elmenv

Simple management of Elm versions, inspired by projects like rbenv, nvm, and phpenv.

How It Works

At a high level, elmenv intercepts Elm commands using shim executables injected into your PATH, determines which Elm version has been specified by your application, and passes your commands along to the correct Elm installation.

Understanding Shims

elmenv works by inserting a directory of shims at the front of your PATH:

~/.elmenv/shims:/usr/local/bin:/usr/bin:/bin

Through a process called rehashing, elmenv maintains shims in that directory to match every Elm command across every installed version of Elm—elm-make, elm-reactor, elm-package, elm-reply, elm, and so on.

Shims are lightweight executables that simply pass your command along to elmenv. So with elmenv installed, when you run, say, elm, your operating system will do the following:

• Search your PATH for an executable file named elm
• Find the elmenv shim named elm at the beginning of your PATH
• Run the shim named elm, which in turn passes the command along to elmenv

Choosing the Elm Version

When you execute a shim, elmenv determines which Elm version to use by reading it from the following sources, in this order:

1. The ELMENV_VERSION environment variable, if specified. You can use the elmenv shell command to set this environment variable in your current shell session.

2. The first .elm-version file found by searching the directory of the script you are executing and each of its parent directories until reaching the root of your filesystem.

3. The first .elm-version file found by searching the current working directory and each of its parent directories until reaching the root of your filesystem. You can modify the .elm-version file in the current working directory with the elmenv local command.

4. The global ~/.elmenv/version file. You can modify this file using the elmenv global command. If the global version file is not present, elmenv assumes you want to use the "system" Elm—i.e. whatever version would be run if elmenv weren't in your path.

Installation

This will get you going with the latest version of elmenv and make it easy to fork and contribute any changes back upstream.

1. Check out elmenv into ~/.elmenv.

   $ git clone --recurse-submodules https://github.com/sonnym/elmenv.git ~/.elmenv

2. Add ~/.elmenv/bin to your $PATH for access to the elmenv command-line utility.

   $ echo 'export PATH="$HOME/.elmenv/bin:$PATH"' >> ~/.bash_profile

   Ubuntu Desktop note: Modify your ~/.bashrc instead of ~/.bash_profile.

   Zsh note: Modify your ~/.zshrc file instead of ~/.bash_profile.

3. Add elmenv init to your shell to enable shims and autocompletion.

   $ echo 'eval "$(elmenv init -)"' >> ~/.bash_profile

   Same as in previous step, use ~/.bashrc on Ubuntu, or ~/.zshrc for Zsh.

4. Restart your shell so that PATH changes take effect. (Opening a new terminal tab will usually do it.) Now check if elmenv was set up:

   $ type elmenv
   #=> "elmenv is a function"

Upgrading

If you've installed elmenv manually using git, you can upgrade your installation to the cutting-edge version at any time.

$ cd ~/.elmenv
$ git pull
$ git submodule foreach $(git submodule update --init --recursive)

Installing Elm

To install a Elm version for use with elmenv, run elmenv install with the exact name of the version you want to install. For example,

elmenv install 0.14.1

Elm versions will be installed into a directory of the same name under ~/.elmenv/versions. It is also possible install the master branch of elm. The installation is directly from source, so it is necessary to have an up to date haskell and cabal setup.