Skip to content
Newer
Older
100644 220 lines (143 sloc) 6.57 KB
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
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 Dec 8, 2008
11 non-Haskell clients such as Emacs (no Vim, volunteers required).
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
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 Dec 8, 2008
19 (For developer builds see section "Hacking" below.)
20
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
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 Nov 14, 2008
22 should be on [Hackage][hackage] and can be installed using
23 [cabal-install][ci]:
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
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
ab7b94c @nominolo Fix a few more links in the README.
nominolo authored Nov 14, 2008
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 Nov 12, 2008
34
74372e1 @nominolo Document developer's build process in README.
nominolo authored Dec 8, 2008
35
36
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
37 Usage
38 =====
39
b28d2de @nominolo Update README slightly
nominolo authored Jan 8, 2009
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
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
45
46 Emacs
47 -----
48
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
49 Install Scion with Emacs support, either via
b28d2de @nominolo Update README slightly
nominolo authored Jan 8, 2009
50
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
51 $ cabal install scion -femacs
52
53 or, if you have a locally copy of Scion
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
54
55 $ cd <scion>
56 $ cabal install -femacs
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
57
58 You'll end up with a binary called "emacs-server".
59
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
60 $ ./.cabal/bin/emacs_server
61
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
62 Add the following to your emacs configuration (typically "~/.emacs"):
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
63
64 (add-to-list 'load-path "<scion>/emacs")
65 (require 'scion)
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
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)
9b8962b @nominolo Update README with new key binding and auto-connect magic.
nominolo authored Apr 7, 2009
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.
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
82
8650e4a @nominolo Document solution to incomplete environment when using `M-x scion`.
nominolo authored Feb 19, 2009
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)
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
91
92 Once you have a running and connected Scion server, you can use the
93 commands provided by scion-mode:
94
9b8962b @nominolo Update README with new key binding and auto-connect magic.
nominolo authored Apr 7, 2009
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
040869c @nominolo Emacs: Change some key bindings and update README accordingly.
nominolo authored Mar 8, 2009
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.
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
114
115 There are a few more utilities:
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
116
117 C-c i l -- insert language pragma
118 C-c i p -- insert pragma
119 C-c i m -- insert (external) module name
9b8962b @nominolo Update README with new key binding and auto-connect magic.
nominolo authored Apr 7, 2009
120 C-c i f -- insert command line flag
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
121
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored Feb 19, 2009
122 Some experimental features:
123
124 C-c C-t -- show type of identifier at point
9b8962b @nominolo Update README with new key binding and auto-connect magic.
nominolo authored Apr 7, 2009
125 (currently only works on ids, not expressions)
126
127
128 # Manually Connecting to Scion
129
130 If you set the variable `scion-auto-connect` to `'ask` (the default is
131 `'always`), Scion will ask whether to start the server. If you set it
132 to `nil` you need to manually connect to the server.
133
134 You can start the server manually on the command line and then use
135
136 M-x scion-connect
137
138 to connect to that server. However, most of the time it will be more
139 convenient to start the server from within Emacs:
140
141 M-x scion
142
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
143
144 Bug Reports
145 ===========
146
147 Please send bug reports or feature requests to the [Issue tracker][issues].
148
149 [issues]: http://code.google.com/p/scion-lib/issues/list
150
50099db @nominolo Add link to mailing list to README.
nominolo authored Nov 14, 2008
151 Discussion
152 ==========
153
96ce6f2 @nominolo Github's markdown implementation is buggy... grrr..
nominolo authored Nov 14, 2008
154 For discussions about Scion use the [scion-lib-devel][ml] mailing list.
50099db @nominolo Add link to mailing list to README.
nominolo authored Nov 14, 2008
155
96ce6f2 @nominolo Github's markdown implementation is buggy... grrr..
nominolo authored Nov 14, 2008
156 [ml]: http://groups.google.com/group/scion-lib-devel
50099db @nominolo Add link to mailing list to README.
nominolo authored Nov 14, 2008
157
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
158
159 Hacking
160 =======
161
ab7b94c @nominolo Fix a few more links in the README.
nominolo authored Nov 14, 2008
162 The main repository for Scion is hosted on [Github][gh]. Get it via
daad9b2 @nominolo Start a README.
nominolo authored Nov 12, 2008
163
164 $ git clone git://github.com/nominolo/scion
165
166 Send patches or pull requests to nominolo (email address at googlemail
167 dot com). Note that, if you fork the project on Github your fork
168 won't take up additional space on your account.
169
ab7b94c @nominolo Fix a few more links in the README.
nominolo authored Nov 14, 2008
170 [gh]: http://github.com
74372e1 @nominolo Document developer's build process in README.
nominolo authored Dec 8, 2008
171
172
173 Building
174 --------
175
176 For development it is probably easier to use the GNU make than Cabal
177 directly. The makefile includes a file called `config.mk` which is
178 not present by default. You can use the provided `config.mk.sample`
179 and edit it:
180
181 $ cp config.mk.sample config.mk
182 $ edit config.mk
183
184 After that, the makefile takes care of the rest.
185
186 $ make # configure and build
187 $ make install # configure, build, and install
188
189 If you don't have the dependencies, yet, and have `cabal-install`, the
190 following may be helpful (If it's not in the path, adjust `config.mk`
191 accordingly):
192
193 $ make cabal-install
194
195 (This also installs Scion, but that shouldn't interfere with hacking.)
196
197
198 Using an in-place GHC
199 ---------------------
200
201 GHC 6.10.1 has a couple of problems. For example, not all error
202 messages are reported using the GHC API but instead are printed to
203 stdout/stderr. Some parts also call `exitWith` directly. GHC's HEAD
204 branch has some of these bugs fixed and may contain new features not
205 present in the stable branch. If you want to compile against an
206 inplace GHC, the following steps should work:
207
208 1. On windows, make sure that Cabal finds the inplace gcc
209
f9c2a27 @nominolo Typo and small formatting fixes.
nominolo authored Dec 8, 2008
210 $ cd /path/to/ghc
211 $ cp `which gcc` ghc/
74372e1 @nominolo Document developer's build process in README.
nominolo authored Dec 8, 2008
212
213 (Adjust to version of GCC that GHC was compiled with.)
214
215 2. Set the `GHC_PATH` variable to the correct path to for your
216 system. Make sure *not* to set `HC`, `PKG`, or `HADDOCK`, they
f9c2a27 @nominolo Typo and small formatting fixes.
nominolo authored Dec 8, 2008
217 will automatically be set to point to the inplace versions.
74372e1 @nominolo Document developer's build process in README.
nominolo authored Dec 8, 2008
218
219 3. Use `make` or `make cabal-install` as above.
Something went wrong with that request. Please try again.