505508a813
Improve beam docs: * correct spelling * update per pandoc changes * capitalize titles * capitalize BEAM throughout and use "the BEAM" when referring to the virtual machine. * tweak grammar and phrasing * reformat build-tools-rebar3 section * add more links * re-wrap <para>s Also update <programlisting>s * normalize whitespace * don't double quote homepage * use $ in all shell snippets
474 lines
17 KiB
XML
474 lines
17 KiB
XML
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="sec-beam">
|
|
|
|
<title>BEAM Languages (Erlang, Elixir & LFE)</title>
|
|
<section xml:id="beam-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
In this document and related Nix expressions, we use the term,
|
|
<emphasis>BEAM</emphasis>, 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.
|
|
</para>
|
|
</section>
|
|
<section xml:id="beam-structure">
|
|
<title>Structure</title>
|
|
<para>
|
|
All BEAM-related expressions are available via the top-level
|
|
<literal>beam</literal> attribute, which includes:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>interpreters</literal>: a set of compilers running on the
|
|
BEAM, including multiple Erlang/OTP versions
|
|
(<literal>beam.interpreters.erlangR19</literal>, etc), Elixir
|
|
(<literal>beam.interpreters.elixir</literal>) and LFE
|
|
(<literal>beam.interpreters.lfe</literal>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>packages</literal>: a set of package sets, each compiled with
|
|
a specific Erlang/OTP version, e.g.
|
|
<literal>beam.packages.erlangR19</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
The default Erlang compiler, defined by
|
|
<literal>beam.interpreters.erlang</literal>, is aliased as
|
|
<literal>erlang</literal>. The default BEAM package set is defined by
|
|
<literal>beam.packages.erlang</literal> and aliased at the top level as
|
|
<literal>beamPackages</literal>.
|
|
</para>
|
|
<para>
|
|
To create a package set built with a custom Erlang version, use the
|
|
lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP
|
|
derivation and produces a package set similar to
|
|
<literal>beam.packages.erlang</literal>.
|
|
</para>
|
|
<para>
|
|
Many Erlang/OTP distributions available in
|
|
<literal>beam.interpreters</literal> have versions with ODBC and/or Java
|
|
enabled. For example, there's
|
|
<literal>beam.interpreters.erlangR19_odbc_javac</literal>, which
|
|
corresponds to <literal>beam.interpreters.erlangR19</literal>.
|
|
</para>
|
|
<para xml:id="erlang-call-package">
|
|
We also provide the lambda,
|
|
<literal>beam.packages.erlang.callPackage</literal>, which simplifies
|
|
writing BEAM package definitions by injecting all packages from
|
|
<literal>beam.packages.erlang</literal> into the top-level context.
|
|
</para>
|
|
</section>
|
|
<section xml:id="build-tools">
|
|
<title>Build Tools</title>
|
|
<section xml:id="build-tools-rebar3">
|
|
<title>Rebar3</title>
|
|
<para>
|
|
By default, Rebar3 wants to manage its own dependencies. This is perfectly
|
|
acceptable in the normal, non-Nix setup, but in the Nix world, it is not.
|
|
To rectify this, we provide two versions of Rebar3:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>rebar3</literal>: patched to remove the ability to download
|
|
anything. When not running it via <literal>nix-shell</literal> or
|
|
<literal>nix-build</literal>, it's probably not going to work as
|
|
desired.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>rebar3-open</literal>: the normal, unmodified Rebar3. It
|
|
should work exactly as would any other version of Rebar3. Any Erlang
|
|
package should rely on <literal>rebar3</literal> instead. See <xref
|
|
linkend="rebar3-packages"/>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section xml:id="build-tools-other">
|
|
<title>Mix & Erlang.mk</title>
|
|
<para>
|
|
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
|
|
<literal>buildMix</literal> and <literal>buildErlangMk</literal>
|
|
derivations, respectively.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="how-to-install-beam-packages">
|
|
<title>How to Install BEAM Packages</title>
|
|
<para>
|
|
BEAM packages are not registered at the top level, simply because they are
|
|
not relevant to the vast majority of Nix users. They are installable using
|
|
the <literal>beam.packages.erlang</literal> attribute set (aliased as
|
|
<literal>beamPackages</literal>), which points to packages built by the
|
|
default Erlang/OTP version in Nixpkgs, as defined by
|
|
<literal>beam.interpreters.erlang</literal>.
|
|
|
|
To list the available packages in
|
|
<literal>beamPackages</literal>, use the following command:
|
|
</para>
|
|
|
|
<programlisting>
|
|
$ nix-env -f "<nixpkgs>" -qaP -A beamPackages
|
|
beamPackages.esqlite esqlite-0.2.1
|
|
beamPackages.goldrush goldrush-0.1.7
|
|
beamPackages.ibrowse ibrowse-4.2.2
|
|
beamPackages.jiffy jiffy-0.14.5
|
|
beamPackages.lager lager-3.0.2
|
|
beamPackages.meck meck-0.8.3
|
|
beamPackages.rebar3-pc pc-1.1.0
|
|
</programlisting>
|
|
<para>
|
|
To install any of those packages into your profile, refer to them by their
|
|
attribute path (first column):
|
|
</para>
|
|
<programlisting>
|
|
$ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse
|
|
</programlisting>
|
|
<para>
|
|
The attribute path of any BEAM package corresponds to the name of that
|
|
particular package in <link xlink:href="https://hex.pm">Hex</link> or its
|
|
OTP Application/Release name.
|
|
</para>
|
|
</section>
|
|
<section xml:id="packaging-beam-applications">
|
|
<title>Packaging BEAM Applications</title>
|
|
<section xml:id="packaging-erlang-applications">
|
|
<title>Erlang Applications</title>
|
|
<section xml:id="rebar3-packages">
|
|
<title>Rebar3 Packages</title>
|
|
<para>
|
|
The Nix function, <literal>buildRebar3</literal>, defined in
|
|
<literal>beam.packages.erlang.buildRebar3</literal> and aliased at the
|
|
top level, can be used to build a derivation that understands how to
|
|
build a Rebar3 project. For example, we can build <link
|
|
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> as
|
|
follows:
|
|
</para>
|
|
<programlisting>
|
|
{ stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }:
|
|
|
|
buildRebar3 rec {
|
|
name = "hex2nix";
|
|
version = "0.0.1";
|
|
|
|
src = fetchFromGitHub {
|
|
owner = "ericbmerritt";
|
|
repo = "hex2nix";
|
|
rev = "${version}";
|
|
sha256 = "1w7xjidz1l5yjmhlplfx7kphmnpvqm67w99hd2m7kdixwdxq0zqg";
|
|
};
|
|
|
|
beamDeps = [ ibrowse jsx erlware_commons ];
|
|
}
|
|
</programlisting>
|
|
<para>
|
|
Such derivations are callable with
|
|
<literal>beam.packages.erlang.callPackage</literal> (see <xref
|
|
linkend="erlang-call-package"/>). To call this package using the normal
|
|
<literal>callPackage</literal>, refer to dependency packages via
|
|
<literal>beamPackages</literal>, e.g.
|
|
<literal>beamPackages.ibrowse</literal>.
|
|
</para>
|
|
<para>
|
|
Notably, <literal>buildRebar3</literal> includes
|
|
<literal>beamDeps</literal>, while
|
|
<literal>stdenv.mkDerivation</literal> does not. BEAM dependencies added
|
|
there will be correctly handled by the system.
|
|
</para>
|
|
<para>
|
|
If a package needs to compile native code via Rebar3's port compilation
|
|
mechanism, add <literal>compilePort = true;</literal> to the derivation.
|
|
</para>
|
|
</section>
|
|
<section xml:id="erlang-mk-packages">
|
|
<title>Erlang.mk Packages</title>
|
|
<para>
|
|
Erlang.mk functions similarly to Rebar3, except we use
|
|
<literal>buildErlangMk</literal> instead of
|
|
<literal>buildRebar3</literal>.
|
|
</para>
|
|
<programlisting>
|
|
{ buildErlangMk, fetchHex, cowlib, ranch }:
|
|
|
|
buildErlangMk {
|
|
name = "cowboy";
|
|
version = "1.0.4";
|
|
|
|
src = fetchHex {
|
|
pkg = "cowboy";
|
|
version = "1.0.4";
|
|
sha256 = "6a0edee96885fae3a8dd0ac1f333538a42e807db638a9453064ccfdaa6b9fdac";
|
|
};
|
|
|
|
beamDeps = [ cowlib ranch ];
|
|
|
|
meta = {
|
|
description = ''
|
|
Small, fast, modular HTTP server written in Erlang
|
|
'';
|
|
license = stdenv.lib.licenses.isc;
|
|
homepage = https://github.com/ninenines/cowboy;
|
|
};
|
|
}
|
|
</programlisting>
|
|
</section>
|
|
<section xml:id="mix-packages">
|
|
<title>Mix Packages</title>
|
|
<para>
|
|
Mix functions similarly to Rebar3, except we use
|
|
<literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
|
|
</para>
|
|
<programlisting>
|
|
{ buildMix, fetchHex, plug, absinthe }:
|
|
|
|
buildMix {
|
|
name = "absinthe_plug";
|
|
version = "1.0.0";
|
|
|
|
src = fetchHex {
|
|
pkg = "absinthe_plug";
|
|
version = "1.0.0";
|
|
sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33";
|
|
};
|
|
|
|
beamDeps = [ plug absinthe ];
|
|
|
|
meta = {
|
|
description = ''
|
|
A plug for Absinthe, an experimental GraphQL toolkit
|
|
'';
|
|
license = stdenv.lib.licenses.bsd3;
|
|
homepage = https://github.com/CargoSense/absinthe_plug;
|
|
};
|
|
}
|
|
</programlisting>
|
|
<para>
|
|
Alternatively, we can use <literal>buildHex</literal> as a shortcut:
|
|
</para>
|
|
<programlisting>
|
|
{ buildHex, buildMix, plug, absinthe }:
|
|
|
|
buildHex {
|
|
name = "absinthe_plug";
|
|
version = "1.0.0";
|
|
|
|
sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33";
|
|
|
|
builder = buildMix;
|
|
|
|
beamDeps = [ plug absinthe ];
|
|
|
|
meta = {
|
|
description = ''
|
|
A plug for Absinthe, an experimental GraphQL toolkit
|
|
'';
|
|
license = stdenv.lib.licenses.bsd3;
|
|
homepage = https://github.com/CargoSense/absinthe_plug;
|
|
};
|
|
}
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section xml:id="how-to-develop">
|
|
<title>How to Develop</title>
|
|
<section xml:id="accessing-an-environment">
|
|
<title>Accessing an Environment</title>
|
|
<para>
|
|
Often, we simply want to access a valid environment that contains a
|
|
specific package and its dependencies. We can accomplish that with the
|
|
<literal>env</literal> attribute of a derivation. For example, let's say
|
|
we want to access an Erlang REPL with <literal>ibrowse</literal> loaded
|
|
up. We could do the following:
|
|
</para>
|
|
<programlisting>
|
|
$ nix-shell -A beamPackages.ibrowse.env --run "erl"
|
|
Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
|
|
|
|
Eshell V7.0 (abort with ^G)
|
|
1> m(ibrowse).
|
|
Module: ibrowse
|
|
MD5: 3b3e0137d0cbb28070146978a3392945
|
|
Compiled: January 10 2016, 23:34
|
|
Object file: /nix/store/g1rlf65rdgjs4abbyj4grp37ry7ywivj-ibrowse-4.2.2/lib/erlang/lib/ibrowse-4.2.2/ebin/ibrowse.beam
|
|
Compiler options: [{outdir,"/tmp/nix-build-ibrowse-4.2.2.drv-0/hex-source-ibrowse-4.2.2/_build/default/lib/ibrowse/ebin"},
|
|
debug_info,debug_info,nowarn_shadow_vars,
|
|
warn_unused_import,warn_unused_vars,warnings_as_errors,
|
|
{i,"/tmp/nix-build-ibrowse-4.2.2.drv-0/hex-source-ibrowse-4.2.2/_build/default/lib/ibrowse/include"}]
|
|
Exports:
|
|
add_config/1 send_req_direct/7
|
|
all_trace_off/0 set_dest/3
|
|
code_change/3 set_max_attempts/3
|
|
get_config_value/1 set_max_pipeline_size/3
|
|
get_config_value/2 set_max_sessions/3
|
|
get_metrics/0 show_dest_status/0
|
|
get_metrics/2 show_dest_status/1
|
|
handle_call/3 show_dest_status/2
|
|
handle_cast/2 spawn_link_worker_process/1
|
|
handle_info/2 spawn_link_worker_process/2
|
|
init/1 spawn_worker_process/1
|
|
module_info/0 spawn_worker_process/2
|
|
module_info/1 start/0
|
|
rescan_config/0 start_link/0
|
|
rescan_config/1 stop/0
|
|
send_req/3 stop_worker_process/1
|
|
send_req/4 stream_close/1
|
|
send_req/5 stream_next/1
|
|
send_req/6 terminate/2
|
|
send_req_direct/4 trace_off/0
|
|
send_req_direct/5 trace_off/2
|
|
send_req_direct/6 trace_on/0
|
|
trace_on/2
|
|
ok
|
|
2>
|
|
</programlisting>
|
|
<para>
|
|
Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
|
|
to this functionality.
|
|
</para>
|
|
</section>
|
|
<section xml:id="creating-a-shell">
|
|
<title>Creating a Shell</title>
|
|
<para>
|
|
Getting access to an environment often isn't enough to do real
|
|
development. Usually, we need to create a <literal>shell.nix</literal>
|
|
file and do our development inside of the environment specified therein.
|
|
This file looks a lot like the packaging described above, except that
|
|
<literal>src</literal> points to the project root and we call the package
|
|
directly.
|
|
</para>
|
|
<programlisting>
|
|
{ pkgs ? import "<nixpkgs"> {} }:
|
|
|
|
with pkgs;
|
|
|
|
let
|
|
|
|
f = { buildRebar3, ibrowse, jsx, erlware_commons }:
|
|
buildRebar3 {
|
|
name = "hex2nix";
|
|
version = "0.1.0";
|
|
src = ./.;
|
|
beamDeps = [ ibrowse jsx erlware_commons ];
|
|
};
|
|
drv = beamPackages.callPackage f {};
|
|
|
|
in
|
|
|
|
drv
|
|
</programlisting>
|
|
<section xml:id="building-in-a-shell">
|
|
<title>Building in a Shell (for Mix Projects)</title>
|
|
<para>
|
|
We can leverage the support of the derivation, irrespective of the build
|
|
derivation, by calling the commands themselves.
|
|
</para>
|
|
<programlisting>
|
|
# =============================================================================
|
|
# Variables
|
|
# =============================================================================
|
|
|
|
NIX_TEMPLATES := "$(CURDIR)/nix-templates"
|
|
|
|
TARGET := "$(PREFIX)"
|
|
|
|
PROJECT_NAME := thorndyke
|
|
|
|
NIXPKGS=../nixpkgs
|
|
NIX_PATH=nixpkgs=$(NIXPKGS)
|
|
NIX_SHELL=nix-shell -I "$(NIX_PATH)" --pure
|
|
# =============================================================================
|
|
# Rules
|
|
# =============================================================================
|
|
.PHONY= all test clean repl shell build test analyze configure install \
|
|
test-nix-install publish plt analyze
|
|
|
|
all: build
|
|
|
|
guard-%:
|
|
@ if [ "${${*}}" == "" ]; then \
|
|
echo "Environment variable $* not set"; \
|
|
exit 1; \
|
|
fi
|
|
|
|
clean:
|
|
rm -rf _build
|
|
rm -rf .cache
|
|
|
|
repl:
|
|
$(NIX_SHELL) --run "iex -pa './_build/prod/lib/*/ebin'"
|
|
|
|
shell:
|
|
$(NIX_SHELL)
|
|
|
|
configure:
|
|
$(NIX_SHELL) --command 'eval "$$configurePhase"'
|
|
|
|
build: configure
|
|
$(NIX_SHELL) --command 'eval "$$buildPhase"'
|
|
|
|
install:
|
|
$(NIX_SHELL) --command 'eval "$$installPhase"'
|
|
|
|
test:
|
|
$(NIX_SHELL) --command 'mix test --no-start --no-deps-check'
|
|
|
|
plt:
|
|
$(NIX_SHELL) --run "mix dialyzer.plt --no-deps-check"
|
|
|
|
analyze: build plt
|
|
$(NIX_SHELL) --run "mix dialyzer --no-compile"
|
|
|
|
</programlisting>
|
|
<para>
|
|
Using a <literal>shell.nix</literal> as described (see <xref
|
|
linkend="creating-a-shell"/>) should just work. Aside from
|
|
<literal>test</literal>, <literal>plt</literal>, and
|
|
<literal>analyze</literal>, the Make targets work just fine for all of the
|
|
build derivations.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section xml:id="generating-packages-from-hex-with-hex2nix">
|
|
<title>Generating Packages from Hex with <literal>hex2nix</literal></title>
|
|
<para>
|
|
Updating the <link xlink:href="https://hex.pm">Hex</link> package set
|
|
requires <link
|
|
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>. Given the
|
|
path to the Erlang modules (usually
|
|
<literal>pkgs/development/erlang-modules</literal>), it will dump a file
|
|
called <literal>hex-packages.nix</literal>, containing all the packages that
|
|
use a recognized build system in <link
|
|
xlink:href="https://hex.pm">Hex</link>. It can't be determined, however,
|
|
whether every package is buildable.
|
|
</para>
|
|
<para>
|
|
To make life easier for our users, try to build every <link
|
|
xlink:href="https://hex.pm">Hex</link> package and remove those that fail.
|
|
To do that, simply run the following command in the root of your
|
|
<literal>nixpkgs</literal> repository:
|
|
</para>
|
|
<programlisting>
|
|
$ nix-build -A beamPackages
|
|
</programlisting>
|
|
<para>
|
|
That will attempt to build every package in
|
|
<literal>beamPackages</literal>. Then manually remove those that fail.
|
|
Hopefully, someone will improve <link
|
|
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> in the
|
|
future to automate the process.
|
|
</para>
|
|
</section>
|
|
</section>
|