nix-rebar3

This is a Nix library aiming to be an alternative to rebar3_nix that does not require code generation, similar to mix-to-nix but for rebar3 instead of Mix.

Usage

(callPackage nix-rebar3 {}).buildRebar3 {
  root = ./.;
  pname = "myapp";
  version = "1.0.0";
  releaseType = "release";
  profile = "prod";
}

Note that for running a built release with dynamic configuration you either need to first copy the files out of the read-only Nix store, or set the RELX_OUT_FILE_PATH environment variable to a suitable location, since the extended start script generated by relx by default will write files under the release root directory.

The parameters of buildRebar3 are:

Attribute	Description
pname	The name of the derivation.
version	The version number.
root	Path to the directory of the rebar3 project.
releaseType	One of: app to build OTP applications; release to assemble relx releases; or escriptize to generate an escript executable. (Default: app)
profile	The profile to run rebar3 tasks in. (Default: default)
checkouts	Attribute set where the keys are dependency names and values are paths to their sources. This is for overriding dependencies or providing the transitive closure of dependencies such as plugins or those not in the default profile, e.g. test dependencies. The latter is made necessary by such dependencies not being stored in the rebar3 lock file. (Default: {})
singleStep	Whether to skip compiling the dependencies in an intermediate derivation first. Enabling reduces the incrementality of builds. (Default: false)

All other arguments are passed through to the resulting stdenv.mkDerivation call.

Background

This section summarizes the existing support for packaging rebar3 projects in Nixpkgs. Apart from the regular nixpkgs.rebar3 attribute, which is adequate for interactive usage, there is also a patched version that makes it possible to provide paths to pre-built rebar3 plugins to include with

nixpkgs.rebar3WithPlugins { plugins = [ ... ] }

(which passes them through an internal REBAR_GLOBAL_PLUGINS environment variable) to avoid rebar3 choking on trying to download missing plugins during sandboxed builds. When using rebar3WithPlugins, in addition to manually specified plugins, a custom rebar_ignore_deps is always included, that, when the environment variable REBAR_IGNORE_DEPS is non-empty, overrides the install_deps rebar3 provider to instead proceed with the build as if there were no declared dependencies.

There are choices that can be made when packaging rebar3 projects with Nix in general regarding library Erlang application dependencies. They may be built en masse in a separate derivation, or individually with one derivation each. To prevent Rebar3 from managing and downloading the dependencies, one can either: Copy them into the _checkouts top-level directory; or reference built library dependencies in the ERL_LIBS environment variable, and use the bare compile rebar3 provider instead of compile (which skips trying to build dependencies,) or set REBAR_IGNORE_DEPS to true (see above.) Note that it is not possible to include multiple versions of the same application in Erlang/rebar3; the lock file in the top level project is authoritative, with an algorithm for determining the versions to fetch, see Source Dependencies; and rebar3 plugins may technically interfere when building other dependencies; and therefore building libraries individually can produce unexpected results.

With that said, the available rebar3 builders in Nixpkgs are:

• buildRebar3: Builds Erlang applications using rebar3 bare compile.

  The built package will export a setup hook that adds the built applications to ERL_LIBS. All dependencies have to be built similarly and passed in the beamDeps argument, which due to the setup hooks is here just an alias for propagatedBuildInputs.

• rebar3Relx: Builds relx releases or escript executables.

  Dependencies should be provided with beamDeps like above, at which point REBAR_IGNORE_DEPS is set.

• fetchRebar3Deps: Produces a fixed-output derivation (FOD) with the output of rebar3 get-deps.

  The result can be used as the checkouts argument to rebar3Relx.

• fetchHex: Fetches a package tarball from Hex the Erlang package manager/repository.

  buildHex is a shorthand for using fetchHex for the source to any other builder such as buildRebar3.

rebar3_nix is a tool that generates a deps.nix file you are intended to check in to version control, which evaluates to an attribute set containing all dependencies for some rebar3 project. Rebar3 lock files are limited to the default profile, and do not include plugin dependencies nor the precise subdependencies of some dependency, but, being a rebar3 plugin, rebar3_nix has access to that information and for any combination of profiles.

This library instead reads the rebar3 lock file with a pure Nix parser, with the big upside of not requiring any additional generated files. The downsides are that compiled dependencies are not shared between different projects built with Nix, and that plugins and dependencies not listed in the default profile, such as test dependencies, and their transitive dependencies, have to be specified manually.