Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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