git.iko.soy/Idris-dev
on master help sign in
Idris-dev/INSTALL.md
153 lines 5.8 kB history raw
1# Idris Installation Guide
3Copyright (C) 2015, The Idris Community
5## Installing Idris from Hackage
7This repository represents the latest development version of the
8language, and may contain bugs that are being actively worked on. For
9those who wish to use a more stable version of Idris please consider
10installing the latest version that has been released on Hackage.
11Installation instructions for various platforms can be
12[found on the Idris Wiki](https://github.com/idris-lang/Idris-dev/wiki/Installation-Instructions).
14## Installing Development Versions
16If you like to work against the latest development version, please
17consider using Cabal Sandboxes to minimise disruption to your local
18Haskell setup. Instructions for installing Idris HEAD within a cabal
19sandbox are
20[available on the Idris Wiki](https://github.com/idris-lang/Idris-dev/wiki/Installing-an-Idris-Development-version-in-a-sandbox).
22To configure, edit config.mk. The default values should work for most
23people.
25Idris is built using a Makefile common targets include:
27* `make` This will install everything using cabal and typecheck the
28 libraries.
29* `make test` This target execute the test suite.
30* `make relib` This target will typecheck and recompile the standard
31 library.
33Idris has an optional dependency on the `C` library `libffi`. If you
34would like to use the features that it enables, make sure that it is
35compiled for the same architecture as your Haskell compiler (e.g. 64
36bit libraries for 64 bit ghc). By default, Idris builds without it. To
37build with it, pass the flag `-f FFI`.
39A secondary optional dependency is on `libGMP`, this allows better
40support for numeric operations. As with `libFFI` Idris builds with out
41it, to enable `GMP` support use the flag `-f GMP`
43To build with `libffi` and `libGMP` by default, create a `custom.mk`
44file and add the following line to it:
46`CABALFLAGS += -f FFI -f GMP`
48The file `custom.mk-alldeps` is a suitable example.
50The continuous integration builds on travis-ci.org are built using the
51ghc-flag -Werror. To enable this behaviour locally also, please
52compile using `make CI=true` or adding the following line into
53`custom.mk`:
55`CI = true`
57If you are only compiling for installing the most current version, you
58can omit the CI flag, but please make sure you use it if you want to
59contribute.
61## Experimental Support for Building with Stack
63[Stack](https://github.com/commercialhaskell/stack) is a new
64cross-platform program for developing Haskell projects, that enhances
65the functionality provided by Cabal. There is experimental support for
66building Idris from source with stack.
68This installation has been tested on Ubuntu 16.04.1 LTS, and the current
69NixOS unstable.
71*Important* Stack will not install any external dependencies required
72to build Idris. Before you try stack please ensure you have the
73correct dependencies.
75To build Idris with stack use the following command:
77* `stack build`
79To install Idris:
81* `stack install`
83Stack will install Idris (and related executables) into `$HOME/.local/bin/`
84on Unix based systems and an appropriate place on Windows. The libraries that
85are included with Idris (e.g. Builtins, Prelude) will 'install' into `<source
86dir>/.stack_work/install/...` so you'll need to keep your source directory
87around after you've installed Idris using Stack.
89Of note: If you haven't used stack before commands will also setup the
90related infrastructure. For more information about Stack please visit
91the [Stack website](https://github.com/commercialhaskell/stack).
93On NixOS, please use the following command instead, to make sure
94the required libraries and header files are available:
96* `stack build --nix`
98### before rebuilding new pulls
99the default build will currently just reuse `.ibc` files which can result
100in build-failures in the `Building libraries...` phase.
102A safer way to do this is therefore to recursively delete all the `*.ibc`
103files from the `libs/` folder.
105On Linux(or similar) you can do this with
107 find . -name "*.ibc" -exec rm -rf {} \;
109### System GHC
111The flag `--system-ghc` can be added to enforce use of your system's
112version of GHC.
114### `libGMP` and `libFFI`
116By default the stack configuration in `stack.yaml` will build with
117support for `libGMP` and `libFFI`. To turn this support off, the
118option flags needs to be fully commented out.
120There have been reports in the past over building Idris on Mac OS X,
121using stack, and linking to a HomeBrew installation of `libFFI`. The
122build has failed to find the correct `libFFI` installation. If you
123encounter this then the fix is to augment the `PKG_CONFIG_PATH` for
124`libFFI`. For example:
126```
127PKG_CONFIG_PATH=/usr/local/opt/libffi/lib/pkgconfig stack build
128```
130## Issue with GHC on Ubuntu/Fedora
132There is an upstream issue with GHC on some Ubuntu and Fedora machines.
133The issue is that for GHC versions greater than 8.4.X linking to libFFI uses the version of libFFI shipped with GHC, instead of the system version.
135See the following GHC issue page for more information:
137 <https://gitlab.haskell.org/ghc/ghc/issues/15397>
139This means that an Idris built with `libFFI` support will fail at runtime as the executable would not be able to find the correct `libffi` shared object.
140This will cause the build to fail.
141Specifically, one will see an error message along the lines of:
143> error while loading shared libraries: libffi.so.7: cannot open shared object file: No such file or directory
145A workround for this bug is to override the used libffi version (this is what we use on CI):
147```bash
148export LD_PRELOAD=/opt/ghc/${GHCVER}/lib/ghc-${GHCVER}/rts/libffi.so.7
149```
151## GHC 8.6
153For reasons that haven't been investigated building the Idris compiler with GHC 8.6 leads to a compiler which doesn't pass test.