@@ -0,0 +1,87 @@
1+# Idris Installation Guide
2+
3+Copyright (C) 2015, The Idris Community
4+
5+This file provides information over obtaining and installing Idris.
6+
7+## Installing Idris from Hackage
8+
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).
14+
15+## Installing Development Versions
16+
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).
21+
22+To configure, edit config.mk. The default values should work for most people.
23+
24+Idris is built using a Makefile common targets include:
25+
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.
30+
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`.
36+
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`
40+
41+To build with `libffi` and `libGMP` by default, create a `custom.mk` file and add the
42+following line to it:
43+
44+`CABALFLAGS += -f FFI -f GMP`
45+
46+The file `custom.mk-alldeps` is a suitable example.
47+
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`:
51+
52+`CI = true`
53+
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.
56+
57+## Experimental Support for Building with Stack
58+
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.
64+
65+To build Idris with stack the following commands are recommended:
66+
67+* `stack build`
68+
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).
74+
75+### System GHC
76+
77+The flag `--system-ghc` can be added to enforce use of your system's version of GHC.
78+
79+### `libGMP` and `libFFI`
80+
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:
83+
84+* `stack build --flag idris:GMP --flag idris:FFI`
85+
86+or un-comment the options `idris:GMP` and `idris:FFI` and their
87+dependencies in the `stack.yaml` file.