diff --git a/doc/default.nix b/doc/default.nix index 540a209c2ac9..cfd51fba257e 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -26,7 +26,7 @@ pkgs.stdenv.mkDerivation { extraHeader = ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" ''; in '' { - pandoc '${inputFile}' -w docbook ${lib.optionalString useChapters "--chapters"} \ + pandoc '${inputFile}' -w docbook ${lib.optionalString useChapters "--top-level-division=chapter"} \ --smart \ | sed -e 's|||' \ diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index 28dec9f77dea..1a18ed27237c 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -2,30 +2,29 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-beam"> - Beam Languages (Erlang, Elixir & LFE) + 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 Virtial Machine and, as far as we know, - from a packaging perspective all languages that run on BEAM are - interchangable. The things that do change, like the build - system, are transperant to the users of the package. So we make - no distinction. + 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 things are available via top-level + All BEAM-related expressions are available via the top-level beam attribute, which includes: - interpreters: contains a set of compilers running - on Beam, including multiple Erlang/OTP versions + 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). @@ -33,36 +32,37 @@ - packages: contains a set of package sets, each - compiled with a specific Erlang/OTP version, e.g. + packages: a set of package sets, each compiled with + a specific Erlang/OTP version, e.g. beam.packages.erlangR19. - Default Erlang compiler is defined by - beam.interpreters.erlang and aliased as - erlang. Default package set with Beam packages is - defined by beam.packages.erlang and aliased at - top-level as beamPackages. + 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. - If you want to create a package set built with a custom Erlang version, - use lambda beam.packagesWith, which accepts an - Erlang/OTP derivative and produces a package set similar to + To create a package set built with a custom Erlang version, use the + lambda, beam.packagesWith, which accepts an Erlang/OTP + derivation and produces a package set similar to beam.packages.erlang. Many Erlang/OTP distributions available in - beam.interpreters have their versions with ODBC and/or - Java enabled. For example there's - beam.interpreters.erlangR19_odbc_javac which + beam.interpreters have versions with ODBC and/or Java + enabled. For example, there's + beam.interpreters.erlangR19_odbc_javac, which corresponds to beam.interpreters.erlangR19. - - We also provide beam.packages.erlang.callPackage, which - simplifies writing Beam package definitions, by injecting all packages from - beam.packages.erlang into top-level context. + + We also provide the lambda, + beam.packages.erlang.callPackage, which simplifies + writing BEAM package definitions by injecting all packages from + beam.packages.erlang into the top-level context.
@@ -70,42 +70,52 @@
Rebar3 - By default Rebar3 wants to manage it's own dependencies. This is perfectly - acceptable in the normal non-Nix setup. In the Nix world it is not. To - support this we have created two versions of rebar3, - rebar3 and rebar3-open. The - rebar3 version has been patched to remove the ability - to download anything from it. If you are not running it a nix-shell or a - nix-build then its probably not going to work for you. - rebar3-open is the normal, un-modified rebar3. It - should work exactly as would any other version of rebar3. Any Erlang - package should rely on rebar3 and thats really what you - should be using too. See buildRebar3 below. + 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: + + + + rebar3: patched to remove the ability to download + anything. When not running it via nix-shell or + nix-build, it's probably not going to work as + desired. + + + + + rebar3-open: the normal, unmodified Rebar3. It + should work exactly as would any other version of Rebar3. Any Erlang + package should rely on rebar3 instead. See . + + +
Mix & Erlang.mk - Both Mix and Erlang.mk work exactly as you would expect. There - is a bootstrap process that needs to be run for both of - them. However, that is supported by the - buildMix and buildErlangMk derivations. + 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 + How to Install BEAM Packages - Beam packages are not registered in the top level simply because they are + 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 beam.packages.erlang attribute set and aliased as - beamPackages. This attribute points at packages built by - the default Erlang/OTP version in Nixpkgs as defined by + the beam.packages.erlang attribute set (aliased as + beamPackages), which points to packages built by the + default Erlang/OTP version in Nixpkgs, as defined by beam.interpreters.erlang. - You can list the avialable packages in the - beamPackages with the following command: + To list the available packages in + beamPackages, use the following command: @@ -119,145 +129,152 @@ beamPackages.meck meck-0.8.3 beamPackages.rebar3-pc pc-1.1.0 - 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): $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse - The attribute path of any Beam packages corresponds to the name - of that particular package in Hex or its OTP Application/Release name. + The attribute path of any BEAM package corresponds to the name of that + particular package in Hex or its + OTP Application/Release name.
- Packaging Beam Applications + Packaging BEAM Applications
Erlang Applications
Rebar3 Packages - There is a Nix function called buildRebar3 (defined - in beam.packages.erlang.buildRebar3 and aliased at - top-level). We use this function to make a derivation that understands - how to build the rebar3 project. For example, the expression we use to - build the hex2nix - project follows. + 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. For example, we can build hex2nix as + follows: - {stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }: + { stdenv, fetchFromGitHub, buildRebar3, ibrowse, jsx, erlware_commons }: - buildRebar3 rec { - name = "hex2nix"; - version = "0.0.1"; + buildRebar3 rec { + name = "hex2nix"; + version = "0.0.1"; - src = fetchFromGitHub { - owner = "ericbmerritt"; - repo = "hex2nix"; - rev = "${version}"; - sha256 = "1w7xjidz1l5yjmhlplfx7kphmnpvqm67w99hd2m7kdixwdxq0zqg"; - }; + src = fetchFromGitHub { + owner = "ericbmerritt"; + repo = "hex2nix"; + rev = "${version}"; + sha256 = "1w7xjidz1l5yjmhlplfx7kphmnpvqm67w99hd2m7kdixwdxq0zqg"; + }; beamDeps = [ ibrowse jsx erlware_commons ]; } - This derivation is callable with - beam.packages.erlang.callPackage (see above). If you - want to call this package using normal callPackage, - you should refer to dependency packages via + Such derivations are callable with + beam.packages.erlang.callPackage (see ). To call this package using the normal + callPackage, refer to dependency packages via beamPackages, e.g. beamPackages.ibrowse. - The only visible difference between this derivation and - something like stdenv.mkDerivation is that we - have added beamDeps to the derivation. If - you add your Beam dependencies here they will be correctly - handled by the system. + Notably, buildRebar3 includes + beamDeps, while + stdenv.mkDerivation does not. BEAM dependencies added + there will be correctly handled by the system. - If your package needs to compile native code via Rebar's port - compilation mechenism. You should add compilePort = - true; to the derivation. + 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 almost identically to Rebar. The only real - difference is that buildErlangMk is called - instead of buildRebar3 + Erlang.mk functions similarly to Rebar3, except we use + buildErlangMk instead of + buildRebar3. - { buildErlangMk, fetchHex, cowlib, ranch }: - buildErlangMk { - name = "cowboy"; - version = "1.0.4"; - src = fetchHex { - pkg = "cowboy"; - version = "1.0.4"; - sha256 = - "6a0edee96885fae3a8dd0ac1f333538a42e807db638a9453064ccfdaa6b9fdac"; - }; - beamDeps = [ cowlib ranch ]; + { buildErlangMk, fetchHex, cowlib, ranch }: - meta = { - description = ''Small, fast, modular HTTP server written in - Erlang.''; - license = stdenv.lib.licenses.isc; - homepage = "https://github.com/ninenines/cowboy"; - }; + 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; + }; }
Mix Packages - Mix functions almost identically to Rebar. The only real - difference is that buildMix is called - instead of buildRebar3 + Mix functions similarly to Rebar3, except we use + buildMix instead of buildRebar3. { buildMix, fetchHex, plug, absinthe }: + buildMix { name = "absinthe_plug"; version = "1.0.0"; + src = fetchHex { pkg = "absinthe_plug"; version = "1.0.0"; - sha256 = - "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; + sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; }; - beamDeps = [ plug absinthe ]; + + beamDeps = [ plug absinthe ]; meta = { - description = ''A plug for Absinthe, an experimental GraphQL - toolkit''; + description = '' + A plug for Absinthe, an experimental GraphQL toolkit + ''; license = stdenv.lib.licenses.bsd3; - homepage = "https://github.com/CargoSense/absinthe_plug"; - }; - } + homepage = https://github.com/CargoSense/absinthe_plug; + }; + } - Alternatively one can use buildHex as a shortcut for the above: + Alternatively, we can use buildHex as a shortcut: { buildHex, buildMix, plug, absinthe }: + buildHex { name = "absinthe_plug"; version = "1.0.0"; - sha256 = - "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; + + sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; + builder = buildMix; - beamDeps = [ plug absinthe]; + + beamDeps = [ plug absinthe ]; meta = { - description = ''A plug for Absinthe, an experimental GraphQL - toolkit''; + description = '' + A plug for Absinthe, an experimental GraphQL toolkit + ''; license = stdenv.lib.licenses.bsd3; - homepage = "https://github.com/CargoSense/absinthe_plug"; + homepage = https://github.com/CargoSense/absinthe_plug; }; } @@ -265,18 +282,18 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse
- How to develop + How to Develop
Accessing an Environment - Often, all you want to do is be able to access a valid - environment that contains a specific package and its - dependencies. we can do that with the env - part of a derivation. For example, lets say we want to access an - erlang repl with ibrowse loaded up. We could do the following. + Often, we simply want to access a valid environment that contains a + specific package and its dependencies. We can accomplish that with the + env attribute of a derivation. For example, let's say + we want to access an Erlang REPL with ibrowse loaded + up. We could do the following: - ~/w/nixpkgs ❯❯❯ nix-shell -A beamPackages.ibrowse.env --run "erl" + $ 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) @@ -317,20 +334,19 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse 2> - Notice the -A beamPackages.ibrowse.env.That - is the key to this functionality. + Notice the -A beamPackages.ibrowse.env. That is the key + to this functionality.
Creating a Shell Getting access to an environment often isn't enough to do real - development. Many times we need to create a - shell.nix file and do our development inside - of the environment specified by that file. This file looks a lot - like the packaging described above. The main difference is that - src points to project root and we call the - package directly. + development. Usually, we need to create a shell.nix + file and do our development inside of the environment specified therein. + This file looks a lot like the packaging described above, except that + src points to the project root and we call the package + directly. { pkgs ? import "<nixpkgs"> {} }: @@ -349,13 +365,14 @@ let drv = beamPackages.callPackage f {}; in - drv + + drv
- Building in a shell (for mix projects) + Building in a Shell (for Mix Projects) - We can leverage the support of the Derivation, regardless of - which build Derivation is called by calling the commands themselves. + We can leverage the support of the derivation, irrespective of the build + derivation, by calling the commands themselves. # ============================================================================= @@ -415,42 +432,43 @@ analyze: build plt - If you add the shell.nix as described and - user rebar as follows things should simply work. Aside from the + Using a shell.nix as described (see ) should just work. Aside from test, plt, and - analyze the talks work just fine for all of - the build Derivations. + analyze, the Make targets work just fine for all of the + build derivations.
- Generating Packages from Hex with Hex2Nix + Generating Packages from Hex with <literal>hex2nix</literal> - Updating the Hex packages requires the use of the - hex2nix tool. Given the path to the Erlang - modules (usually - pkgs/development/erlang-modules). It will - dump a file called - hex-packages.nix. That file will contain all - the packages that use a recognized build system in Hex. However, - it can't know whether or not all those packages are buildable. + Updating the Hex package set + requires hex2nix. Given the + path to the Erlang modules (usually + pkgs/development/erlang-modules), it will dump a file + called hex-packages.nix, containing all the packages that + use a recognized build system in Hex. It can't be determined, however, + whether every package is buildable. - To make life easier for our users, it makes good sense to go - ahead and attempt to build all those packages and remove the - ones that don't build. To do that, simply run the command (in - the root of your nixpkgs repository). that follows. + To make life easier for our users, try to build every Hex package and remove those that fail. + To do that, simply run the following command in the root of your + nixpkgs repository: $ nix-build -A beamPackages - That will build every package in - beamPackages. Then you can go through and - manually remove the ones that fail. Hopefully, someone will - improve hex2nix in the future to automate - that. + That will attempt to build every package in + beamPackages. Then manually remove those that fail. + Hopefully, someone will improve hex2nix in the + future to automate the process.