git.iko.soy/elk
on d15e080 help sign in
elk/README.md
113 lines 6.4 kB history raw
1Elm
2===
4This is the Elm compiler and server, allowing you to develop Elm
5applications that run in any modern browser.
7If you intend to serve Elm code with a custom Haskell backend, be
8sure to read all the way to the "Installation for Haskell-Users" section.
11Installation for General Use
12----------------------------
14Download the [Haskell Platform 2012.2.0.0](http://hackage.haskell.org/platform/).
15This will give you access to the Haskell compiler (needed to build Elm) and Haskell's
16package distribution system (to make installation of Elm easier). Elm definitely works with
17version 7.4 of the Haskell compiler (i.e. GHC 7.4) which is bundled with
18version 2012.2.0.0 of the Haskell Platform.
20If you are a Linux user and already have a copy of GHC installed and have
21downloaded a bunch of packages, it may be worthwhile to create new user account
22and just install Elm separately
23[as described here](https://groups.google.com/forum/?fromgroups=#!topic/elm-discuss/cNNJ6YM77zs).
24Dependency issues have been rampant lately with packages changing to support GHC 7.6.
26If you run into issues, check [the mailing list][list] for advice or go to the
27[#Elm IRC channel][irc].
29 [list]: https://groups.google.com/forum/?fromgroups#!forum/elm-discuss "Mailing List"
30 [irc]: http://webchat.freenode.net/?channels=elm "#elm channel"
32#### Installing the compiler and server
34Once the Haskell Platform is installed (even if it already was), you must update your listing of packages with:
36 cabal update
38This will ensure that the elm package is available. Then install Elm with:
40 cabal install elm
42Assuming everything goes correctly (potential problems are discussed later), this
43will install the `elm` compiler on your machine. `elm` is a standard compiler that
44takes `.elm` files and produces `.html` and/or `.js` files. You can then use these
45files with your favorite web-framework. Use `elm --help` for more directions on how to use it.
47If you have this installed you can write and compile Elm locally,
48so if the next step fails for you, it is safe to proceed without it.
50You can also install `elm-server` which is both a compiler and server, allowing
51you to develop without designing and setting up a server yourself. Running `elm-server`
52starts a server in the current directory. It will compile and serve any `.elm` files in
53the current directory and its sub-directories. This is how I prefer to develop
54Elm programs. Install with:
56 cabal install elm-server
58Dependency issues have been cropping up with this step, so if you run into issues,
59please report them so they can be fixed! Once installed, use the command `elm-server --help`
60to see some extra information.
62#### Using the Elm compiler and server
64To use these executables you need to add a new directory to your PATH. For me, the
65executables were placed in `/home/evan/.cabal/bin` which I appended to the end of my
66PATH variable in my .bashrc file. Cabal should tell you where your executables are
67located upon successful installation, so you can make a similar addition (see this
68tutorial if you are new to changing your PATH in [Unix/Linux](http://www.cyberciti.biz/faq/unix-linux-adding-path/)).
70You can use the commands `elm --help` and `elm-server --help`
71to get more information about using these tools.
73That is almost everything. Now, we will create a simple Elm project.
74The following commands will set-up a very basic project and start the Elm server.
76 mkdir helloElm
77 cd helloElm
78 echo main = lift asText Mouse.position > main.elm
79 elm-server
81The first two commands create a new directory and navigate into it. The `echo`
82command places a simple program into `main.elm` (do this manually if you do not
83have `echo`). The final command starts the Elm server at [localhost](http://localhost:8000/),
84allowing you to navigate to `main.elm` and see your first program in action.
87Installation for Haskell-users
88------------------------------
90The `elm` package provides support for [compilation of Elm code directly in Haskell](http://hackage.haskell.org/packages/archive/Elm/0.1.2/doc/html/Language-Elm.html) and [QuasiQuoting](http://hackage.haskell.org/packages/archive/Elm/0.1.2/doc/html/Language-Elm-Quasi.html). See the [Examples/](https://github.com/evancz/Elm/tree/master/Examples) directory for information and examples on how to get started with Elm+Haskell.
92Yesod users should also install the `elm-yesod` package which provides functions for idiomatically embedding Elm in Yesod:
94 cabal install elm-yesod
96Some extra tips on Elm+Yesod can be found [here](https://github.com/evancz/Elm/wiki/Elm-with-Yesod:-Getting-Started).
98An important note: When you install the `elm` compiler, it automatically downloads Elm's JavaScript runtime system to `~/.cabal/share/Elm-x.y.z/`. The runtime system will follow the name scheme `elm-runtime-x.y.z.js` where `x.y.z` matches the version number of the compiler. If you want to serve this file from a different location, *copy* it from its home and always be sure that code compiled with version `x.y.z` of the compiler is served with version `x.y.z` of the runtime system.
101Potential problems and their solutions
102--------------------------------------
104* Try `cabal install elm`. This will give you access to the `elm` executable (but not `elm-server`).
106These problems all appeared before Elm version 0.1.1.4:
108* Install errors having to do with `happstack-server-7.0.2`. This version of `happstack-server` has stricter dependency restrictions that conflict with other libraries required by Elm. Try installing with an earlier version of `happstack-server` with the following command: `cabal install elm --constrain="happstack-server<7.0.2"`
109* When installing on Debian, `blaze-html-0.4.3.2` fails to compile. You must install `blaze-html-0.4.3.1` instead.
110* Elm does not appear to work with the latest versions of `containers` (i.e. 0.4.2.*). I know it works with earlier versions of containers, so to avoid this problem, you can try: `cabal install elm --constrain="containers==0.4.1.0" --force-reinstall`
111* On Windows, HAppStack has trouble installing because of issues with the "network" package. I struggled with this problem on Windows 7 until I found the suggestion at the bottom of [this page](http://hackage.haskell.org/trac/ghc/ticket/5159).
113If you are still stuck, email the list or ask a question in the [#Elm IRC channel](http://webchat.freenode.net/?channels=elm).