Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 241 lines (159 sloc) 7.815 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
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
23 [cabal-install][ci] in the lib directory:
daad9b2f » nominolo
2008-11-12 Start a README.
24
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
25 $ cd dir/to/scion/lib
daad9b2f » nominolo
2008-11-12 Start a README.
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
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
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.
daad9b2f » nominolo
2008-11-12 Start a README.
46
47 Emacs
48 -----
49
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
50 Install Scion with Emacs support:
b28d2de6 » nominolo
2009-01-08 Update README slightly
51
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
52 $ cd dir/to/scion/server
53 $ cabal install
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
54
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
55 You'll end up with a binary called "scion_server".
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
56
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
57 $ ~/.cabal/bin/scion_server
daad9b2f » nominolo
2008-11-12 Start a README.
58
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
59 Add the following to your emacs configuration (typically "~/.emacs"):
daad9b2f » nominolo
2008-11-12 Start a README.
60
61 (add-to-list 'load-path "<scion>/emacs")
62 (require 'scion)
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
63
64 ;; if ./cabal/bin is not in your $PATH
7012684e » Thomas ten Cate
2009-06-02 updated the readme to match the new build system
65 (setq scion-program "~/.cabal/bin/scion_server")
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
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)
9b8962b0 » nominolo
2009-04-07 Update README with new key binding and auto-connect magic.
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.
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
79
8650e4a4 » nominolo
2009-02-19 Document solution to incomplete environment when using `M-x scion`.
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)
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
88
89 Once you have a running and connected Scion server, you can use the
90 commands provided by scion-mode:
91
9b8962b0 » nominolo
2009-04-07 Update README with new key binding and auto-connect magic.
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
040869c7 » nominolo
2009-03-08 Emacs: Change some key bindings and update README accordingly.
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.
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
111
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
112 ## Completion
daad9b2f » nominolo
2008-11-12 Start a README.
113
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
114 The following commands offer completion for a few things.
daad9b2f » nominolo
2008-11-12 Start a README.
115
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
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)
2db8942e » nominolo
2009-02-19 Update instructions for using Scion with Emacs.
145
8035adaa » nominolo
2009-04-20 Update README with more complete descriptions of the currently
146 Calling this command on `+` will print `Int -> Int -> Int` instead
147 of `Num a => a -> a -> a`.
9b8962b0 » nominolo
2009-04-07 Update README with new key binding and auto-connect magic.
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
daad9b2f » nominolo
2008-11-12 Start a README.
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
50099dba » nominolo
2008-11-14 Add link to mailing list to README.
173 Discussion
174 ==========
175
96ce6f22 » nominolo
2008-11-14 Github's markdown implementation is buggy... grrr..
176 For discussions about Scion use the [scion-lib-devel][ml] mailing list.
50099dba » nominolo
2008-11-14 Add link to mailing list to README.
177
96ce6f22 » nominolo
2008-11-14 Github's markdown implementation is buggy... grrr..
178 [ml]: http://groups.google.com/group/scion-lib-devel
50099dba » nominolo
2008-11-14 Add link to mailing list to README.
179
daad9b2f » nominolo
2008-11-12 Start a README.
180
181 Hacking
182 =======
183
ab7b94cc » nominolo
2008-11-14 Fix a few more links in the README.
184 The main repository for Scion is hosted on [Github][gh]. Get it via
daad9b2f » nominolo
2008-11-12 Start a README.
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
ab7b94cc » nominolo
2008-11-14 Fix a few more links in the README.
192 [gh]: http://github.com
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
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
f9c2a27a » nominolo
2008-12-08 Typo and small formatting fixes.
232 $ cd /path/to/ghc
233 $ cp `which gcc` ghc/
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
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
f9c2a27a » nominolo
2008-12-08 Typo and small formatting fixes.
239 will automatically be set to point to the inplace versions.
74372e17 » nominolo
2008-12-08 Document developer's build process in README.
240
241 3. Use `make` or `make cabal-install` as above.
Something went wrong with that request. Please try again.