From 0fccd5bba40ce903ff25bb8f2ca09e86f3bef19d Mon Sep 17 00:00:00 2001 From: Gleb Peregud Date: Sun, 18 Jun 2017 23:05:18 +0200 Subject: [PATCH] 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. --- doc/languages-frameworks/beam.xml | 140 ++++++++++++++---- pkgs/development/beam-modules/mix-bootstrap | 20 ++- .../rebar3/rebar3-nix-bootstrap | 2 +- 3 files changed, 120 insertions(+), 42 deletions(-) diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index efb2e60cf3a..28dec9f77de 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -2,36 +2,85 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-beam"> - Beam Languages (Erlang & Elixir) + Beam Languages (Erlang, Elixir & LFE)
Introduction In this document and related Nix expressions we use the term - Beam to describe the environment. Beam is + 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 + 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.
-
+
+ Structure + + All Beam-related things are available via top-level + beam attribute, which includes: + + + + + interpreters: contains a set of compilers running + on Beam, including multiple Erlang/OTP versions + (beam.interpreters.erlangR19, etc), Elixir + (beam.interpreters.elixir) and LFE + (beam.interpreters.lfe). + + + + + packages: contains 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. + + + 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 + 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 + 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. + +
+
Build Tools
Rebar3 - By default Rebar3 wants to manage it's own dependencies. In the - normal non-Nix, this is perfectly acceptable. In the Nix world it - is not. To support this we have created two versions of 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. + 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.
@@ -43,16 +92,17 @@ buildMix and buildErlangMk derivations.
-
How to install Beam packages - Beam packages are not registered in the top level simply because - they are not relevant to the vast majority of Nix users. They are - installable using the beamPackages attribute - set. + Beam packages are not registered in 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 + beam.interpreters.erlang. You can list the avialable packages in the beamPackages with the following command: @@ -87,10 +137,11 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse
Rebar3 Packages - There is a Nix functional called - buildRebar3. We use this function to make a - derivation that understands how to build the rebar3 project. For - example, the epression we use to build the 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. @@ -111,10 +162,18 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse 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 + beamPackages, e.g. + beamPackages.ibrowse. + The only visible difference between this derivation and something like stdenv.mkDerivation is that we - have added erlangDeps to the derivation. If + have added beamDeps to the derivation. If you add your Beam dependencies here they will be correctly handled by the system. @@ -171,6 +230,27 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse 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"; + }; + } + + + Alternatively one can use buildHex as a shortcut for the above: + + + { buildHex, buildMix, plug, absinthe }: + buildHex { + name = "absinthe_plug"; + version = "1.0.0"; + sha256 = + "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; + builder = buildMix; beamDeps = [ plug absinthe]; meta = { @@ -264,7 +344,7 @@ let name = "hex2nix"; version = "0.1.0"; src = ./.; - erlangDeps = [ ibrowse jsx erlware_commons ]; + beamDeps = [ ibrowse jsx erlware_commons ]; }; drv = beamPackages.callPackage f {}; @@ -272,10 +352,10 @@ in drv
- Building in a shell + Building in a shell (for mix projects) - We can leveral the support of the Derivation, regardless of - which build Derivation is called by calling the commands themselv.s + We can leverage the support of the Derivation, regardless of + which build Derivation is called by calling the commands themselves. # ============================================================================= @@ -351,7 +431,7 @@ analyze: build plt hex2nix tool. Given the path to the Erlang modules (usually pkgs/development/erlang-modules). It will - happily dump a file called + 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. diff --git a/pkgs/development/beam-modules/mix-bootstrap b/pkgs/development/beam-modules/mix-bootstrap index c4a1b364daa..6c9a20c6de2 100755 --- a/pkgs/development/beam-modules/mix-bootstrap +++ b/pkgs/development/beam-modules/mix-bootstrap @@ -3,18 +3,16 @@ %%! -smp enable %%% --------------------------------------------------------------------------- %%% @doc -%%% The purpose of this command is to prepare a rebar3 project so that -%%% rebar3 understands that the dependencies are all already -%%% installed. If you want a hygienic build on nix then you must run -%%% this command before running rebar3. I suggest that you add a -%%% `Makefile` to your project and have the bootstrap command be a -%%% dependency of the build commands. See the nix documentation for +%%% The purpose of this command is to prepare a mix project so that mix +%%% understands that the dependencies are all already installed. If you want a +%%% hygienic build on nix then you must run this command before running mix. I +%%% suggest that you add a `Makefile` to your project and have the bootstrap +%%% command be a dependency of the build commands. See the nix documentation for %%% more information. %%% -%%% This command designed to have as few dependencies as possible so -%%% that it can be a dependency of root level packages like rebar3. To -%%% that end it does many things in a fairly simplistic way. That is -%%% by design. +%%% This command designed to have as few dependencies as possible so that it can +%%% be a dependency of root level packages like mix. To that end it does many +%%% things in a fairly simplistic way. That is by design. %%% %%% ### Assumptions %%% @@ -37,7 +35,7 @@ main(Args) -> %% @doc %% This takes an app name in the standard OTP - 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. -spec fixup_app_name(file:name()) -> string(). fixup_app_name(Path) -> diff --git a/pkgs/development/tools/build-managers/rebar3/rebar3-nix-bootstrap b/pkgs/development/tools/build-managers/rebar3/rebar3-nix-bootstrap index b839a4a3b09..aa7e6c5f912 100755 --- a/pkgs/development/tools/build-managers/rebar3/rebar3-nix-bootstrap +++ b/pkgs/development/tools/build-managers/rebar3/rebar3-nix-bootstrap @@ -146,7 +146,7 @@ make_symlink(Path, TargetFile) -> %% @doc %% This takes an app name in the standard OTP - 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. -spec fixup_app_name(string()) -> string(). fixup_app_name(FileName) ->