Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 252 lines (165 sloc) 7.997 kb
daad9b2f » nominolo
2008-11-12 Start a README.
1
2 Introduction
3 ============
4
5 [Scion][home] is a Haskell library that aims to provide Haskell source
6 code inspection and transformation functionality as well as various
7 other features that may be useful for an IDE.
8
9 Most of Scion's functionality is based on the GHC API. Scion tries to
10 be front-end agnostic; it provides both a Haskell API and servers for
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
11 non-Haskell clients such as Emacs (no Vim, volunteers required).
daad9b2f » nominolo
2008-11-12 Start a README.
12
13 [home]: http://code.google.com/p/scion-lib/
14
15
16 Installation
17 ============
18
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
19 (For developer builds see section "Hacking" below.)
20
daad9b2f » nominolo
2008-11-12 Start a README.
21 Scion requires [GHC 6.10.1][ghc] or later. All other dependencies
ab7b94cc » nominolo
2008-11-14 Fix a few more links in the README.
22 should be on [Hackage][hackage] and can be installed using
23 [cabal-install][ci]:
daad9b2f » nominolo
2008-11-12 Start a README.
24
25 $ cd dir/to/scion
26 $ cabal install
27
28 Scion supports various configuration flags which are useful when
29 working on Scion itself.
30
31 [ghc]: http://haskell.org/ghc/download.html
ab7b94cc » nominolo
2008-11-14 Fix a few more links in the README.
32 [hackage]: http://hackage.haskell.org/packages/hackage.html
33 [ci]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
daad9b2f » nominolo
2008-11-12 Start a README.
34
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
35
36
daad9b2f » nominolo
2008-11-12 Start a README.
37 Usage
38 =====
39
b28d2de6 » nominolo
2009-01-08 Update README slightly
40 Since Scion is a library, you should consult the haddock documentation
41 for how to use it. However, you may look at the Emacs frontend for
42 inspiration.
43
44 The Emacs frontend is implemented as a Haskell server
daad9b2f » nominolo
2008-11-12 Start a README.
45
46 Emacs
47 -----
48
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
49 Install Scion with Emacs support, either via
b28d2de6 » nominolo
2009-01-08 Update README slightly
50
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
51 $ cabal install scion -femacs
52
53 or, if you have a locally copy of Scion
daad9b2f » nominolo
2008-11-12 Start a README.
54
55 $ cd <scion>
56 $ cabal install -femacs
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
57
58 You'll end up with a binary called "emacs-server".
59
daad9b2f » nominolo
2008-11-12 Start a README.
60 $ ./.cabal/bin/emacs_server
61
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
62 Add the following to your emacs configuration (typically "~/.emacs"):
daad9b2f » nominolo
2008-11-12 Start a README.
63
64 (add-to-list 'load-path "<scion>/emacs")
65 (require 'scion)
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
66
67 ;; if ./cabal/bin is not in your $PATH
68 (setq scion-program "~/.cabal/bin/emacs_server")
69
70 (defun my-haskell-hook ()
71 ;; Whenever we open a file in Haskell mode, also activate Scion
72 (scion-mode 1)
73 ;; Whenever a file is saved, immediately type check it and
74 ;; highlight errors/warnings in the source.
75 (scion-flycheck-on-save 1))
76
77 (add-hook 'haskell-mode-hook 'my-haskell-hook)
9b8962b0 » nominolo
2009-04-07 Update README with new key binding and auto-connect magic.
78
79 Scion mode needs to communicate with the external server. By default
80 it will automatically start the server when needed. See "Manually
81 Connecting to Scion" below for how to connect to the server manually.
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
82
8650e4a4 » nominolo
2009-02-19 Document solution to incomplete environment when using `M-x scion`.
83 The scion server process inherits the environment variables from the
84 Emacs process. Depending on your system this may be different than
85 what you'd get if you started the server from the shell. To adjust
86 the `PATH` environment variable from within Emacs, add something like
87 the following to your `.emacs`:
88
89 ;; add ~/usr/bin to the PATH
90 (setenv "PATH" "$HOME/usr/bin:$PATH" t)
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
91
92 Once you have a running and connected Scion server, you can use the
93 commands provided by scion-mode:
94
9b8962b0 » nominolo
2009-04-07 Update README with new key binding and auto-connect magic.
95 * `C-c C-x C-l` (`scion-load`) load the current file with Scion. If
96 the file is within a Cabal project this will prompt to use the
97 settings from one of the components in the package description
98 file. You can still choose to load only the current file using
99 the default settings.
100
040869c7 » nominolo
2009-03-08 Emacs: Change some key bindings and update README accordingly.
101 * `C-c C-o` (`scion-open-cabal-project`) configures a Cabal project
102 and loads the meta-data from a Cabal file. Note that this
103 does not type check or load anything. If you change the Cabal
104 file of a project, call this function to update the session with
105 the new settings.
106
107 If loading generates any errors or warnings, a buffer will appear and
108 list them all. Pressing `RET` on a note will jump to its source
109 location. Pressing `q` closes the buffer, and `C-c C-n`
110 (`scion-list-compiler-notes`) brings it back. Use `M-n`
111 (`scion-next-note-in-buffer`) and `M-p`
112 (`scion-previous-note-in-buffer`) to navigate within the notes of one
113 buffer.
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
114
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
115 ## Completion
daad9b2f » nominolo
2008-11-12 Start a README.
116
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
117 The following commands offer completion for a few things.
daad9b2f » nominolo
2008-11-12 Start a README.
118
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
119 * `C-c i l` (`haskell-insert-language`) asks for a `LANGUAGE` pragma
120 and adds it to the top of the file.
121
122 * `C-c i p` (`haskell-insert-pragma`) inserts a pragma at the
123 current cursor position. (At the moment this doesn't try to make
124 sense of the selected pragma, however.)
125
126 * `C-c i m` (`haskell-insert-module-name`) inserts the name of an
127 external module (external), i.e., a module _not_ from the current
128 package.
129
130 * `C-c i f` (`haskell-insert-flag`) insert (GHC) command line flag
131 at point. (Really only makes sense within an `OPTiONS_GHC` pragma.)
132
133 ## Experimental features
134
135 The following should work most of the cases.
136
137 * `C-c C-.` (`scion-goto-definition`) jumps to the definition of the
138 identifier at point. If there is no identifier at point, offers a
139 list to complete on a particular identifier. This currently only
140 works for identifiers defined within the same project.
141
142 * `C-c C-t` shows type of identifier at point. This only works if
143 the current file typechecks, but then it also works for local
144 identifiers. For polymorphic function it will show the type to
145 which they are _instantiated_, e.g.,
146
147 f x = x + (1::Int)
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
148
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
149 Calling this command on `+` will print `Int -> Int -> Int` instead
150 of `Num a => a -> a -> a`.
9b8962b0 » nominolo
2009-04-07 Update README with new key binding and auto-connect magic.
151
152
153 # Manually Connecting to Scion
154
155 If you set the variable `scion-auto-connect` to `'ask` (the default is
156 `'always`), Scion will ask whether to start the server. If you set it
157 to `nil` you need to manually connect to the server.
158
159 You can start the server manually on the command line and then use
160
161 M-x scion-connect
162
163 to connect to that server. However, most of the time it will be more
164 convenient to start the server from within Emacs:
165
166 M-x scion
167
daad9b2f » nominolo
2008-11-12 Start a README.
168
169 Bug Reports
170 ===========
171
172 Please send bug reports or feature requests to the [Issue tracker][issues].
173
174 [issues]: http://code.google.com/p/scion-lib/issues/list
175
50099dba » nominolo
2008-11-14 Add link to mailing list to README.
176 Discussion
177 ==========
178
96ce6f22 » nominolo
2008-11-14 Github's markdown implementation is buggy... grrr..
179 For discussions about Scion use the [scion-lib-devel][ml] mailing list.
50099dba » nominolo
2008-11-14 Add link to mailing list to README.
180
96ce6f22 » nominolo
2008-11-14 Github's markdown implementation is buggy... grrr..
181 [ml]: http://groups.google.com/group/scion-lib-devel
50099dba » nominolo
2008-11-14 Add link to mailing list to README.
182
daad9b2f » nominolo
2008-11-12 Start a README.
183
184 Hacking
185 =======
186
ab7b94cc » nominolo
2008-11-14 Fix a few more links in the README.
187 The main repository for Scion is hosted on [Github][gh]. Get it via
daad9b2f » nominolo
2008-11-12 Start a README.
188
189 $ git clone git://github.com/nominolo/scion
190
191 Send patches or pull requests to nominolo (email address at googlemail
192 dot com). Note that, if you fork the project on Github your fork
193 won't take up additional space on your account.
194
ab7b94cc » nominolo
2008-11-14 Fix a few more links in the README.
195 [gh]: http://github.com
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
196
197
198 Building
199 --------
200
201 For development it is probably easier to use the GNU make than Cabal
202 directly. The makefile includes a file called `config.mk` which is
203 not present by default. You can use the provided `config.mk.sample`
204 and edit it:
205
206 $ cp config.mk.sample config.mk
207 $ edit config.mk
208
209 After that, the makefile takes care of the rest.
210
211 $ make # configure and build
212 $ make install # configure, build, and install
213
214 If you don't have the dependencies, yet, and have `cabal-install`, the
215 following may be helpful (If it's not in the path, adjust `config.mk`
216 accordingly):
217
218 $ make cabal-install
219
220 (This also installs Scion, but that shouldn't interfere with hacking.)
221
222
223 Using an in-place GHC
224 ---------------------
225
226 GHC 6.10.1 has a couple of problems. For example, not all error
227 messages are reported using the GHC API but instead are printed to
228 stdout/stderr. Some parts also call `exitWith` directly. GHC's HEAD
229 branch has some of these bugs fixed and may contain new features not
230 present in the stable branch. If you want to compile against an
231 inplace GHC, the following steps should work:
232
233 1. On windows, make sure that Cabal finds the inplace gcc
234
f9c2a27a » nominolo
2008-12-08 Typo and small formatting fixes.
235 $ cd /path/to/ghc
236 $ cp `which gcc` ghc/
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
237
238 (Adjust to version of GCC that GHC was compiled with.)
239
240 2. Set the `GHC_PATH` variable to the correct path to for your
241 system. Make sure *not* to set `HC`, `PKG`, or `HADDOCK`, they
f9c2a27a » nominolo
2008-12-08 Typo and small formatting fixes.
242 will automatically be set to point to the inplace versions.
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
243
244 3. Use `make` or `make cabal-install` as above.
d115e993 » MarcWeber
2009-01-22 Added another markdown item ("Known Pitfalls").
245
246
247
248 KNOWN PITFALLS
249 ------------------------------
250 If you get an error message like this:
251 "scion_server: mkTopLevEnv: not interpreted main:Main"
252 then you should rm [Ss]etup.hi [Ss]etup.o in the project directory.
Something went wrong with that request. Please try again.