Skip to content

Commit 0d5c5d4

Browse files
jneirajneira
authored
Merge pull request #112 from jneira/port-hie-readme
Port hie README partially: mainly "install from source" instructions and "project configuration"
2 parents 0a2be76 + 1eba1b0 commit 0d5c5d4

File tree

2 files changed

+271
-4
lines changed

2 files changed

+271
-4
lines changed

Diff for: ‎README.md

+269-3
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,277 @@ background](https://neilmitchell.blogspot.com/2020/01/one-haskell-ide-to-rule-th
1414

1515
This is *very* early stage software.
1616

17-
To play along at home, do a recursive `git clone`.
17+
- [Haskell Language Server (HLS)](#haskell-language-server)
18+
- [Installation](#installation)
19+
- [Installation from source](#installation-from-source)
20+
- [Common pre-requirements](#common-pre-requirements)
21+
- [Linux-specific pre-requirements](#linux-specific-pre-requirements)
22+
- [Windows-specific pre-requirements](#windows-specific-pre-requirements)
23+
- [Download the source code](#download-the-source-code)
24+
- [Building](#building)
25+
- [Install via cabal](#install-via-cabal)
26+
- [Install specific GHC Version](#install-specific-ghc-version)
27+
- [Project Configuration](#project-configuration)
28+
- [Contributing](#contributing)
29+
- [It's time to join the project!](#its-time-to-join-the-project)
1830

19-
Initial effort is to understand how plugins can be supported in a modular way.
31+
## Installation
2032

21-
Builds with stack and cabal, using GHC 8.6.5
33+
For now only installation from source is supported.
34+
35+
### Installation from source
36+
37+
#### Common pre-requirements
38+
39+
- `stack` or `cabal` must be in your PATH
40+
- You need stack version >= 2.1.1 or cabal >= 2.4.0.0
41+
- `git` must be in your PATH
42+
- The directory where `stack`or `cabal` put the binaries must be in you PATH:
43+
- For stack you can get it with `stack path --local-bin`
44+
- For cabal it is by default `$HOME/.cabal/bin` in linux and `%APPDATA%\cabal\bin` in windows.
45+
46+
Tip: you can quickly check if some command is in your path by running the command.
47+
If you receive some meaningful output instead of "command not found"-like message
48+
then it means you have the command in PATH.
49+
50+
#### Linux-specific pre-requirements
51+
52+
On Linux you will need install a couple of extra libraries (for Unicode ([ICU](http://site.icu-project.org/)) and [NCURSES](https://www.gnu.org/software/ncurses/)):
53+
54+
**Debian 9/Ubuntu 18.04 or earlier**:
55+
56+
```bash
57+
sudo apt install libicu-dev libtinfo-dev libgmp-dev
58+
```
59+
60+
**Debian 10/Ubuntu 18.10 or later**:
61+
62+
```bash
63+
sudo apt install libicu-dev libncurses-dev libgmp-dev
64+
```
65+
66+
**Fedora**:
67+
68+
```bash
69+
sudo dnf install libicu-devel ncurses-devel # also zlib-devel if not already installed
70+
```
71+
72+
#### Windows-specific pre-requirements
73+
74+
In order to avoid problems with long paths on Windows you can do either one of the following:
75+
76+
1. Clone the `haskell-language-server` to a short path, for example the root of your logical drive (e.g. to
77+
`C:\hls`). Even if you choose `C:\haskell-language-server` you could hit the problem. If this doesn't work or you want to use a longer path, try the second option.
78+
79+
2. If the `Local Group Policy Editor` is available on your system, go to: `Local Computer Policy -> Computer Configuration -> Administrative Templates -> System -> Filesystem` set `Enable Win32 long paths` to `Enabled`. If you don't have the policy editor you can use regedit by using the following instructions [here](https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#enable-long-paths-in-windows-10-version-1607-and-later). You also need to configure git to allow longer paths by using unicode paths. To set this for all your git repositories use `git config --system core.longpaths true` (you probably need an administrative shell for this) or for just this one repository use `git config core.longpaths true`.
80+
81+
In addition make sure `haskell-language-server.exe` is not running by closing your editor, otherwise in case of an upgrade the executable can not be installed.
82+
83+
#### Download the source code
84+
85+
```bash
86+
git clone https://github.com/haskell/haskell-language-server --recurse-submodules
87+
cd haskell-language-server
88+
```
89+
90+
#### Building
91+
92+
Note, on first invocation of the build script with stack, a GHC is being installed for execution.
93+
The GHC used for the `install.hs` can be adjusted in `./install/shake.yaml` by using a different resolver.
94+
95+
Available commands can be seen with:
96+
97+
```bash
98+
stack ./install.hs help
99+
```
100+
101+
Remember, this will take time to download a Stackage-LTS and an appropriate GHC for build
102+
haskell-language-server the first time.
103+
104+
##### Install via cabal
105+
106+
The install-script can be invoked via `cabal` instead of `stack` with the command
107+
108+
```bash
109+
cabal v2-run ./install.hs --project-file install/shake.project <target>
110+
```
111+
112+
or using the existing alias script
113+
114+
```bash
115+
./cabal-hls-install <target>
116+
```
117+
118+
Running the script with cabal on windows requires a cabal version greater or equal to `3.0.0.0`.
119+
120+
For brevity, only the `stack`-based commands are presented in the following sections.
121+
122+
##### Install specific GHC Version
123+
124+
Install haskell-language-server for the latest available and supported GHC version (and hoogle docs):
125+
126+
```bash
127+
stack ./install.hs hls
128+
```
129+
130+
Install haskell-language-server for a specific GHC version (and hoogle docs):
131+
132+
```bash
133+
stack ./install.hs hls-8.8.3
134+
stack ./install.hs data
135+
```
136+
137+
The Haskell Language Server can also be built with `cabal v2-build` instead of `stack build`.
138+
This has the advantage that you can decide how the GHC versions have been installed.
139+
To see what GHC versions are available, the command `cabal-hls-install ghcs` can be used.
140+
It will list all *supported* GHC versions that are on the path for build with their respective installation directory.
141+
If you think, this list is incomplete, you can try to modify the PATH variable, such that the executables can be found.
142+
Note, that the targets `hls` and `data` depend on the found GHC versions.
143+
144+
An example output is:
145+
146+
```bash
147+
> ./cabal-hls-install ghcs
148+
******************************************************************
149+
Found the following GHC paths:
150+
ghc-8.6.5: /opt/bin/ghc-8.6.5
151+
ghc-8.8.3: /opt/bin/ghc-8.8.3
152+
153+
******************************************************************
154+
```
155+
156+
If your desired ghc has been found, you use it to install haskell-language-server.
157+
158+
```bash
159+
./cabal-hls-install hls-8.6.5
160+
./cabal-hls-install data
161+
```
162+
163+
## Project Configuration
164+
165+
**For a full explanation of possible configurations, refer to [hie-bios/README](https://github.com/mpickering/hie-bios/blob/master/README.md).**
166+
167+
haskell-language-server has some limited support via hie-bios to detect automatically
168+
your project configuration and set up the environment for GHC.
169+
The plan is to improve it to handle most use cases.
170+
171+
However, for now, the more reliable way is using a `hie.yaml` file in the root
172+
of the workspace to **explicitly** describe how to setup the environment.
173+
For that you need to know what *components* have your project and the path
174+
associated with each one. So you will need some knowledge about
175+
[stack](https://docs.haskellstack.org/en/stable/build_command/#components) or [cabal](https://cabal.readthedocs.io/en/latest/cabal-commands.html?#cabal-v2-build) components.
176+
177+
You also can use [this utility](https://github.com/Avi-D-coder/implicit-hie
178+
) to generate automatically `hie.yaml` files for
179+
the most common stack and cabal configurations
180+
181+
For example, to state that you want to use `stack` then the configuration file
182+
would look like:
183+
184+
```yaml
185+
cradle:
186+
stack:
187+
component: "haskell-language-server:lib"
188+
```
189+
190+
If you use `cabal` then you probably need to specify which component you want
191+
to use.
192+
193+
```yaml
194+
cradle:
195+
cabal:
196+
component: "lib:haskell-language-server"
197+
```
198+
199+
If you have a project with multiple components, you can use a cabal-multi
200+
cradle:
201+
202+
```yaml
203+
cradle:
204+
cabal:
205+
- path: "./test/functional/"
206+
component: "haskell-language-server:func-test"
207+
- path: "./test/utils/"
208+
component: "haskell-language-server:hls-test-utils"
209+
- path: "./exe/Main.hs"
210+
component: "haskell-language-server:exe:haskell-language-server"
211+
- path: "./exe/Wrapper.hs"
212+
component: "haskell-language-server:exe:haskell-language-server-wrapper"
213+
- path: "./src"
214+
component: "lib:haskell-language-server"
215+
- path: "./ghcide/src"
216+
component: "ghcide:lib:ghcide"
217+
- path: "./ghcide/exe"
218+
component: "ghcide:exe:ghcide"
219+
```
220+
221+
Equivalently, you can use stack:
222+
223+
```yaml
224+
cradle:
225+
stack:
226+
- path: "./test/functional/"
227+
component: "haskell-language-server:func-test"
228+
- path: "./exe/Main.hs"
229+
component: "haskell-language-server:exe:haskell-language-server"
230+
- path: "./exe/Wrapper.hs"
231+
component: "haskell-language-server:exe:haskell-language-server-wrapper"
232+
- path: "./src"
233+
component: "haskell-language-server:lib"
234+
- path: "./ghcide/src"
235+
component: "ghcide:lib:ghcide"
236+
- path: "./ghcide/exe"
237+
component: "ghcide:exe:ghcide"
238+
```
239+
240+
Or you can explicitly state the program which should be used to collect
241+
the options by supplying the path to the program. It is interpreted
242+
relative to the current working directory if it is not an absolute path.
243+
244+
```yaml
245+
cradle:
246+
bios:
247+
program: ".hie-bios"
248+
```
249+
250+
The complete configuration is a subset of
251+
252+
```yaml
253+
cradle:
254+
cabal:
255+
component: "optional component name"
256+
stack:
257+
component: "optional component name"
258+
bios:
259+
program: "program to run"
260+
dependency-program: "optional program to run"
261+
direct:
262+
arguments: ["list","of","ghc","arguments"]
263+
default:
264+
none:
265+
266+
dependencies:
267+
- someDep
268+
```
269+
270+
## Contributing
271+
272+
### It's time to join the project!
273+
274+
:heart: Haskell tooling dream is near, we need your help! :heart:
275+
276+
- Join [our IRC channel](https://webchat.freenode.net/?channels=haskell-ide-engine) at `#haskell-ide-engine` on `freenode`.
277+
- Fork this repo and hack as much as you can.
278+
- Ask @alanz or @hvr to join the project.
279+
280+
### Hacking on haskell-language-server
281+
282+
Haskell-language-server can be used on its own project. We have supplied
283+
preset samples of `hie.yaml` files for stack and cabal, simply copy
284+
the appropriate template to `hie.yaml` and it should work.
285+
286+
- `hie.yaml.cbl` for cabal
287+
- `hie.yaml.stack` for stack
22288

23289
Two sample `hie.yaml` files are provided, `hie.yaml.stack` for stack
24290
usage, `hie.yaml.cbl` for cabal. Simply copy the relevant one to be

Diff for: ‎install/src/HlsInstall.hs

+2-1
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ defaultMain = do
5353
need ["show-options"]
5454
need ["submodules"]
5555
need ["check"]
56-
if isRunFromStack then stackBuildData args else cabalBuildData args
56+
liftIO $ putStrLn "Generation of hoogle data files is disabled for now."
57+
-- if isRunFromStack then stackBuildData args else cabalBuildData args
5758

5859
forM_
5960
versions

0 commit comments

Comments
 (0)