Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 196 lines (125 sloc) 5.66 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
23 [cabal-install][ci]:
daad9b2 @nominolo Start a README.
nominolo 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 @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
44 The Emacs frontend is implemented as a Haskell server
daad9b2 @nominolo Start a README.
nominolo authored
45
46 Emacs
47 -----
48
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
49 Install Scion with Emacs support, either via
b28d2de @nominolo Update README slightly
nominolo authored
50
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
51 $ cabal install scion -femacs
52
53 or, if you have a locally copy of Scion
daad9b2 @nominolo Start a README.
nominolo authored
54
55 $ cd <scion>
56 $ cabal install -femacs
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
57
58 You'll end up with a binary called "emacs-server".
59
daad9b2 @nominolo Start a README.
nominolo authored
60 $ ./.cabal/bin/emacs_server
61
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
62 Add the following to your emacs configuration (typically "~/.emacs"):
daad9b2 @nominolo Start a README.
nominolo authored
63
64 (add-to-list 'load-path "<scion>/emacs")
65 (require 'scion)
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo 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)
78
79 Scion mode needs to communicate with the external server. You can
80 start the server manually on the command line and then use
81
daad9b2 @nominolo Start a README.
nominolo authored
82 M-x scion-connect
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
83
84 to connect to that server. However, most of the time it will be more
85 convenient to start the server from within Emacs:
86
87 M-x scion
88
8650e4a @nominolo Document solution to incomplete environment when using `M-x scion`.
nominolo authored
89 The scion server process inherits the environment variables from the
90 Emacs process. Depending on your system this may be different than
91 what you'd get if you started the server from the shell. To adjust
92 the `PATH` environment variable from within Emacs, add something like
93 the following to your `.emacs`:
94
95 ;; add ~/usr/bin to the PATH
96 (setenv "PATH" "$HOME/usr/bin:$PATH" t)
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
97
98 Once you have a running and connected Scion server, you can use the
99 commands provided by scion-mode:
100
101 * `M-x scion-open-cabal-project` (`C-c C-o`) configures a .cabal
102 project and loads the meta-data from a .cabal file. Note that
103 this doesn't type check or load anything. If you change the
104 .cabal file of a project, call this function to update the session
105 with the new settings.
106
107 * `M-x scion-load-library` (`C-c C-l`) type checks all the files in
108 the library.
109
110 There are a few more utilities:
daad9b2 @nominolo Start a README.
nominolo authored
111
112 C-c i l -- insert language pragma
113 C-c i p -- insert pragma
114 C-c i m -- insert (external) module name
115
2db8942 @nominolo Update instructions for using Scion with Emacs.
nominolo authored
116 Some experimental features:
117
118 C-c C-t -- show type of identifier at point
daad9b2 @nominolo Start a README.
nominolo authored
119
120 Bug Reports
121 ===========
122
123 Please send bug reports or feature requests to the [Issue tracker][issues].
124
125 [issues]: http://code.google.com/p/scion-lib/issues/list
126
50099db @nominolo Add link to mailing list to README.
nominolo authored
127 Discussion
128 ==========
129
96ce6f2 @nominolo Github's markdown implementation is buggy... grrr..
nominolo authored
130 For discussions about Scion use the [scion-lib-devel][ml] mailing list.
50099db @nominolo Add link to mailing list to README.
nominolo authored
131
96ce6f2 @nominolo Github's markdown implementation is buggy... grrr..
nominolo authored
132 [ml]: http://groups.google.com/group/scion-lib-devel
50099db @nominolo Add link to mailing list to README.
nominolo authored
133
daad9b2 @nominolo Start a README.
nominolo authored
134
135 Hacking
136 =======
137
ab7b94c @nominolo Fix a few more links in the README.
nominolo authored
138 The main repository for Scion is hosted on [Github][gh]. Get it via
daad9b2 @nominolo Start a README.
nominolo authored
139
140 $ git clone git://github.com/nominolo/scion
141
142 Send patches or pull requests to nominolo (email address at googlemail
143 dot com). Note that, if you fork the project on Github your fork
144 won't take up additional space on your account.
145
ab7b94c @nominolo Fix a few more links in the README.
nominolo authored
146 [gh]: http://github.com
74372e1 @nominolo Document developer's build process in README.
nominolo authored
147
148
149 Building
150 --------
151
152 For development it is probably easier to use the GNU make than Cabal
153 directly. The makefile includes a file called `config.mk` which is
154 not present by default. You can use the provided `config.mk.sample`
155 and edit it:
156
157 $ cp config.mk.sample config.mk
158 $ edit config.mk
159
160 After that, the makefile takes care of the rest.
161
162 $ make # configure and build
163 $ make install # configure, build, and install
164
165 If you don't have the dependencies, yet, and have `cabal-install`, the
166 following may be helpful (If it's not in the path, adjust `config.mk`
167 accordingly):
168
169 $ make cabal-install
170
171 (This also installs Scion, but that shouldn't interfere with hacking.)
172
173
174 Using an in-place GHC
175 ---------------------
176
177 GHC 6.10.1 has a couple of problems. For example, not all error
178 messages are reported using the GHC API but instead are printed to
179 stdout/stderr. Some parts also call `exitWith` directly. GHC's HEAD
180 branch has some of these bugs fixed and may contain new features not
181 present in the stable branch. If you want to compile against an
182 inplace GHC, the following steps should work:
183
184 1. On windows, make sure that Cabal finds the inplace gcc
185
f9c2a27 @nominolo Typo and small formatting fixes.
nominolo authored
186 $ cd /path/to/ghc
187 $ cp `which gcc` ghc/
74372e1 @nominolo Document developer's build process in README.
nominolo authored
188
189 (Adjust to version of GCC that GHC was compiled with.)
190
191 2. Set the `GHC_PATH` variable to the correct path to for your
192 system. Make sure *not* to set `HC`, `PKG`, or `HADDOCK`, they
f9c2a27 @nominolo Typo and small formatting fixes.
nominolo authored
193 will automatically be set to point to the inplace versions.
74372e1 @nominolo Document developer's build process in README.
nominolo authored
194
195 3. Use `make` or `make cabal-install` as above.
Something went wrong with that request. Please try again.