Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 242 lines (159 sloc) 7.815 kb
daad9b2 Thomas Schilling 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 Thomas Schilling Document developer's build process in README.
nominolo authored
11 non-Haskell clients such as Emacs (no Vim, volunteers required).
daad9b2 Thomas Schilling Start a README.
nominolo authored
12
13 [home]: http://code.google.com/p/scion-lib/
14
15
16 Installation
17 ============
18
74372e1 Thomas Schilling Document developer's build process in README.
nominolo authored
19 (For developer builds see section "Hacking" below.)
20
daad9b2 Thomas Schilling Start a README.
nominolo authored
21 Scion requires [GHC 6.10.1][ghc] or later. All other dependencies
ab7b94c Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling Start a README.
nominolo authored
34
74372e1 Thomas Schilling Document developer's build process in README.
nominolo authored
35
36
daad9b2 Thomas Schilling Start a README.
nominolo authored
37 Usage
38 =====
39
b28d2de Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling Start a README.
nominolo authored
58
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
nominolo authored
59 Add the following to your emacs configuration (typically "~/.emacs"):
daad9b2 Thomas Schilling Start a README.
nominolo authored
60
61 (add-to-list 'load-path "<scion>/emacs")
62 (require 'scion)
2db8942 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling Update instructions for using Scion with Emacs.
nominolo authored
79
8650e4a Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling Update instructions for using Scion with Emacs.
nominolo authored
111
8035ada Thomas Schilling Update README with more complete descriptions of the currently
nominolo authored
112 ## Completion
daad9b2 Thomas Schilling Start a README.
nominolo authored
113
8035ada Thomas Schilling Update README with more complete descriptions of the currently
nominolo authored
114 The following commands offer completion for a few things.
daad9b2 Thomas Schilling Start a README.
nominolo authored
115
8035ada Thomas Schilling 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 Thomas Schilling Update instructions for using Scion with Emacs.
nominolo authored
145
8035ada Thomas Schilling 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 Thomas Schilling 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 Thomas Schilling Start a README.
nominolo authored
165
166 Bug Reports
167 ===========
168
169 Please send bug reports or feature requests to the [Issue tracker][issues].
170
171 [issues]: http://code.google.com/p/scion-lib/issues/list
172
50099db Thomas Schilling Add link to mailing list to README.
nominolo authored
173 Discussion
174 ==========
175
96ce6f2 Thomas Schilling Github's markdown implementation is buggy... grrr..
nominolo authored
176 For discussions about Scion use the [scion-lib-devel][ml] mailing list.
50099db Thomas Schilling Add link to mailing list to README.
nominolo authored
177
96ce6f2 Thomas Schilling Github's markdown implementation is buggy... grrr..
nominolo authored
178 [ml]: http://groups.google.com/group/scion-lib-devel
50099db Thomas Schilling Add link to mailing list to README.
nominolo authored
179
daad9b2 Thomas Schilling Start a README.
nominolo authored
180
181 Hacking
182 =======
183
ab7b94c Thomas Schilling Fix a few more links in the README.
nominolo authored
184 The main repository for Scion is hosted on [Github][gh]. Get it via
daad9b2 Thomas Schilling Start a README.
nominolo authored
185
186 $ git clone git://github.com/nominolo/scion
187
188 Send patches or pull requests to nominolo (email address at googlemail
189 dot com). Note that, if you fork the project on Github your fork
190 won't take up additional space on your account.
191
ab7b94c Thomas Schilling Fix a few more links in the README.
nominolo authored
192 [gh]: http://github.com
74372e1 Thomas Schilling Document developer's build process in README.
nominolo authored
193
194
195 Building
196 --------
197
198 For development it is probably easier to use the GNU make than Cabal
199 directly. The makefile includes a file called `config.mk` which is
200 not present by default. You can use the provided `config.mk.sample`
201 and edit it:
202
203 $ cp config.mk.sample config.mk
204 $ edit config.mk
205
206 After that, the makefile takes care of the rest.
207
208 $ make # configure and build
209 $ make install # configure, build, and install
210
211 If you don't have the dependencies, yet, and have `cabal-install`, the
212 following may be helpful (If it's not in the path, adjust `config.mk`
213 accordingly):
214
215 $ make cabal-install
216
217 (This also installs Scion, but that shouldn't interfere with hacking.)
218
219
220 Using an in-place GHC
221 ---------------------
222
223 GHC 6.10.1 has a couple of problems. For example, not all error
224 messages are reported using the GHC API but instead are printed to
225 stdout/stderr. Some parts also call `exitWith` directly. GHC's HEAD
226 branch has some of these bugs fixed and may contain new features not
227 present in the stable branch. If you want to compile against an
228 inplace GHC, the following steps should work:
229
230 1. On windows, make sure that Cabal finds the inplace gcc
231
f9c2a27 Thomas Schilling Typo and small formatting fixes.
nominolo authored
232 $ cd /path/to/ghc
233 $ cp `which gcc` ghc/
74372e1 Thomas Schilling Document developer's build process in README.
nominolo authored
234
235 (Adjust to version of GCC that GHC was compiled with.)
236
237 2. Set the `GHC_PATH` variable to the correct path to for your
238 system. Make sure *not* to set `HC`, `PKG`, or `HADDOCK`, they
f9c2a27 Thomas Schilling Typo and small formatting fixes.
nominolo authored
239 will automatically be set to point to the inplace versions.
74372e1 Thomas Schilling Document developer's build process in README.
nominolo authored
240
241 3. Use `make` or `make cabal-install` as above.
Something went wrong with that request. Please try again.