@@ -0,0 +1,87 @@
1+# Idris Installation Guide
3+Copyright (C) 2015, The Idris Community
5+This file provides information over obtaining and installing Idris.
7+## Installing Idris from Hackage
9+This repository represents the latest development version of the language,
10+and may contain bugs that are being actively worked on.
11+For those who wish to use a more stable version of Idris please consider
12+installing the latest version that has been released on Hackage.
13+Installation instructions for various platforms can be [found on the Idris Wiki](https://github.com/idris-lang/Idris-dev/wiki/Installation-Instructions).
15+## Installing Development Versions
17+If you like to work against the latest development version, please consider
18+using Cabal Sandboxes to minimise disruption to your local Haskell setup.
19+Instructions for installing Idris HEAD within a cabal sandbox are
20+[available on the Idris Wiki](https://github.com/idris-lang/Idris-dev/wiki/Installing-an-Idris-Development-version-in-a-sandbox).
22+To configure, edit config.mk. The default values should work for most people.
24+Idris is built using a Makefile common targets include:
26+* `make` This will install everything using cabal and
27+typecheck the libraries.
28+* `make test` This target execute the test suite.
29+* `make relib` This target will typecheck and recompile the standard library.
31+Idris has an optional buildtime dependency on the C library
32+`libffi`. If you would like to use the features that it enables, make
33+sure that it is compiled for the same architecture as your Haskell
34+compiler (e.g. 64 bit libraries for 64 bit ghc). By default, Idris
35+builds without it. To build with it, pass the flag `-f FFI`.
37+A secondary optional buildtime dependency is on `libGMP`, this allows
38+better support for numeric operations. As with `libFFI` Idris builds
39+with out it, to enable `GMP` support use the flag `-f GMP`
41+To build with `libffi` and `libGMP` by default, create a `custom.mk` file and add the
44+`CABALFLAGS += -f FFI -f GMP`
46+The file `custom.mk-alldeps` is a suitable example.
48+The continuous integration builds on travis-ci.org are built using the
49+ghc-flag -Werror. To enable this behaviour locally also, please compile
50+using `make CI=true` or adding the following line into `custom.mk`:
54+If you are only compiling for installing the most current version, you can
55+omit the CI flag, but please make sure you use it if you want to contribute.
57+## Experimental Support for Building with Stack
59+[Stack](https://github.com/commercialhaskell/stack) is a new
60+cross-platform program for developing Haskell projects, that enhances
61+the functionality provided by Cabal. There is experimental support for
62+building Idris from source using with stack, that uses the LTS 3.6 resolver.
63+This installation has been tested on Ubuntu 14.04.2 LTS, only.
65+To build Idris with stack the following commands are recommended:
69+This will install Idris (and related executables) into `./local/bin/`
70+on Unix based systems and an appropriate place on Windows. If you
71+haven't used stack before this will also setup the related
72+infrastructure. For more information about Stack please visit the
73+[Stack website](https://github.com/commercialhaskell/stack).
77+The flag `--system-ghc` can be added to enforce use of your system's version of GHC.
79+### `libGMP` and `libFFI`
81+To build with support for `libGMP` and `libFFI` you need to pass build
82+commands for the Idris library either from the command line:
84+* `stack build --flag idris:GMP --flag idris:FFI`
86+or un-comment the options `idris:GMP` and `idris:FFI` and their
87+dependencies in the `stack.yaml` file.