diff options
Diffstat (limited to 'doc/languages-frameworks/beam.xml')
| -rw-r--r-- | doc/languages-frameworks/beam.xml | 500 |
1 files changed, 277 insertions, 223 deletions
diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index 1a18ed27237c..ac7a83ed4265 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -1,124 +1,137 @@ <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> - <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> + <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> - 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>. + <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> - 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>. + <literal>packages</literal>: a set of package sets, each compiled with a + specific Erlang/OTP version, e.g. + <literal>beam.packages.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"> + </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 + <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> + </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> + <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> -<section xml:id="how-to-install-beam-packages"> + <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: + 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> +<programlisting> $ nix-env -f "<nixpkgs>" -qaP -A beamPackages beamPackages.esqlite esqlite-0.2.1 beamPackages.goldrush goldrush-0.1.7 @@ -128,34 +141,43 @@ 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): + To install any of those packages into your profile, refer to them by their + attribute path (first column): </para> - <programlisting> + +<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. + 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"> + </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> + <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 { @@ -172,33 +194,40 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse 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> + + <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 { @@ -222,14 +251,17 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse }; } </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> + </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 { @@ -253,10 +285,12 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse }; } </programlisting> - <para> - Alternatively, we can use <literal>buildHex</literal> as a shortcut: - </para> - <programlisting> + + <para> + Alternatively, we can use <literal>buildHex</literal> as a shortcut: + </para> + +<programlisting> { buildHex, buildMix, plug, absinthe }: buildHex { @@ -278,21 +312,25 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse }; } </programlisting> - </section> + </section> </section> -</section> -<section xml:id="how-to-develop"> + </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> + <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] @@ -333,22 +371,25 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse ok 2> </programlisting> - <para> - Notice the <literal>-A beamPackages.ibrowse.env</literal>. That is the key - to this functionality. - </para> + + <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> + <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; @@ -368,13 +409,16 @@ in drv </programlisting> - <section xml:id="building-in-a-shell"> + + <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. + We can leverage the support of the derivation, irrespective of the build + derivation, by calling the commands themselves. </para> - <programlisting> + +<programlisting> # ============================================================================= # Variables # ============================================================================= @@ -431,44 +475,54 @@ analyze: build plt $(NIX_SHELL) --run "mix dialyzer --no-compile" </programlisting> + <para> - Using a <literal>shell.nix</literal> as described (see <xref + 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. + <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> -<section xml:id="generating-packages-from-hex-with-hex2nix"> + </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> + 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> + + <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> |