3
0
Fork 0
forked from mirrors/nixpkgs

erlang: update documentation.

The documentation got a bit stale compared to actual contents of
nixpkgs. This commit focuses on updating existing docs, not on making
sure all details of beam packages are covered.
This commit is contained in:
Gleb Peregud 2017-06-18 23:05:18 +02:00
parent 7797e1a1dd
commit 0fccd5bba4
3 changed files with 120 additions and 42 deletions
doc/languages-frameworks
pkgs/development
beam-modules
tools/build-managers/rebar3

View file

@ -2,36 +2,85 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="sec-beam"> xml:id="sec-beam">
<title>Beam Languages (Erlang &amp; Elixir)</title> <title>Beam Languages (Erlang, Elixir &amp; LFE)</title>
<section xml:id="beam-introduction"> <section xml:id="beam-introduction">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
In this document and related Nix expressions we use the term In this document and related Nix expressions we use the term
<emphasis>Beam</emphasis> to describe the environment. Beam is <emphasis>Beam</emphasis> to describe the environment. BEAM is
the name of the Erlang Virtial Machine and, as far as we know, the name of the Erlang Virtial Machine and, as far as we know,
from a packaging perspective all languages that run on Beam are from a packaging perspective all languages that run on BEAM are
interchangable. The things that do change, like the build interchangable. The things that do change, like the build
system, are transperant to the users of the package. So we make system, are transperant to the users of the package. So we make
no distinction. no distinction.
</para> </para>
</section> </section>
<section xml:id="build-tools"> <section xml:id="beam-structure">
<title>Structure</title>
<para>
All Beam-related things are available via top-level
<literal>beam</literal> attribute, which includes:
</para>
<itemizedlist>
<listitem>
<para>
<literal>interpreters</literal>: contains a set of compilers running
on 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>: contains a set of package sets, each
compiled with a specific Erlang/OTP version, e.g.
<literal>beam.packages.erlangR19</literal>.
</para>
</listitem>
</itemizedlist>
<para>
Default Erlang compiler is defined by
<literal>beam.interpreters.erlang</literal> and aliased as
<literal>erlang</literal>. Default package set with Beam packages is
defined by <literal>beam.packages.erlang</literal> and aliased at
top-level as <literal>beamPackages</literal>.
</para>
<para>
If you want to create a package set built with a custom Erlang version,
use lambda <literal>beam.packagesWith</literal>, which accepts an
Erlang/OTP derivative 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 their 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>
We also provide <literal>beam.packages.erlang.callPackage</literal>, which
simplifies writing Beam package definitions, by injecting all packages from
<literal>beam.packages.erlang</literal> into top-level context.
</para>
</section>
<section xml:id="build-tools">
<title>Build Tools</title> <title>Build Tools</title>
<section xml:id="build-tools-rebar3"> <section xml:id="build-tools-rebar3">
<title>Rebar3</title> <title>Rebar3</title>
<para> <para>
By default Rebar3 wants to manage it's own dependencies. In the By default Rebar3 wants to manage it's own dependencies. This is perfectly
normal non-Nix, this is perfectly acceptable. In the Nix world it acceptable in the normal non-Nix setup. In the Nix world it is not. To
is not. To support this we have created two versions of rebar3, support this we have created two versions of rebar3,
<literal>rebar3</literal> and <literal>rebar3-open</literal>. The <literal>rebar3</literal> and <literal>rebar3-open</literal>. The
<literal>rebar3</literal> version has been patched to remove the <literal>rebar3</literal> version has been patched to remove the ability
ability to download anything from it. If you are not running it a to download anything from it. If you are not running it a nix-shell or a
nix-shell or a nix-build then its probably not going to work for nix-build then its probably not going to work for you.
you. <literal>rebar3-open</literal> is the normal, un-modified <literal>rebar3-open</literal> is the normal, un-modified rebar3. It
rebar3. It should work exactly as would any other version of should work exactly as would any other version of rebar3. Any Erlang
rebar3. Any Erlang package should rely on package should rely on <literal>rebar3</literal> and thats really what you
<literal>rebar3</literal> and thats really what you should be should be using too. See <literal>buildRebar3</literal> below.
using too.
</para> </para>
</section> </section>
<section xml:id="build-tools-other"> <section xml:id="build-tools-other">
@ -43,16 +92,17 @@
<literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations. <literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations.
</para> </para>
</section> </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> <title>How to install Beam packages</title>
<para> <para>
Beam packages are not registered in the top level simply because Beam packages are not registered in the top level simply because they are
they are not relevant to the vast majority of Nix users. They are not relevant to the vast majority of Nix users. They are installable using
installable using the <literal>beamPackages</literal> attribute the <literal>beam.packages.erlang</literal> attribute set and aliased as
set. <literal>beamPackages</literal>. This attribute points at packages built by
the default Erlang/OTP version in Nixpkgs as defined by
<literal>beam.interpreters.erlang</literal>.
You can list the avialable packages in the You can list the avialable packages in the
<literal>beamPackages</literal> with the following command: <literal>beamPackages</literal> with the following command:
@ -87,10 +137,11 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
<section xml:id="rebar3-packages"> <section xml:id="rebar3-packages">
<title>Rebar3 Packages</title> <title>Rebar3 Packages</title>
<para> <para>
There is a Nix functional called There is a Nix function called <literal>buildRebar3</literal> (defined
<literal>buildRebar3</literal>. We use this function to make a in <literal>beam.packages.erlang.buildRebar3</literal> and aliased at
derivation that understands how to build the rebar3 project. For top-level). We use this function to make a derivation that understands
example, the epression we use to build the <link how to build the rebar3 project. For example, the expression we use to
build the <link
xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link>
project follows. project follows.
</para> </para>
@ -111,10 +162,18 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
beamDeps = [ ibrowse jsx erlware_commons ]; beamDeps = [ ibrowse jsx erlware_commons ];
} }
</programlisting> </programlisting>
<para>
This derivation is callable with
<literal>beam.packages.erlang.callPackage</literal> (see above). If you
want to call this package using normal <literal>callPackage</literal>,
you should refer to dependency packages via
<literal>beamPackages</literal>, e.g.
<literal>beamPackages.ibrowse</literal>.
</para>
<para> <para>
The only visible difference between this derivation and The only visible difference between this derivation and
something like <literal>stdenv.mkDerivation</literal> is that we something like <literal>stdenv.mkDerivation</literal> is that we
have added <literal>erlangDeps</literal> to the derivation. If have added <literal>beamDeps</literal> to the derivation. If
you add your Beam dependencies here they will be correctly you add your Beam dependencies here they will be correctly
handled by the system. handled by the system.
</para> </para>
@ -171,6 +230,27 @@ $ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.ibrowse
sha256 = sha256 =
"08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; "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 one can use <literal>buildHex</literal> as a shortcut for the above:
</para>
<programlisting>
{ buildHex, buildMix, plug, absinthe }:
buildHex {
name = "absinthe_plug";
version = "1.0.0";
sha256 =
"08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33";
builder = buildMix;
beamDeps = [ plug absinthe]; beamDeps = [ plug absinthe];
meta = { meta = {
@ -264,7 +344,7 @@ let
name = "hex2nix"; name = "hex2nix";
version = "0.1.0"; version = "0.1.0";
src = ./.; src = ./.;
erlangDeps = [ ibrowse jsx erlware_commons ]; beamDeps = [ ibrowse jsx erlware_commons ];
}; };
drv = beamPackages.callPackage f {}; drv = beamPackages.callPackage f {};
@ -272,10 +352,10 @@ in
drv drv
</programlisting> </programlisting>
<section xml:id="building-in-a-shell"> <section xml:id="building-in-a-shell">
<title>Building in a shell</title> <title>Building in a shell (for mix projects)</title>
<para> <para>
We can leveral the support of the Derivation, regardless of We can leverage the support of the Derivation, regardless of
which build Derivation is called by calling the commands themselv.s which build Derivation is called by calling the commands themselves.
</para> </para>
<programlisting> <programlisting>
# ============================================================================= # =============================================================================
@ -351,7 +431,7 @@ analyze: build plt
<literal>hex2nix</literal> tool. Given the path to the Erlang <literal>hex2nix</literal> tool. Given the path to the Erlang
modules (usually modules (usually
<literal>pkgs/development/erlang-modules</literal>). It will <literal>pkgs/development/erlang-modules</literal>). It will
happily dump a file called dump a file called
<literal>hex-packages.nix</literal>. That file will contain all <literal>hex-packages.nix</literal>. That file will contain all
the packages that use a recognized build system in Hex. However, the packages that use a recognized build system in Hex. However,
it can't know whether or not all those packages are buildable. it can't know whether or not all those packages are buildable.

View file

@ -3,18 +3,16 @@
%%! -smp enable %%! -smp enable
%%% --------------------------------------------------------------------------- %%% ---------------------------------------------------------------------------
%%% @doc %%% @doc
%%% The purpose of this command is to prepare a rebar3 project so that %%% The purpose of this command is to prepare a mix project so that mix
%%% rebar3 understands that the dependencies are all already %%% understands that the dependencies are all already installed. If you want a
%%% installed. If you want a hygienic build on nix then you must run %%% hygienic build on nix then you must run this command before running mix. I
%%% this command before running rebar3. I suggest that you add a %%% suggest that you add a `Makefile` to your project and have the bootstrap
%%% `Makefile` to your project and have the bootstrap command be a %%% command be a dependency of the build commands. See the nix documentation for
%%% dependency of the build commands. See the nix documentation for
%%% more information. %%% more information.
%%% %%%
%%% This command designed to have as few dependencies as possible so %%% This command designed to have as few dependencies as possible so that it can
%%% that it can be a dependency of root level packages like rebar3. To %%% be a dependency of root level packages like mix. To that end it does many
%%% that end it does many things in a fairly simplistic way. That is %%% things in a fairly simplistic way. That is by design.
%%% by design.
%%% %%%
%%% ### Assumptions %%% ### Assumptions
%%% %%%
@ -37,7 +35,7 @@ main(Args) ->
%% @doc %% @doc
%% This takes an app name in the standard OTP <name>-<version> format %% This takes an app name in the standard OTP <name>-<version> format
%% and returns just the app name. Why? because rebar is doesn't %% and returns just the app name. Why? Because rebar doesn't
%% respect OTP conventions in some cases. %% respect OTP conventions in some cases.
-spec fixup_app_name(file:name()) -> string(). -spec fixup_app_name(file:name()) -> string().
fixup_app_name(Path) -> fixup_app_name(Path) ->

View file

@ -146,7 +146,7 @@ make_symlink(Path, TargetFile) ->
%% @doc %% @doc
%% This takes an app name in the standard OTP <name>-<version> format %% This takes an app name in the standard OTP <name>-<version> format
%% and returns just the app name. Why? because rebar doesn't %% and returns just the app name. Why? Because rebar doesn't
%% respect OTP conventions in some cases. %% respect OTP conventions in some cases.
-spec fixup_app_name(string()) -> string(). -spec fixup_app_name(string()) -> string().
fixup_app_name(FileName) -> fixup_app_name(FileName) ->