yogsototh/elm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Simplify install instructions

Browse source
This commit is contained in:
evancz 2013-05-23 01:15:55 +02:00
parent 0f76e1643c
commit 6983857379
1 changed files with 28 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

118
README.md
View file

@ -1,117 +1,55 @@
Elm
===
If you are new to Elm, learn more about the language [here](http://elm-lang.org/)
and try it out in the [online interactive editor](http://elm-lang.org/try).
This is the Elm compiler and server, allowing you to natively develop Elm
applications that run in any modern browser. The compiler generates HTML and JS
files, and the server just serves .elm files directly.
If you intend to serve Elm code with a custom Haskell backend, be
sure to read all the way to the "Installation for Haskell-Users" section.
Learn more about the language at [elm-lang.org](http://elm-lang.org/).
Installation for General Use
----------------------------
### Installing the Compiler
Download the [Haskell Platform 2012.2.0.0](http://hackage.haskell.org/platform/).
This will give you access to the Haskell compiler (needed to build Elm) and Haskell's
package distribution system (to make installation of Elm easier). Elm definitely works with
version 7.4 of the Haskell compiler (i.e. GHC 7.4) which is bundled with
version 2012.2.0.0 of the Haskell Platform.
Elm definitely works with GHC 7.4, so newer versions of the Haskell Platform may work too.
If you are a Linux user and already have a copy of GHC installed and have
downloaded a bunch of packages, it may be worthwhile to create new user account
and just install Elm separately
[as described here](https://groups.google.com/forum/?fromgroups=#!topic/elm-discuss/cNNJ6YM77zs).
Dependency issues have been rampant lately with packages changing to support GHC 7.6.
Once the Haskell Platform is installed:
If you run into issues, check [the mailing list][list] for advice or go to the
[#Elm IRC channel][irc].
cabal update ; cabal install elm
[list]: https://groups.google.com/forum/?fromgroups#!forum/elm-discuss "Mailing List"
[irc]: http://webchat.freenode.net/?channels=elm "#elm channel"
#### Installing the compiler and server
Once the Haskell Platform is installed (even if it already was), you must update your listing of packages with:
cabal update
This will ensure that the elm package is available. Then install Elm with:
cabal install elm
Assuming everything goes correctly (potential problems are discussed later), this
will install the `elm` compiler on your machine. `elm` is a standard compiler that
takes `.elm` files and produces `.html` and/or `.js` files. You can then use these
files with your favorite web-framework. Use `elm --help` for more directions on how to use it.
If you have this installed you can write and compile Elm locally,
so if the next step fails for you, it is safe to proceed without it.
You can also install `elm-server` which is both a compiler and server, allowing
you to develop without designing and setting up a server yourself. Running `elm-server`
starts a server in the current directory. It will compile and serve any `.elm` files in
the current directory and its sub-directories. This is how I prefer to develop
Elm programs. Install with:
### Installing the Server
cabal install elm-server
Dependency issues have been cropping up with this step, so if you run into issues,
please report them so they can be fixed! Once installed, use the command `elm-server --help`
to see some extra information.
### Using the executables
#### Using the Elm compiler and server
To use `elm` and `elm-server` you need to add a new directory to your PATH.
To use these executables you need to add a new directory to your PATH. For me, the
executables were placed in `/home/evan/.cabal/bin` which I appended to the end of my
PATH variable in my .bashrc file. Cabal should tell you where your executables are
located upon successful installation, so you can make a similar addition (see this
tutorial if you are new to changing your PATH in [Unix/Linux](http://www.cyberciti.biz/faq/unix-linux-adding-path/)).
Cabal should tell you where your executables are located upon
successful installation.
You can use the commands `elm --help` and `elm-server --help`
to get more information about using these tools.
For me, the executables were placed in `/home/evan/.cabal/bin` which I
appended to the end of my PATH variable in my .bashrc file.
That is almost everything. Now, we will create a simple Elm project.
See this tutorial if you are new to changing your PATH in
[Unix/Linux](http://www.cyberciti.biz/faq/unix-linux-adding-path/).
## A Test project
Now we will create a simple Elm project.
The following commands will set-up a very basic project and start the Elm server.
mkdir helloElm
cd helloElm
echo main = lift asText Mouse.position > main.elm
echo import Mouse > Main.elm
echo main = lift asText Mouse.position > Main.elm
elm-server
The first two commands create a new directory and navigate into it. The `echo`
command places a simple program into `main.elm` (do this manually if you do not
have `echo`). The final command starts the Elm server at [localhost](http://localhost:8000/),
allowing you to navigate to `main.elm` and see your first program in action.
commands place a simple program into `Main.elm`. Do this manually if you do not
have `echo`. The final command starts the Elm server at [localhost:8000](http://localhost:8000/),
allowing you to navigate to `Main.elm` and see your first program in action.
#### Wrap up
Installation for Haskell-users
------------------------------
The `elm` package provides support for compilation of Elm code directly in Haskell and QuasiQuoting.
Check it out on Hackage if you are interested.
The `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.
Yesod users should also install the `elm-yesod` package which provides functions for idiomatically embedding Elm in Yesod:
cabal install elm-yesod
Some extra tips on Elm+Yesod can be found [here](https://github.com/evancz/Elm/wiki/Elm-with-Yesod:-Getting-Started).
An 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.
Potential problems and their solutions
--------------------------------------
* Try `cabal install elm`. This will give you access to the `elm` executable (but not `elm-server`).
These problems all appeared before Elm version 0.1.1.4:
* 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"`
* When installing on Debian, `blaze-html-0.4.3.2` fails to compile. You must install `blaze-html-0.4.3.1` instead.
* 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`
* 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).
If you are still stuck, email the list or ask a question in the [#Elm IRC channel](http://webchat.freenode.net/?channels=elm).
If you are stuck, email [the list](https://groups.google.com/forum/?fromgroups#!forum/elm-discuss)
or ask a question in the [#Elm IRC channel](http://webchat.freenode.net/?channels=elm).