@@ -3,32 +3,43 @@
33Our vision is that you should build an IDE by combining:
44
55* [`hie-bios`](https://github.com/mpickering/hie-bios) for determining where your files are, what are their dependencies, what extensions are enabled and so on;
6−* `hie-core` (i.e. this library) for defining how to type check, when to type check, and producing messages;
7−* [`haskell-lsp`](https://github.com/alanz/haskell-lsp) for sending those messages to an LSP ([Language Server Protocol](https://microsoft.github.io/language-server-protocol/)) server;
8−* A [VS Code extension](https://code.visualstudio.com/api), e.g. `extension` in this directory (although the above components enable Haskell IDE features in other editors too).
6+* `hie-core` (i.e. this library) for defining how to type check, when to type check, and producing diagnostic messages;
7+* A bunch of plugins that haven't yet been written, e.g. [`hie-hlint`](https://github.com/ndmitchell/hlint) and [`hie-ormolu`](https://github.com/tweag/ormolu) for your specific choices of plugin;
8+* [`haskell-lsp`](https://github.com/alanz/haskell-lsp) for sending those messages to a [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) server;
9+* An extension for your editor. We provide a [VS Code extension](https://code.visualstudio.com/api) as `extension` in this directory, although the components work in other LSP editors too (see below for instructions using Emacs).
910
1011There are more details about our approach [in this blog post](https://4ta.uk/p/shaking-up-the-ide).
1112
1213## How to use it
1314
14−### VS Code
15−
16−#### Installing the binary
15+First install the `hie-core` binary using `stack` or `cabal`, e.g.
1716
18171. `git clone https://github.com/digital-asset/daml.git`
19182. `cd daml/compiler/hie-core`
20−3. `stack build`
19+3. `cabal install` or `stack install` (and make sure `~/.local/bin` is on your `$PATH`)
20+
21+It's important that `hie-core` is compiled with the same compiler you use to build your projects.
22+
23+Next, check that `hie-bios` is able to load your project. This step is currently a bit difficult.
24+
25+Next, set up an extension for your editor.
2126
22−#### Installing the VSCode extension
27+### Using with VS Code
28+
29+Install the VS code extension
2330
24311. `cd compiler/hie-core/extension`
25322. `npm ci`
26−3. `vsce package`
27−4. `code --install-extension hie-core-0.0.1.vsix`
33+3. `npm install vsce --global` (may require `sudo`)
34+4. `vsce package`
35+5. `code --install-extension hie-core-0.0.1.vsix`
36+
37+Now openning a `.hs` file should work with `hie-core`.
2838
2939### Emacs
3040
3141The frst step is to install required Emacs packages. If you don't already have [Melpa](https://melpa.org/#/) package installation configured in your `.emacs`, put this stanza at the top.
42+
3243```elisp
3344;;Melpa packages support
3445(require 'package)
@@ -51,14 +62,17 @@ There are two things you can do about this warning:
5162(package-initialize)
5263;; Remember : to avoid package-not-found errors, refresh the package
5364;; database now and then with M-x package-refresh-contents.
54− ```
65+```
66+
5567When this is in your `.emacs` and evaluated, `M-x package-refresh-contents` to get the package database downloaded and then `M-x package-list-packages` to display the available packages. Click on a package to install it. You'll need to install the following packages:
56− - `lsp-haskell`
57− - `lsp-ui`
58− - `flycheck`
59− - `yasnippet`
6068
61−When done with this, add the following lines to your `.emacs` :
69+* `lsp-haskell`
70+* `lsp-ui`
71+* `flycheck`
72+* `yasnippet`
73+
74+When done with this, add the following lines to your `.emacs`:
75+
6276```elisp
6377;; LSP support for Haskell
6478(require 'lsp)
@@ -70,6 +84,7 @@ When done with this, add the following lines to your `.emacs` :
7084```
7185
7286Optionally, you may wish to add the following conveniences:
87+
7388```elisp
7489;; Enable LSP logging (helpful for debugging)
7590(setq lsp-log-io t)
@@ -79,10 +94,12 @@ Optionally, you may wish to add the following conveniences:
7994(define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error)
8095```
8196
82−Next stop is to build `hie-core`. In the `daml` repository, navigate to `//compiler/hie-core` and invoked `stack build`. This will install the `hie-core` executable into a location along the lines of `$HOME/path/to/daml/compiler/hie-core/.stack-work/install/x86_64-osx/nightly-2019-05-20/8.6.5/bin/hie-core`. You want to get this executable in your `$PATH`. I achieved this with a command like `ln -s ~/path/to/compiler/hie-core/.stack-work/install/x86_64-osx/nightly-2019-05-20/8.6.5/bin/hie-core ~/.local/bin/hie-core` (because `~/.local/bin` is put into my `PATH` in my `~/.bashrc`).
97+### Testing
98+
99+For testing, I've been using the `ghc-lib-gen` target of the [`ghc-lib` project](https://github.com/digital-asset/ghc-lib). Navigate to the root of `ghc-lib` and create an `hie.yaml` file with contents
83100
84−Time to test things out. It's important to note that for this to work, your programs need to be compiled with the same compiler used to build `hie-core`. For testing, I've been using the `ghc-lib-gen` target of the [`ghc-lib` project](https://github.com/digital-asset/ghc-lib). Navigate to the root of `ghc-lib` and create an `hie.yaml` file with contents
85101```yaml
86102cradle: {cabal: {component: "exe:ghc-lib-gen"}}
87103```
88−Invoke `cabal new-configure -w ~/.stack/programs/~/.stack/programs/x86_64-osx/ghc-8.6.5/bin/ghc` (this is the `ghc` used by `stack` to build `hie-core` - consult `//compiler/hie-core/stack.yaml` to help work out what you should write here). This last step will create a file `cabal.project.local` with contents pointing `cabal` to use the desired `ghc`. You can build `ghc-lib-gen` from the `ghc-lib` directory with the command `cabal new-build` as you like. After creating `cabal.project.local`, you should be all set. Open `ghc-lib/ghc-lib-gen/src/Main.hs` in an Emacs buffer and, for example, hover should bring up type/definition info.
104+
105+Invoke `cabal new-configure -w ~/.stack/programs/~/.stack/programs/x86_64-osx/ghc-8.6.5/bin/ghc` (this is the `ghc` used by `stack` to build `hie-core` - consult `//compiler/hie-core/stack.yaml` to help work out what you should write here). This last step will create a file `cabal.project.local` with contents pointing `cabal` to use the desired `ghc`. You can build `ghc-lib-gen` from the `ghc-lib` directory with the command `cabal new-build` as you like. After creating `cabal.project.local`, you should be all set. Open `ghc-lib/ghc-lib-gen/src/Main.hs` in a buffer and, for example, hover should bring up type/definition info.