BEAM Languages (Erlang, Elixir & LFE)

Introduction

In this document and related Nix expressions, we use the term, BEAM, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction.

Structure

All BEAM-related expressions are available via the top-level beam attribute, which includes:

interpreters: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (beam.interpreters.erlangR19, etc), Elixir (beam.interpreters.elixir) and LFE (beam.interpreters.lfe).
packages: a set of package builders (Mix and rebar3), each compiled with a specific Erlang/OTP version, e.g. beam.packages.erlangR19.

The default Erlang compiler, defined by beam.interpreters.erlang, is aliased as erlang. The default BEAM package set is defined by beam.packages.erlang and aliased at the top level as beamPackages.

To create a package builder built with a custom Erlang version, use the lambda, beam.packagesWith, which accepts an Erlang/OTP derivation and produces a package builder similar to beam.packages.erlang.

Many Erlang/OTP distributions available in beam.interpreters have versions with ODBC and/or Java enabled or without wx (no observer support). For example, there's beam.interpreters.erlangR22_odbc_javac, which corresponds to beam.interpreters.erlangR22 and beam.interpreters.erlangR22_nox, which corresponds to beam.interpreters.erlangR22.

Build Tools

Rebar3

We provide a version of Rebar3, under rebar3. We also provide a helper to fetch Rebar3 dependencies from a lockfile under fetchRebar3Deps.

Mix & Erlang.mk

Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the buildMix and buildErlangMk derivations, respectively.

How to Install BEAM Packages

BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. To install any of those builders into your profile, refer to them by their attribute path beamPackages.rebar3:

$ nix-env -f "<nixpkgs>" -iA beamPackages.rebar3

Packaging BEAM Applications

Erlang Applications

Rebar3 Packages

The Nix function, buildRebar3, defined in beam.packages.erlang.buildRebar3 and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project.

If a package needs to compile native code via Rebar3's port compilation mechanism, add compilePort = true; to the derivation.

Erlang.mk Packages

Erlang.mk functions similarly to Rebar3, except we use buildErlangMk instead of buildRebar3.

Mix Packages

Mix functions similarly to Rebar3, except we use buildMix instead of buildRebar3.

Alternatively, we can use buildHex as a shortcut:

How to Develop

Creating a Shell

Usually, we need to create a shell.nix file and do our development inside of the environment specified therein. Just install your version of erlang and other interpreter, and then user your normal build tools. As an example with elixir:

{ pkgs ? import "<nixpkgs"> {} }:

with pkgs;

let

  elixir = beam.packages.erlangR22.elixir_1_9;

in
mkShell {
  buildInputs = [ elixir ];

  ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include";
}

Building in a Shell (for Mix Projects)

Using a shell.nix as described (see ) should just work.

3.9 KiB Raw Blame History