Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 220 lines (143 sloc) 6.726 kb
daad9b2 Thomas Schilling Start a README.
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.
authored
11 non-Haskell clients such as Emacs (no Vim, volunteers required).
daad9b2 Thomas Schilling Start a README.
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.
authored
19 (For developer builds see section "Hacking" below.)
20
daad9b2 Thomas Schilling Start a README.
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.
authored
22 should be on [Hackage][hackage] and can be installed using
23 [cabal-install][ci]:
daad9b2 Thomas Schilling Start a README.
authored
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 Thomas Schilling Fix a few more links in the README.
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.
authored
34
74372e1 Thomas Schilling Document developer's build process in README.
authored
35
36
daad9b2 Thomas Schilling Start a README.
authored
37 Usage
38 =====
39
b28d2de Thomas Schilling Update README slightly
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
44 The Emacs frontend is implemented as a Haskell server
daad9b2 Thomas Schilling Start a README.
authored
45
46 Emacs
47 -----
48
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
authored
49 Install Scion with Emacs support, either via
b28d2de Thomas Schilling Update README slightly
authored
50
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
authored
51 $ cabal install scion -femacs
52
53 or, if you have a locally copy of Scion
daad9b2 Thomas Schilling Start a README.
authored
54
55 $ cd <scion>
56 $ cabal install -femacs
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
authored
57
58 You'll end up with a binary called "emacs-server".
59
daad9b2 Thomas Schilling Start a README.
authored
60 $ ./.cabal/bin/emacs_server
61
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
authored
62 Add the following to your emacs configuration (typically "~/.emacs"):
daad9b2 Thomas Schilling Start a README.
authored
63
64 (add-to-list 'load-path "<scion>/emacs")
65 (require 'scion)
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
authored
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 Thomas Schilling Update README with new key binding and auto-connect magic.
authored
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 Thomas Schilling Update instructions for using Scion with Emacs.
authored
82
8650e4a Thomas Schilling Document solution to incomplete environment when using `M-x scion`.
authored
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 Thomas Schilling Update instructions for using Scion with Emacs.
authored
91
92 Once you have a running and connected Scion server, you can use the
93 commands provided by scion-mode:
94
9b8962b Thomas Schilling Update README with new key binding and auto-connect magic.
authored
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 Thomas Schilling Emacs: Change some key bindings and update README accordingly.
authored
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 Thomas Schilling Update instructions for using Scion with Emacs.
authored
114
115 There are a few more utilities:
daad9b2 Thomas Schilling Start a README.
authored
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 Thomas Schilling Update README with new key binding and auto-connect magic.
authored
120 C-c i f -- insert command line flag
daad9b2 Thomas Schilling Start a README.
authored
121
2db8942 Thomas Schilling Update instructions for using Scion with Emacs.
authored
122 Some experimental features:
123
124 C-c C-t -- show type of identifier at point
9b8962b Thomas Schilling Update README with new key binding and auto-connect magic.
authored
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 Thomas Schilling Start a README.
authored
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 Thomas Schilling Add link to mailing list to README.
authored
151 Discussion
152 ==========
153
96ce6f2 Thomas Schilling Github's markdown implementation is buggy... grrr..
authored
154 For discussions about Scion use the [scion-lib-devel][ml] mailing list.
50099db Thomas Schilling Add link to mailing list to README.
authored
155
96ce6f2 Thomas Schilling Github's markdown implementation is buggy... grrr..
authored
156 [ml]: http://groups.google.com/group/scion-lib-devel
50099db Thomas Schilling Add link to mailing list to README.
authored
157
daad9b2 Thomas Schilling Start a README.
authored
158
159 Hacking
160 =======
161
ab7b94c Thomas Schilling Fix a few more links in the README.
authored
162 The main repository for Scion is hosted on [Github][gh]. Get it via
daad9b2 Thomas Schilling Start a README.
authored
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 Thomas Schilling Fix a few more links in the README.
authored
170 [gh]: http://github.com
74372e1 Thomas Schilling Document developer's build process in README.
authored
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 Thomas Schilling Typo and small formatting fixes.
authored
210 $ cd /path/to/ghc
211 $ cp `which gcc` ghc/
74372e1 Thomas Schilling Document developer's build process in README.
authored
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 Thomas Schilling Typo and small formatting fixes.
authored
217 will automatically be set to point to the inplace versions.
74372e1 Thomas Schilling Document developer's build process in README.
authored
218
219 3. Use `make` or `make cabal-install` as above.
Something went wrong with that request. Please try again.