···
xmlns:xlink="http://www.w3.org/1999/xlink"
5
-
<title>Beam Languages (Erlang & Elixir)</title>
5
+
<title>BEAM Languages (Erlang, Elixir & LFE)</title>
<section xml:id="beam-introduction">
<title>Introduction</title>
9
-
In this document and related Nix expressions we use the term
10
-
<emphasis>Beam</emphasis> to describe the environment. Beam is
11
-
the name of the Erlang Virtial Machine and, as far as we know,
12
-
from a packaging perspective all languages that run on Beam are
13
-
interchangable. The things that do change, like the build
14
-
system, are transperant to the users of the package. So we make
9
+
In this document and related Nix expressions, we use the term,
10
+
<emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name
11
+
of the Erlang Virtual Machine and, as far as we're concerned, from a
12
+
packaging perspective, all languages that run on the BEAM are
13
+
interchangeable. That which varies, like the build system, is transparent
14
+
to users of any given BEAM package, so we make no distinction.
17
+
<section xml:id="beam-structure">
18
+
<title>Structure</title>
20
+
All BEAM-related expressions are available via the top-level
21
+
<literal>beam</literal> attribute, which includes:
26
+
<literal>interpreters</literal>: a set of compilers running on the
27
+
BEAM, including multiple Erlang/OTP versions
28
+
(<literal>beam.interpreters.erlangR19</literal>, etc), Elixir
29
+
(<literal>beam.interpreters.elixir</literal>) and LFE
30
+
(<literal>beam.interpreters.lfe</literal>).
35
+
<literal>packages</literal>: a set of package sets, each compiled with
36
+
a specific Erlang/OTP version, e.g.
37
+
<literal>beam.packages.erlangR19</literal>.
42
+
The default Erlang compiler, defined by
43
+
<literal>beam.interpreters.erlang</literal>, is aliased as
44
+
<literal>erlang</literal>. The default BEAM package set is defined by
45
+
<literal>beam.packages.erlang</literal> and aliased at the top level as
46
+
<literal>beamPackages</literal>.
49
+
To create a package set built with a custom Erlang version, use the
50
+
lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP
51
+
derivation and produces a package set similar to
52
+
<literal>beam.packages.erlang</literal>.
55
+
Many Erlang/OTP distributions available in
56
+
<literal>beam.interpreters</literal> have versions with ODBC and/or Java
57
+
enabled. For example, there's
58
+
<literal>beam.interpreters.erlangR19_odbc_javac</literal>, which
59
+
corresponds to <literal>beam.interpreters.erlangR19</literal>.
61
+
<para xml:id="erlang-call-package">
62
+
We also provide the lambda,
63
+
<literal>beam.packages.erlang.callPackage</literal>, which simplifies
64
+
writing BEAM package definitions by injecting all packages from
65
+
<literal>beam.packages.erlang</literal> into the top-level context.
18
-
<section xml:id="build-tools">
68
+
<section xml:id="build-tools">
<title>Build Tools</title>
<section xml:id="build-tools-rebar3">
23
-
By default Rebar3 wants to manage it's own dependencies. In the
24
-
normal non-Nix, this is perfectly acceptable. In the Nix world it
25
-
is not. To support this we have created two versions of rebar3,
26
-
<literal>rebar3</literal> and <literal>rebar3-open</literal>. The
27
-
<literal>rebar3</literal> version has been patched to remove the
28
-
ability to download anything from it. If you are not running it a
29
-
nix-shell or a nix-build then its probably not going to work for
30
-
you. <literal>rebar3-open</literal> is the normal, un-modified
31
-
rebar3. It should work exactly as would any other version of
32
-
rebar3. Any Erlang package should rely on
33
-
<literal>rebar3</literal> and thats really what you should be
73
+
By default, Rebar3 wants to manage its own dependencies. This is perfectly
74
+
acceptable in the normal, non-Nix setup, but in the Nix world, it is not.
75
+
To rectify this, we provide two versions of Rebar3:
79
+
<literal>rebar3</literal>: patched to remove the ability to download
80
+
anything. When not running it via <literal>nix-shell</literal> or
81
+
<literal>nix-build</literal>, it's probably not going to work as
87
+
<literal>rebar3-open</literal>: the normal, unmodified Rebar3. It
88
+
should work exactly as would any other version of Rebar3. Any Erlang
89
+
package should rely on <literal>rebar3</literal> instead. See <xref
90
+
linkend="rebar3-packages"/>.
<section xml:id="build-tools-other">
<title>Mix & Erlang.mk</title>
40
-
Both Mix and Erlang.mk work exactly as you would expect. There
41
-
is a bootstrap process that needs to be run for both of
42
-
them. However, that is supported by the
43
-
<literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations.
99
+
Both Mix and Erlang.mk work exactly as expected. There is a bootstrap
100
+
process that needs to be run for both, however, which is supported by the
101
+
<literal>buildMix</literal> and <literal>buildErlangMk</literal>
102
+
derivations, respectively.
<section xml:id="how-to-install-beam-packages">
50
-
<title>How to install Beam packages</title>
108
+
<title>How to Install BEAM Packages</title>
52
-
Beam packages are not registered in the top level simply because
53
-
they are not relevant to the vast majority of Nix users. They are
54
-
installable using the <literal>beamPackages</literal> attribute
110
+
BEAM packages are not registered at the top level, simply because they are
111
+
not relevant to the vast majority of Nix users. They are installable using
112
+
the <literal>beam.packages.erlang</literal> attribute set (aliased as
113
+
<literal>beamPackages</literal>), which points to packages built by the
114
+
default Erlang/OTP version in Nixpkgs, as defined by
115
+
<literal>beam.interpreters.erlang</literal>.
57
-
You can list the avialable packages in the
58
-
<literal>beamPackages</literal> with the following command:
117
+
To list the available packages in
118
+
<literal>beamPackages</literal>, use the following command:
···
beamPackages.rebar3-pc pc-1.1.0
72
-
To install any of those packages into your profile, refer to them by
73
-
their attribute path (first column):
132
+
To install any of those packages into your profile, refer to them by their
133
+
attribute path (first column):
$ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse
79
-
The attribute path of any Beam packages corresponds to the name
80
-
of that particular package in Hex or its OTP Application/Release name.
139
+
The attribute path of any BEAM package corresponds to the name of that
140
+
particular package in <link xlink:href="https://hex.pm">Hex</link> or its
141
+
OTP Application/Release name.
<section xml:id="packaging-beam-applications">
84
-
<title>Packaging Beam Applications</title>
145
+
<title>Packaging BEAM Applications</title>
<section xml:id="packaging-erlang-applications">
<title>Erlang Applications</title>
<section xml:id="rebar3-packages">
<title>Rebar3 Packages</title>
90
-
There is a Nix functional called
91
-
<literal>buildRebar3</literal>. We use this function to make a
92
-
derivation that understands how to build the rebar3 project. For
93
-
example, the epression we use to build the <link
94
-
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>
151
+
The Nix function, <literal>buildRebar3</literal>, defined in
152
+
<literal>beam.packages.erlang.buildRebar3</literal> and aliased at the
153
+
top level, can be used to build a derivation that understands how to
154
+
build a Rebar3 project. For example, we can build <link
155
+
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> as
98
-
{stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }:
159
+
{ stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }:
104
-
src = fetchFromGitHub {
105
-
owner = "ericbmerritt";
107
-
rev = "${version}";
108
-
sha256 = "1w7xjidz1l5yjmhlplfx7kphmnpvqm67w99hd2m7kdixwdxq0zqg";
165
+
src = fetchFromGitHub {
166
+
owner = "ericbmerritt";
168
+
rev = "${version}";
169
+
sha256 = "1w7xjidz1l5yjmhlplfx7kphmnpvqm67w99hd2m7kdixwdxq0zqg";
beamDeps = [ ibrowse jsx erlware_commons ];
115
-
The only visible difference between this derivation and
116
-
something like <literal>stdenv.mkDerivation</literal> is that we
117
-
have added <literal>erlangDeps</literal> to the derivation. If
118
-
you add your Beam dependencies here they will be correctly
119
-
handled by the system.
176
+
Such derivations are callable with
177
+
<literal>beam.packages.erlang.callPackage</literal> (see <xref
178
+
linkend="erlang-call-package"/>). To call this package using the normal
179
+
<literal>callPackage</literal>, refer to dependency packages via
180
+
<literal>beamPackages</literal>, e.g.
181
+
<literal>beamPackages.ibrowse</literal>.
122
-
If your package needs to compile native code via Rebar's port
123
-
compilation mechenism. You should add <literal>compilePort =
124
-
true;</literal> to the derivation.
184
+
Notably, <literal>buildRebar3</literal> includes
185
+
<literal>beamDeps</literal>, while
186
+
<literal>stdenv.mkDerivation</literal> does not. BEAM dependencies added
187
+
there will be correctly handled by the system.
190
+
If a package needs to compile native code via Rebar3's port compilation
191
+
mechanism, add <literal>compilePort = true;</literal> to the derivation.
<section xml:id="erlang-mk-packages">
<title>Erlang.mk Packages</title>
130
-
Erlang.mk functions almost identically to Rebar. The only real
131
-
difference is that <literal>buildErlangMk</literal> is called
132
-
instead of <literal>buildRebar3</literal>
197
+
Erlang.mk functions similarly to Rebar3, except we use
198
+
<literal>buildErlangMk</literal> instead of
199
+
<literal>buildRebar3</literal>.
135
-
{ buildErlangMk, fetchHex, cowlib, ranch }:
202
+
{ buildErlangMk, fetchHex, cowlib, ranch }:
143
-
"6a0edee96885fae3a8dd0ac1f333538a42e807db638a9453064ccfdaa6b9fdac";
145
-
beamDeps = [ cowlib ranch ];
211
+
sha256 = "6a0edee96885fae3a8dd0ac1f333538a42e807db638a9453064ccfdaa6b9fdac";
214
+
beamDeps = [ cowlib ranch ];
148
-
description = ''Small, fast, modular HTTP server written in
150
-
license = stdenv.lib.licenses.isc;
151
-
homepage = "https://github.com/ninenines/cowboy";
218
+
Small, fast, modular HTTP server written in Erlang
220
+
license = stdenv.lib.licenses.isc;
221
+
homepage = https://github.com/ninenines/cowboy;
<section xml:id="mix-packages">
<title>Mix Packages</title>
159
-
Mix functions almost identically to Rebar. The only real
160
-
difference is that <literal>buildMix</literal> is called
161
-
instead of <literal>buildRebar3</literal>
229
+
Mix functions similarly to Rebar3, except we use
230
+
<literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
{ buildMix, fetchHex, plug, absinthe }:
172
-
"08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33";
242
+
sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33";
245
+
beamDeps = [ plug absinthe ];
249
+
A plug for Absinthe, an experimental GraphQL toolkit
251
+
license = stdenv.lib.licenses.bsd3;
252
+
homepage = https://github.com/CargoSense/absinthe_plug;
174
-
beamDeps = [ plug absinthe];
257
+
Alternatively, we can use <literal>buildHex</literal> as a shortcut:
260
+
{ buildHex, buildMix, plug, absinthe }:
263
+
name = "absinthe_plug";
266
+
sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33";
268
+
builder = buildMix;
270
+
beamDeps = [ plug absinthe ];
177
-
description = ''A plug for Absinthe, an experimental GraphQL
274
+
A plug for Absinthe, an experimental GraphQL toolkit
license = stdenv.lib.licenses.bsd3;
180
-
homepage = "https://github.com/CargoSense/absinthe_plug";
277
+
homepage = https://github.com/CargoSense/absinthe_plug;
···
<section xml:id="how-to-develop">
188
-
<title>How to develop</title>
285
+
<title>How to Develop</title>
<section xml:id="accessing-an-environment">
<title>Accessing an Environment</title>
192
-
Often, all you want to do is be able to access a valid
193
-
environment that contains a specific package and its
194
-
dependencies. we can do that with the <literal>env</literal>
195
-
part of a derivation. For example, lets say we want to access an
196
-
erlang repl with ibrowse loaded up. We could do the following.
289
+
Often, we simply want to access a valid environment that contains a
290
+
specific package and its dependencies. We can accomplish that with the
291
+
<literal>env</literal> attribute of a derivation. For example, let's say
292
+
we want to access an Erlang REPL with <literal>ibrowse</literal> loaded
293
+
up. We could do the following:
199
-
~/w/nixpkgs ❯❯❯ nix-shell -A beamPackages.ibrowse.env --run "erl"
296
+
$ 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)
···
240
-
Notice the <literal>-A beamPackages.ibrowse.env</literal>.That
241
-
is the key to this functionality.
337
+
Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key
338
+
to this functionality.
<section xml:id="creating-a-shell">
<title>Creating a Shell</title>
Getting access to an environment often isn't enough to do real
248
-
development. Many times we need to create a
249
-
<literal>shell.nix</literal> file and do our development inside
250
-
of the environment specified by that file. This file looks a lot
251
-
like the packaging described above. The main difference is that
252
-
<literal>src</literal> points to project root and we call the
345
+
development. Usually, we need to create a <literal>shell.nix</literal>
346
+
file and do our development inside of the environment specified therein.
347
+
This file looks a lot like the packaging described above, except that
348
+
<literal>src</literal> points to the project root and we call the package
{ pkgs ? import "<nixpkgs"> {} }:
···
267
-
erlangDeps = [ ibrowse jsx erlware_commons ];
363
+
beamDeps = [ ibrowse jsx erlware_commons ];
drv = beamPackages.callPackage f {};
<section xml:id="building-in-a-shell">
275
-
<title>Building in a shell</title>
372
+
<title>Building in a Shell (for Mix Projects)</title>
277
-
We can leveral the support of the Derivation, regardless of
278
-
which build Derivation is called by calling the commands themselv.s
374
+
We can leverage the support of the derivation, irrespective of the build
375
+
derivation, by calling the commands themselves.
# =============================================================================
···
338
-
If you add the <literal>shell.nix</literal> as described and
339
-
user rebar as follows things should simply work. Aside from the
435
+
Using a <literal>shell.nix</literal> as described (see <xref
436
+
linkend="creating-a-shell"/>) should just work. Aside from
<literal>test</literal>, <literal>plt</literal>, and
341
-
<literal>analyze</literal> the talks work just fine for all of
342
-
the build Derivations.
438
+
<literal>analyze</literal>, the Make targets work just fine for all of the
<section xml:id="generating-packages-from-hex-with-hex2nix">
348
-
<title>Generating Packages from Hex with Hex2Nix</title>
445
+
<title>Generating Packages from Hex with <literal>hex2nix</literal></title>
350
-
Updating the Hex packages requires the use of the
351
-
<literal>hex2nix</literal> tool. Given the path to the Erlang
353
-
<literal>pkgs/development/erlang-modules</literal>). It will
354
-
happily dump a file called
355
-
<literal>hex-packages.nix</literal>. That file will contain all
356
-
the packages that use a recognized build system in Hex. However,
357
-
it can't know whether or not all those packages are buildable.
447
+
Updating the <link xlink:href="https://hex.pm">Hex</link> package set
449
+
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>. Given the
450
+
path to the Erlang modules (usually
451
+
<literal>pkgs/development/erlang-modules</literal>), it will dump a file
452
+
called <literal>hex-packages.nix</literal>, containing all the packages that
453
+
use a recognized build system in <link
454
+
xlink:href="https://hex.pm">Hex</link>. It can't be determined, however,
455
+
whether every package is buildable.
360
-
To make life easier for our users, it makes good sense to go
361
-
ahead and attempt to build all those packages and remove the
362
-
ones that don't build. To do that, simply run the command (in
363
-
the root of your <literal>nixpkgs</literal> repository). that follows.
458
+
To make life easier for our users, try to build every <link
459
+
xlink:href="https://hex.pm">Hex</link> package and remove those that fail.
460
+
To do that, simply run the following command in the root of your
461
+
<literal>nixpkgs</literal> repository:
$ nix-build -A beamPackages
369
-
That will build every package in
370
-
<literal>beamPackages</literal>. Then you can go through and
371
-
manually remove the ones that fail. Hopefully, someone will
372
-
improve <literal>hex2nix</literal> in the future to automate
467
+
That will attempt to build every package in
468
+
<literal>beamPackages</literal>. Then manually remove those that fail.
469
+
Hopefully, someone will improve <link
470
+
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> in the
471
+
future to automate the process.
pyrox.dev