# elm-make

`elm-make` is a build tool for Elm.

  * **Compile down to JS or HTML** — turn Elm files into artifacts that
    can be used with whatever backend you are already using.

  * **Build in parallel** — if you have four cores, `elm-make` will try to
    compile four files at all times.

  * **Build dependencies** — `elm-make` is designed to work with
    `elm-package` so if you use a bunch of 3rd party packages they will all
    work just fine.

  * **Build what you need** — if a module is not needed for your project it
    will not be built or appear in the resulting JS or HTML.


## Basic Usage

Your Elm projects should all have a root directory, like `project/` that all
of your Elm related stuff is going to live in. Lets imagine having the
following directory structure.

```
project/
    Main.elm
    SearchBox.elm
    SearchResults.elm
    Theme.elm
```

We have a couple Elm modules, maybe they depend on each other in some way. To
turn this into JavaScript, you can run the following command:

```bash
elm-make Main.elm --output=main.html
```

Before creating an HTML file called `main.html`, this will prompt you to
install `elm-lang/core` which contains all of the core modules needed to make
Elm programs work.

It will also create a file called `elm-package.json` which gives a structured
description of your project. `elm-make` uses this file to figure out what
directories it needs to look in and which packages are relevant.


## More Advanced Usage

A lot of the more advanced stuff involves fiddling with `elm-package.json` to
make your directory structure nicer or to make sure you are working with the
right dependencies.

### Directory Structure

In the Basic Usage section above, we saw a pretty boring directory structure.
As we actually used it, it would probably expand to look like this:

```
project/
    elm-package.json
    elm-stuff/...
    LICENSE
    Main.elm
    README.md
    SearchBox.elm
    SearchResults.elm
    Theme.elm
```

Pretty messy! There is a field in `elm-package.json` called `source-directories`
that allows you to list all the directories that contain Elm modules. By default
it only lists the root directory `.` but it is best to change that a bit. If you
are doing an Elm only project, this structure is pretty nice.

```
project/
    src/
        Main.elm
        SearchBox.elm
        SearchResults.elm
        Theme.elm
    elm-package.json
    LICENSE
    README.md
```

I would set `"source-directories": [ "src" ]` keeping the root of the project
as clean as possible.

If you have a project that has both frontend and backend components, I have
been experimenting with this directory structure.

```
project/
    backend/...
    frontend/
        Main.elm
        SearchBox.elm
        SearchResults.elm
        Theme.elm
    elm-package.json
    LICENSE
    README.md
```

In this world you set `"source-directories": [ "frontend" ]`. This pattern is
used for [the `package.elm-lang.org` project][src] and seems to work pretty
well.

[src]: https://github.com/elm-lang/package.elm-lang.org/

### Managing Dependencies

There are two general approaches to managing dependencies depending on what you
are trying to do. These rules may not apply in every case, but they are good
guidelines.

  1. If you are creating a package for others to use, you want to keep your
     dependency ranges as broad as possible. You also only want to extend
     ranges as far as you have tested. When you say "my library works with
     4.0.0 of this package" before that version has been released or before
     you have tested with it, you are likely to make life suck for your users.
     Do not do that!

  2. If you are creating an app or product, you want to keep your dependency
     ranges very specific. When you build, a file is generated called
     `elm-stuff/exact-dependencies.json` which lists all of the packages needed
     for your project and the exact versions you happen to be using right now.
     You may want to check this in to version control if you want the same
     exact thing every time.

If you are in camp #1 creating a package for others, we have plans to help
automate the process of expanding version bounds. If your project compiles
with the new stuff and your tests pass, it is conceivable that everything
just works. We will be experimenting with this!