diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/configuration.xml | 215 | ||||
| -rw-r--r-- | doc/cross-compilation.xml | 72 | ||||
| -rw-r--r-- | doc/default.nix | 2 | ||||
| -rw-r--r-- | doc/functions.xml | 2 | ||||
| -rw-r--r-- | doc/languages-frameworks/beam.xml | 364 | ||||
| -rw-r--r-- | doc/languages-frameworks/go.xml | 8 | ||||
| -rw-r--r-- | doc/languages-frameworks/haskell.md | 802 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.md | 28 | ||||
| -rw-r--r-- | doc/languages-frameworks/qt.xml | 68 | ||||
| -rw-r--r-- | doc/languages-frameworks/vim.md | 41 | ||||
| -rw-r--r-- | doc/overlays.xml | 2 | ||||
| -rw-r--r-- | doc/package-notes.xml | 136 | ||||
| -rw-r--r-- | doc/quick-start.xml | 2 | ||||
| -rw-r--r-- | doc/reviewing-contributions.xml | 2 | ||||
| -rw-r--r-- | doc/stdenv.xml | 30 |
15 files changed, 1182 insertions, 592 deletions
diff --git a/doc/configuration.xml b/doc/configuration.xml index 56950e07ab5c4..ac03b42714c60 100644 --- a/doc/configuration.xml +++ b/doc/configuration.xml @@ -227,7 +227,7 @@ packages via <literal>packageOverrides</literal></title> <para>You can define a function called <varname>packageOverrides</varname> in your local -<filename>~/.config/nixpkgs/config.nix</filename> to overide nix packages. It +<filename>~/.config/nixpkgs/config.nix</filename> to override nix packages. It must be a function that takes pkgs as an argument and return modified set of packages. @@ -243,5 +243,218 @@ set of packages. </section> +<section xml:id="sec-declarative-package-management"> + <title>Declarative Package Management</title> + + <section xml:id="sec-building-environment"> + <title>Build an environment</title> + + <para> + Using <literal>packageOverrides</literal>, it is possible to manage + packages declaratively. This means that we can list all of our desired + packages within a declarative Nix expression. For example, to have + <literal>aspell</literal>, <literal>bc</literal>, + <literal>ffmpeg</literal>, <literal>coreutils</literal>, + <literal>gdb</literal>, <literal>nixUnstable</literal>, + <literal>emscripten</literal>, <literal>jq</literal>, + <literal>nox</literal>, and <literal>silver-searcher</literal>, we could + use the following in <filename>~/.config/nixpkgs/config.nix</filename>: + </para> + + <screen> +{ + packageOverrides = pkgs: with pkgs; { + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ aspell bc coreutils gdb ffmpeg nixUnstable emscripten jq nox silver-searcher ]; + }; + }; +} + </screen> + + <para> + To install it into our environment, you can just run <literal>nix-env -iA + nixpkgs.myPackages</literal>. If you want to load the packages to be built + from a working copy of <literal>nixpkgs</literal> you just run + <literal>nix-env -f. -iA myPackages</literal>. To explore what's been + installed, just look through <filename>~/.nix-profile/</filename>. You can + see that a lot of stuff has been installed. Some of this stuff is useful + some of it isn't. Let's tell Nixpkgs to only link the stuff that we want: + </para> + + <screen> +{ + packageOverrides = pkgs: with pkgs; { + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ aspell bc coreutils gdb ffmpeg nixUnstable emscripten jq nox silver-searcher ]; + pathsToLink = [ "/share" "/bin" ]; + }; + }; +} + </screen> + + <para> + <literal>pathsToLink</literal> tells Nixpkgs to only link the paths listed + which gets rid of the extra stuff in the profile. + <filename>/bin</filename> and <filename>/share</filename> are good + defaults for a user environment, getting rid of the clutter. If you are + running on Nix on MacOS, you may want to add another path as well, + <filename>/Applications</filename>, that makes GUI apps available. + </para> + + </section> + + <section xml:id="sec-getting-documentation"> + <title>Getting documentation</title> + + <para> + After building that new environment, look through + <filename>~/.nix-profile</filename> to make sure everything is there that + we wanted. Discerning readers will note that some files are missing. Look + inside <filename>~/.nix-profile/share/man/man1/</filename> to verify this. + There are no man pages for any of the Nix tools! This is because some + packages like Nix have multiple outputs for things like documentation (see + section 4). Let's make Nix install those as well. + </para> + + <screen> +{ + packageOverrides = pkgs: with pkgs; { + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ aspell bc coreutils ffmpeg nixUnstable emscripten jq nox silver-searcher ]; + pathsToLink = [ "/share/man" "/share/doc" /bin" ]; + extraOutputsToInstall = [ "man" "doc" ]; + }; + }; +} + </screen> + + <para> + This provides us with some useful documentation for using our packages. + However, if we actually want those manpages to be detected by man, we need + to set up our environment. This can also be managed within Nix + expressions. + </para> + + <screen> +{ + packageOverrides = pkgs: with pkgs; rec { + myProfile = writeText "my-profile" '' +export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin +export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man + ''; + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ + (runCommand "profile" {} '' +mkdir -p $out/etc/profile.d +cp ${myProfile} $out/etc/profile.d/my-profile.sh + '') + aspell + bc + coreutils + ffmpeg + man + nixUnstable + emscripten + jq + nox + silver-searcher + ]; + pathsToLink = [ "/share/man" "/share/doc" /bin" "/etc" ]; + extraOutputsToInstall = [ "man" "doc" ]; + }; + }; +} + </screen> + + <para> + For this to work fully, you must also have this script sourced when you + are logged in. Try adding something like this to your + <filename>~/.profile</filename> file: + </para> + + <screen> +#!/bin/sh +if [ -d $HOME/.nix-profile/etc/profile.d ]; then + for i in $HOME/.nix-profile/etc/profile.d/*.sh; do + if [ -r $i ]; then + . $i + fi + done +fi + </screen> + + <para> + Now just run <literal>source $HOME/.profile</literal> and you can starting + loading man pages from your environent. + </para> + + </section> + + <section xml:id="sec-gnu-info-setup"> + <title>GNU info setup</title> + + <para> + Configuring GNU info is a little bit trickier than man pages. To work + correctly, info needs a database to be generated. This can be done with + some small modifications to our environment scripts. + </para> + + <screen> +{ + packageOverrides = pkgs: with pkgs; rec { + myProfile = writeText "my-profile" '' +export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin +export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man +export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info + ''; + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ + (runCommand "profile" {} '' +mkdir -p $out/etc/profile.d +cp ${myProfile} $out/etc/profile.d/my-profile.sh + '') + aspell + bc + coreutils + ffmpeg + man + nixUnstable + emscripten + jq + nox + silver-searcher + texinfoInteractive + ]; + pathsToLink = [ "/share/man" "/share/doc" "/share/info" "/bin" "/etc" ]; + extraOutputsToInstall = [ "man" "doc" "info" ]; + postBuild = '' + if [ -x $out/bin/install-info -a -w $out/share/info ]; then + shopt -s nullglob + for i in $out/share/info/*.info $out/share/info/*.info.gz; do + $out/bin/install-info $i $out/share/info/dir + done + fi + ''; + }; + }; +} + </screen> + + <para> + <literal>postBuild</literal> tells Nixpkgs to run a command after building + the environment. In this case, <literal>install-info</literal> adds the + installed info pages to <literal>dir</literal> which is GNU info's default + root node. Note that <literal>texinfoInteractive</literal> is added to the + environment to give the <literal>install-info</literal> command. + </para> + + </section> + +</section> </chapter> diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index 728616a9f2635..77d020afa2df3 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -30,15 +30,16 @@ <section> <title>Platform parameters</title> <para> - The three GNU Autoconf platforms, <wordasword>build</wordasword>, <wordasword>host</wordasword>, and <wordasword>cross</wordasword>, are historically the result of much confusion. + The three GNU Autoconf platforms, <wordasword>build</wordasword>, <wordasword>host</wordasword>, and <wordasword>target</wordasword>, are historically the result of much confusion. <link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html" /> clears this up somewhat but there is more to be said. An important advice to get out the way is, unless you are packaging a compiler or other build tool, just worry about the build and host platforms. Dealing with just two platforms usually better matches people's preconceptions, and in this case is completely correct. </para> <para> In Nixpkgs, these three platforms are defined as attribute sets under the names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and <literal>targetPlatform</literal>. - All three are always defined at the top level, so one can get at them just like a dependency in a function that is imported with <literal>callPackage</literal>: - <programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...</programlisting> + All three are always defined as attributes in the standard environment, and at the top level. That means one can get at them just like a dependency in a function that is imported with <literal>callPackage</literal>: + <programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>, or just off <varname>stdenv</varname>: + <programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting>. </para> <variablelist> <varlistentry> @@ -62,8 +63,8 @@ The "target platform" is black sheep. The other two intrinsically apply to all compiled software—or any build process with a notion of "build-time" followed by "run-time". The target platform only applies to programming tools, and even then only is a good for for some of them. - Briefly, GCC, Binutils, GHC, and certain other tools are written in such a way such that a single build can only compiler code for a single platform. - Thus, when building them, one must think ahead about what platforms they wish to use the tool to produce machine code for, and build binaries for each. + Briefly, GCC, Binutils, GHC, and certain other tools are written in such a way such that a single build can only compile code for a single platform. + Thus, when building them, one must think ahead about which platforms they wish to use the tool to produce machine code for, and build binaries for each. </para> <para> There is no fundamental need to think about the target ahead of time like this. @@ -79,13 +80,9 @@ </listitem> </varlistentry> </variablelist> - <note><para> - If you dig around nixpkgs, you may notice there is also <varname>stdenv.cross</varname>. - This field defined as <varname>hostPlatform</varname> when the host and build platforms differ, but otherwise not defined at all. - This field is obsolete and will soon disappear—please do not use it. - </para></note> <para> - The exact scheme these fields is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up. + The exact schema these fields follow is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up. + You can see examples of ones used in practice in <literal>lib.systems.examples</literal>; note how they are not all very consistent. For now, here are few fields can count on them containing: </para> <variablelist> @@ -118,8 +115,27 @@ This is a nix representation of a parsed LLVM target triple with white-listed components. This can be specified directly, or actually parsed from the <varname>config</varname>. [Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.] - See <literal>lib.systems.parse</literal> for the exact representation, along with some <literal>is*</literal>predicates. - These predicates are superior to the ones in <varname>stdenv</varname> as they aren't tied to the build platform (host, as previously discussed, would be a saner default). + See <literal>lib.systems.parse</literal> for the exact representation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>libc</varname></term> + <listitem> + <para> + This is a string identifying the standard C library used. + Valid identifiers include "glibc" for GNU libc, "libSystem" for Darwin's Libsystem, and "uclibc" for µClibc. + It should probably be refactored to use the module system, like <varname>parse</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>is*</varname></term> + <listitem> + <para> + These predicates are defined in <literal>lib.systems.inspect</literal>, and slapped on every platform. + They are superior to the ones in <varname>stdenv</varname> as they force the user to be explicit about which platform they are inspecting. + Please use these instead of those. </para> </listitem> </varlistentry> @@ -128,7 +144,7 @@ <listitem> <para> This is, quite frankly, a dumping ground of ad-hoc settings (it's an attribute set). - See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform one is working. + See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform that is working. Please help us triage these flags and give them better homes! </para> </listitem> @@ -158,10 +174,10 @@ The depending package's target platform is unconstrained by the sliding window principle, which makes sense in that one can in principle build cross compilers targeting arbitrary platforms. </para></note> <para> - How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set. + How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set. For example, <varname>buildPackages.gcc</varname> should be used at build time, while <varname>gcc</varname> should be used at run time. Now, for most of Nixpkgs's history, there was no <varname>buildPackages</varname>, and most packages have not been refactored to use it explicitly. - Instead, one can use the four attributes used for specifying dependencies as documented in <link linkend="ssec-stdenv-attributes" />. + Instead, one can use the four attributes used for specifying dependencies as documented in <xref linkend="ssec-stdenv-attributes"/>. We "splice" together the run-time and build-time package sets with <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for each of four attributes pulls the right derivation out. This splicing can be skipped when not cross compiling as the package sets are the same, but is a bit slow for cross compiling. Because of this, a best-of-both-worlds solution is in the works with no splicing or explicit access of <varname>buildPackages</varname> needed. @@ -184,12 +200,28 @@ More information needs to moved from the old wiki, especially <link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section. </para></note> <para> - Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, and, optionally, <varname>crossSystem</varname> to nixpkgs: - <literal>import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }</literal>. - <varname>system</varname> and <varname>platform</varname> together determine the system on which packages are built, and <varname>crossSystem</varname> specifies the platform on which packages are ultimately intended to run, if it is different. - This still works, but with more recent changes, one can alternatively pass <varname>localSystem</varname>, containing <varname>system</varname> and <varname>platform</varname>, for symmetry. + Nixpkgs can be instantiated with <varname>localSystem</varname> alone, in which case there is no cross compiling and everything is built by and for that system, + or also with <varname>crossSystem</varname>, in which case packages run on the latter, but all building happens on the former. + Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section. + As mentioned above, <literal>lib.systems.examples</literal> has some platforms which are used as arguments for these parameters in practice. + You can use them programmatically, or on the command line like <command>nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz'</command>. </para> <para> + While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields. + As discussed in the previous section, only one of <varname>system</varname>, <varname>config</varname>, and <varname>parsed</varname> is needed to infer the other two. + Additionally, <varname>libc</varname> will be inferred from <varname>parse</varname>. + Finally, <literal>localSystem.system</literal> is also <emphasis>impurely</emphasis> inferred based on the platform evaluation occurs. + This means it is often not necessary to pass <varname>localSystem</varname> at all, as in the command-line example in the previous paragraph. + </para> + <note> + <para> + Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, along with the optional <varname>crossSystem</varname> to nixpkgs: + <literal>import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }</literal>. + Passing those two instead of <varname>localSystem</varname> is still supported for compatibility, but is discouraged. + Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience. + </para> + </note> + <para> One would think that <varname>localSystem</varname> and <varname>crossSystem</varname> overlap horribly with the three <varname>*Platforms</varname> (<varname>buildPlatform</varname>, <varname>hostPlatform,</varname> and <varname>targetPlatform</varname>; see <varname>stage.nix</varname> or the manual). Actually, those identifiers are purposefully not used here to draw a subtle but important distinction: While the granularity of having 3 platforms is necessary to properly *build* packages, it is overkill for specifying the user's *intent* when making a build plan or package set. diff --git a/doc/default.nix b/doc/default.nix index 540a209c2ac9d..cfd51fba257e9 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|<ulink url=|<link xlink:href=|' \ -e 's|</ulink>|</link>|' \ diff --git a/doc/functions.xml b/doc/functions.xml index 4e7159638cae3..4a9015602afc6 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -70,7 +70,7 @@ <para> In the above example, the <varname>separateDebugInfo</varname> attribute is - overriden to be true, thus building debug info for + overridden to be true, thus building debug info for <varname>helloWithDebug</varname>, while all other attributes will be retained from the original <varname>hello</varname> package. </para> diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index efb2e60cf3aac..1a18ed27237c2 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -2,60 +2,120 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-beam"> - <title>Beam Languages (Erlang & Elixir)</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 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, + <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="build-tools"> + <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> + <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 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, - <literal>rebar3</literal> and <literal>rebar3-open</literal>. The - <literal>rebar3</literal> 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. <literal>rebar3-open</literal> is the normal, un-modified - rebar3. It should work exactly as would any other version of - rebar3. Any Erlang package should rely on - <literal>rebar3</literal> and thats really what you should be - using too. + 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> </section> <section xml:id="build-tools-other"> <title>Mix & Erlang.mk</title> <para> - 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 - <literal>buildMix</literal> and <literal>buildErlangMk</literal> 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 + <literal>buildMix</literal> and <literal>buildErlangMk</literal> + derivations, respectively. </para> </section> - </section> <section xml:id="how-to-install-beam-packages"> - <title>How to install Beam packages</title> + <title>How to Install BEAM Packages</title> <para> - 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 <literal>beamPackages</literal> attribute - set. + 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>. - You can list the avialable packages in the - <literal>beamPackages</literal> with the following command: + To list the available packages in + <literal>beamPackages</literal>, use the following command: </para> <programlisting> @@ -69,115 +129,152 @@ 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> $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse </programlisting> <para> - 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 <link xlink:href="https://hex.pm">Hex</link> or its + OTP Application/Release name. </para> </section> <section xml:id="packaging-beam-applications"> - <title>Packaging Beam Applications</title> + <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> - There is a Nix functional called - <literal>buildRebar3</literal>. 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 <link - xlink:href="https://github.com/erlang-nix/hex2nix">hex2nix</link> - project follows. + 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 }: + { 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 ]; } </programlisting> <para> - The only visible difference between this derivation and - something like <literal>stdenv.mkDerivation</literal> is that we - have added <literal>erlangDeps</literal> to the derivation. If - you add your Beam dependencies here they will be correctly - handled by the system. + 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 your package needs to compile native code via Rebar's port - compilation mechenism. You should add <literal>compilePort = - true;</literal> to the derivation. + 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 almost identically to Rebar. The only real - difference is that <literal>buildErlangMk</literal> is called - instead of <literal>buildRebar3</literal> + Erlang.mk functions similarly to Rebar3, except we use + <literal>buildErlangMk</literal> instead of + <literal>buildRebar3</literal>. </para> <programlisting> - { buildErlangMk, fetchHex, cowlib, ranch }: - buildErlangMk { - name = "cowboy"; + { buildErlangMk, fetchHex, cowlib, ranch }: + + buildErlangMk { + name = "cowboy"; + version = "1.0.4"; + + src = fetchHex { + pkg = "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"; - }; + 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; + }; } </programlisting> </section> <section xml:id="mix-packages"> <title>Mix Packages</title> <para> - Mix functions almost identically to Rebar. The only real - difference is that <literal>buildMix</literal> is called - instead of <literal>buildRebar3</literal> + Mix functions similarly to Rebar3, except we use + <literal>buildMix</literal> instead of <literal>buildRebar3</literal>. </para> <programlisting> { 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 ]; + + meta = { + description = '' + A plug for Absinthe, an experimental GraphQL toolkit + ''; + license = stdenv.lib.licenses.bsd3; + homepage = https://github.com/CargoSense/absinthe_plug; }; - beamDeps = [ plug absinthe]; + } + </programlisting> + <para> + Alternatively, we can use <literal>buildHex</literal> as a shortcut: + </para> + <programlisting> + { buildHex, buildMix, plug, absinthe }: + + buildHex { + name = "absinthe_plug"; + version = "1.0.0"; + + sha256 = "08459823fe1fd4f0325a8bf0c937a4520583a5a26d73b193040ab30a1dfc0b33"; + + builder = buildMix; + + 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; }; } </programlisting> @@ -185,18 +282,18 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse </section> </section> <section xml:id="how-to-develop"> - <title>How to develop</title> + <title>How to Develop</title> <section xml:id="accessing-an-environment"> <title>Accessing an Environment</title> <para> - 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 <literal>env</literal> - 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 + <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> - ~/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) @@ -237,20 +334,19 @@ $ nix-env -f "<nixpkgs>" -iA beamPackages.ibrowse 2> </programlisting> <para> - Notice the <literal>-A beamPackages.ibrowse.env</literal>.That - is the key to this functionality. + 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. Many times we need to create a - <literal>shell.nix</literal> 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 - <literal>src</literal> points to project root and we call the - package directly. + 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"> {} }: @@ -264,18 +360,19 @@ let name = "hex2nix"; version = "0.1.0"; src = ./.; - erlangDeps = [ ibrowse jsx erlware_commons ]; + beamDeps = [ ibrowse jsx erlware_commons ]; }; drv = beamPackages.callPackage f {}; in - drv + + drv </programlisting> <section xml:id="building-in-a-shell"> - <title>Building in a shell</title> + <title>Building in a Shell (for Mix Projects)</title> <para> - 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, irrespective of the build + derivation, by calling the commands themselves. </para> <programlisting> # ============================================================================= @@ -335,42 +432,43 @@ analyze: build plt </programlisting> <para> - If you add the <literal>shell.nix</literal> as described and - user rebar as follows things should simply work. Aside from the + 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 talks work just fine for all of - the build Derivations. + <literal>analyze</literal>, the Make targets work just fine for all of the + build derivations. </para> </section> </section> </section> <section xml:id="generating-packages-from-hex-with-hex2nix"> - <title>Generating Packages from Hex with Hex2Nix</title> + <title>Generating Packages from Hex with <literal>hex2nix</literal></title> <para> - Updating the Hex packages requires the use of the - <literal>hex2nix</literal> tool. Given the path to the Erlang - modules (usually - <literal>pkgs/development/erlang-modules</literal>). It will - happily dump a file called - <literal>hex-packages.nix</literal>. 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 <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, 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 <literal>nixpkgs</literal> repository). that follows. + 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 build every package in - <literal>beamPackages</literal>. Then you can go through and - manually remove the ones that fail. Hopefully, someone will - improve <literal>hex2nix</literal> in the future to automate - that. + 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> diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml index 026acb4e8fb94..54ea60c902129 100644 --- a/doc/languages-frameworks/go.xml +++ b/doc/languages-frameworks/go.xml @@ -13,7 +13,7 @@ standard Go programs. deis = buildGoPackage rec { name = "deis-${version}"; version = "1.13.0"; - + goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' /> subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' /> @@ -130,6 +130,9 @@ the following arguments are of special significance to the function: </para> +<para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. + It can produce complete derivation and <varname>goDeps</varname> file for Go programs.</para> + <para> <varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows: @@ -160,7 +163,4 @@ done </screen> </para> -<para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. - It can produce complete derivation and <varname>goDeps</varname> file for Go programs.</para> </section> - diff --git a/doc/languages-frameworks/haskell.md b/doc/languages-frameworks/haskell.md index 1cab3d1e4eed3..68894994392b8 100644 --- a/doc/languages-frameworks/haskell.md +++ b/doc/languages-frameworks/haskell.md @@ -11,32 +11,35 @@ date: 2015-06-01 Nixpkgs distributes build instructions for all Haskell packages registered on [Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package lookups don't seem to discover any of them, except for the default version of ghc, cabal-install, and stack: - - $ nix-env -i alex - error: selector ‘alex’ matches no derivations - $ nix-env -qa ghc - ghc-7.10.2 +``` +$ nix-env -i alex +error: selector ‘alex’ matches no derivations +$ nix-env -qa ghc +ghc-7.10.2 +``` The Haskell package set is not registered in the top-level namespace because it is *huge*. If all Haskell packages were visible to these commands, then name-based search/install operations would be much slower than they are now. We avoided that by keeping all Haskell-related packages in a separate attribute set called `haskellPackages`, which the following command will list: - - $ nix-env -f "<nixpkgs>" -qaP -A haskellPackages - haskellPackages.a50 a50-0.5 - haskellPackages.abacate haskell-abacate-0.0.0.0 - haskellPackages.abcBridge haskell-abcBridge-0.12 - haskellPackages.afv afv-0.1.1 - haskellPackages.alex alex-3.1.4 - haskellPackages.Allure Allure-0.4.101.1 - haskellPackages.alms alms-0.6.7 - [... some 8000 entries omitted ...] +``` +$ nix-env -f "<nixpkgs>" -qaP -A haskellPackages +haskellPackages.a50 a50-0.5 +haskellPackages.abacate haskell-abacate-0.0.0.0 +haskellPackages.abcBridge haskell-abcBridge-0.12 +haskellPackages.afv afv-0.1.1 +haskellPackages.alex alex-3.1.4 +haskellPackages.Allure Allure-0.4.101.1 +haskellPackages.alms alms-0.6.7 +[... some 8000 entries omitted ...] +``` To install any of those packages into your profile, refer to them by their attribute path (first column): - - $ nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ... +```shell +nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ... +``` The attribute path of any Haskell packages corresponds to the name of that particular package on Hackage: the package `cabal-install` has the attribute @@ -58,55 +61,60 @@ Attribute paths are deterministic inside of Nixpkgs, but the path necessary to reach Nixpkgs varies from system to system. We dodged that problem by giving `nix-env` an explicit `-f "<nixpkgs>"` parameter, but if you call `nix-env` without that flag, then chances are the invocation fails: - - $ nix-env -iA haskellPackages.cabal-install - error: attribute ‘haskellPackages’ in selection path - ‘haskellPackages.cabal-install’ not found +``` +$ nix-env -iA haskellPackages.cabal-install +error: attribute ‘haskellPackages’ in selection path + ‘haskellPackages.cabal-install’ not found +``` On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by default. To figure out the proper attribute path, it's easiest to query for the path of a well-known Nixpkgs package, i.e.: - - $ nix-env -qaP coreutils - nixos.coreutils coreutils-8.23 +``` +$ nix-env -qaP coreutils +nixos.coreutils coreutils-8.23 +``` If your system responds like that (most NixOS installations will), then the attribute path to `haskellPackages` is `nixos.haskellPackages`. Thus, if you want to use `nix-env` without giving an explicit `-f` flag, then that's the way to do it: - - $ nix-env -qaP -A nixos.haskellPackages - $ nix-env -iA nixos.haskellPackages.cabal-install +```shell +nix-env -qaP -A nixos.haskellPackages +nix-env -iA nixos.haskellPackages.cabal-install +``` Our current default compiler is GHC 7.10.x and the `haskellPackages` set contains packages built with that particular version. Nixpkgs contains the latest major release of every GHC since 6.10.4, however, and there is a whole family of package sets available that defines Hackage packages built with each of those compilers, too: - - $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123 - $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763 +```shell +nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123 +nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763 +``` The name `haskellPackages` is really just a synonym for `haskell.packages.ghc7102`, because we prefer that package set internally and recommend it to our users as their default choice, but ultimately you are free to compile your Haskell packages with any GHC version you please. The following command displays the complete list of available compilers: - - $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler - haskell.compiler.ghc6104 ghc-6.10.4 - haskell.compiler.ghc6123 ghc-6.12.3 - haskell.compiler.ghc704 ghc-7.0.4 - haskell.compiler.ghc722 ghc-7.2.2 - haskell.compiler.ghc742 ghc-7.4.2 - haskell.compiler.ghc763 ghc-7.6.3 - haskell.compiler.ghc784 ghc-7.8.4 - haskell.compiler.ghc7102 ghc-7.10.2 - haskell.compiler.ghcHEAD ghc-7.11.20150402 - haskell.compiler.ghcNokinds ghc-nokinds-7.11.20150704 - haskell.compiler.ghcjs ghcjs-0.1.0 - haskell.compiler.jhc jhc-0.8.2 - haskell.compiler.uhc uhc-1.1.9.0 +``` +$ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler +haskell.compiler.ghc6104 ghc-6.10.4 +haskell.compiler.ghc6123 ghc-6.12.3 +haskell.compiler.ghc704 ghc-7.0.4 +haskell.compiler.ghc722 ghc-7.2.2 +haskell.compiler.ghc742 ghc-7.4.2 +haskell.compiler.ghc763 ghc-7.6.3 +haskell.compiler.ghc784 ghc-7.8.4 +haskell.compiler.ghc7102 ghc-7.10.2 +haskell.compiler.ghcHEAD ghc-7.11.20150402 +haskell.compiler.ghcNokinds ghc-nokinds-7.11.20150704 +haskell.compiler.ghcjs ghcjs-0.1.0 +haskell.compiler.jhc jhc-0.8.2 +haskell.compiler.uhc uhc-1.1.9.0 +``` We have no package sets for `jhc` or `uhc` yet, unfortunately, but for every version of GHC listed above, there exists a package set based on that compiler. @@ -121,8 +129,9 @@ A simple development environment consists of a Haskell compiler and one or both of the tools `cabal-install` and `stack`. We saw in section [How to install Haskell packages] how you can install those programs into your user profile: - - $ nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install +```shell +nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install +``` Instead of the default package set `haskellPackages`, you can also use the more precise name `haskell.compiler.ghc7102`, which has the advantage that it refers @@ -131,24 +140,25 @@ given time. Once you've made those tools available in `$PATH`, it's possible to build Hackage packages the same way people without access to Nix do it all the time: - - $ cabal get lens-4.11 && cd lens-4.11 - $ cabal install -j --dependencies-only - $ cabal configure - $ cabal build +```shell +cabal get lens-4.11 && cd lens-4.11 +cabal install -j --dependencies-only +cabal configure +cabal build +``` If you enjoy working with Cabal sandboxes, then that's entirely possible too: just execute the command - - $ cabal sandbox init - +```shell +cabal sandbox init +``` before installing the required dependencies. The `nix-shell` utility makes it easy to switch to a different compiler version; just enter the Nix shell environment with the command - - $ nix-shell -p haskell.compiler.ghc784 - +```shell +nix-shell -p haskell.compiler.ghc784 +``` to bring GHC 7.8.4 into `$PATH`. Alternatively, you can use Stack instead of `nix-shell` directly to select compiler versions and other build tools per-project. It uses `nix-shell` under the hood when Nix support is turned on. @@ -159,8 +169,9 @@ shell switches your build to use that compiler instead. If you're working on a project that doesn't depend on any additional system libraries outside of GHC, then it's even sufficient to just run the `cabal configure` command inside of the shell: - - $ nix-shell -p haskell.compiler.ghc784 --command "cabal configure" +```shell +nix-shell -p haskell.compiler.ghc784 --command "cabal configure" +``` Afterwards, all other commands like `cabal build` work just fine in any shell environment, because the configure phase recorded the absolute paths to all @@ -187,29 +198,30 @@ packages, which determines the libraries known to that particular version of GHC. For example, the Nix expression `ghcWithPackages (pkgs: [pkgs.mtl])` generates a copy of GHC that has the `mtl` library registered in addition to its normal core packages: +``` +$ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])" - $ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])" - - [nix-shell:~]$ ghc-pkg list mtl - /nix/store/zy79...-ghc-7.10.2/lib/ghc-7.10.2/package.conf.d: - mtl-2.2.1 +[nix-shell:~]$ ghc-pkg list mtl +/nix/store/zy79...-ghc-7.10.2/lib/ghc-7.10.2/package.conf.d: + mtl-2.2.1 +``` This function allows users to define their own development environment by means of an override. After adding the following snippet to `~/.config/nixpkgs/config.nix`, - - { - packageOverrides = super: let self = super.pkgs; in - { - myHaskellEnv = self.haskell.packages.ghc7102.ghcWithPackages - (haskellPackages: with haskellPackages; [ - # libraries - arrows async cgi criterion - # tools - cabal-install haskintex - ]); - }; - } - +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + myHaskellEnv = self.haskell.packages.ghc7102.ghcWithPackages + (haskellPackages: with haskellPackages; [ + # libraries + arrows async cgi criterion + # tools + cabal-install haskintex + ]); + }; +} +``` it's possible to install that compiler with `nix-env -f "<nixpkgs>" -iA myHaskellEnv`. If you'd like to switch that development environment to a different version of GHC, just replace the `ghc7102` bit in the previous @@ -221,14 +233,15 @@ file conflicts.) The generated `ghc` program is a wrapper script that re-directs the real GHC executable to use a new `lib` directory --- one that we specifically constructed to contain all those packages the user requested: - - $ cat $(type -p ghc) - #! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e - export NIX_GHC=/nix/store/19sm...-ghc-7.10.2/bin/ghc - export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.2/bin/ghc-pkg - export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.2/share/doc/ghc/html - export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.2/lib/ghc-7.10.2 - exec /nix/store/j50p...-ghc-7.10.2/bin/ghc "-B$NIX_GHC_LIBDIR" "$@" +``` +$ cat $(type -p ghc) +#! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e +export NIX_GHC=/nix/store/19sm...-ghc-7.10.2/bin/ghc +export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.2/bin/ghc-pkg +export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.2/share/doc/ghc/html +export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.2/lib/ghc-7.10.2 +exec /nix/store/j50p...-ghc-7.10.2/bin/ghc "-B$NIX_GHC_LIBDIR" "$@" +``` The variables `$NIX_GHC`, `$NIX_GHCPKG`, etc. point to the *new* store path `ghcWithPackages` constructed specifically for this environment. The last line @@ -248,23 +261,25 @@ than trying to guess them at compile-time. To make sure that mechanism works properly all the time, we recommend that you set those variables to meaningful values in your shell environment, too, i.e. by adding the following code to your `~/.bashrc`: - - if type >/dev/null 2>&1 -p ghc; then - eval "$(egrep ^export "$(type -p ghc)")" - fi +```bash +if type >/dev/null 2>&1 -p ghc; then + eval "$(egrep ^export "$(type -p ghc)")" +fi +``` If you are certain that you'll use only one GHC environment which is located in your user profile, then you can use the following code, too, which has the advantage that it doesn't contain any paths from the Nix store, i.e. those settings always remain valid even if a `nix-env -u` operation updates the GHC environment in your profile: - - if [ -e ~/.nix-profile/bin/ghc ]; then - export NIX_GHC="$HOME/.nix-profile/bin/ghc" - export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg" - export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html" - export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)" - fi +```bash +if [ -e ~/.nix-profile/bin/ghc ]; then + export NIX_GHC="$HOME/.nix-profile/bin/ghc" + export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg" + export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html" + export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)" +fi +``` ### How to install a compiler with libraries, hoogle and documentation indexes @@ -280,20 +295,20 @@ uses all those things. A precise name for this thing would be long and scary. For example, installing the following environment - - { - packageOverrides = super: let self = super.pkgs; in - { - myHaskellEnv = self.haskellPackages.ghcWithHoogle - (haskellPackages: with haskellPackages; [ - # libraries - arrows async cgi criterion - # tools - cabal-install haskintex - ]); - }; - } - +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + myHaskellEnv = self.haskellPackages.ghcWithHoogle + (haskellPackages: with haskellPackages; [ + # libraries + arrows async cgi criterion + # tools + cabal-install haskintex + ]); + }; +} +``` allows one to browse module documentation index [not too dissimilar to this](https://downloads.haskell.org/~ghc/latest/docs/html/libraries/index.html) for all the specified packages and their dependencies by directing a browser of @@ -303,23 +318,24 @@ choice to `~/.nix-profiles/share/doc/hoogle/index.html` (or After you've marveled enough at that try adding the following to your `~/.ghc/ghci.conf` - - :def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\"" - :def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\"" - +``` +:def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\"" +:def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\"" +``` and test it by typing into `ghci`: - - :hoogle a -> a - :doc a -> a +``` +:hoogle a -> a +:doc a -> a +``` Be sure to note the links to `haddock` files in the output. With any modern and properly configured terminal emulator you can just click those links to navigate there. Finally, you can run - - hoogle server -p 8080 - +```shell +hoogle server -p 8080 +``` and navigate to http://localhost:8080/ for your own local [Hoogle](https://www.haskell.org/hoogle/). Note, however, that Firefox and possibly other browsers disallow navigation from `http:` to `file:` URIs for @@ -334,18 +350,20 @@ It has first-class support for Nix. Stack can optionally use Nix to automatically select the right version of GHC and other build tools to build, test and execute apps in an existing project downloaded from somewhere on the Internet. Pass the `--nix` flag to any `stack` command to do so, e.g. - - $ git clone --recursive http://github.com/yesodweb/wai - $ cd wai - $ stack --nix build +```shell +git clone --recursive http://github.com/yesodweb/wai +cd wai +stack --nix build +``` If you want `stack` to use Nix by default, you can add a `nix` section to the `stack.yaml` file, as explained in the [Stack documentation][stack-nix-doc]. For example: - - nix: - enable: true - packages: [pkgconfig zeromq zlib] +```yaml +nix: + enable: true + packages: [pkgconfig zeromq zlib] +``` The example configuration snippet above tells Stack to create an ad hoc environment for `nix-shell` as in the below section, in which the `pkgconfig`, @@ -356,10 +374,11 @@ Some projects have more sophisticated needs. For examples, some ad hoc environments might need to expose Nixpkgs packages compiled in a certain way, or with extra environment variables. In these cases, you'll need a `shell` field instead of `packages`: - - nix: - enable: true - shell-file: shell.nix +```yaml +nix: + enable: true + shell-file: shell.nix +``` For more on how to write a `shell.nix` file see the below section. You'll need to express a derivation. Note that Nixpkgs ships with a convenience wrapper @@ -368,32 +387,34 @@ create this derivation in exactly the way Stack expects. All of the same inputs as `mkDerivation` can be provided. For example, to build a Stack project that including packages that link against a version of the R library compiled with special options turned on: +```nix +with (import <nixpkgs> { }); - with (import <nixpkgs> { }); - - let R = pkgs.R.override { enableStrictBarrier = true; }; - in - haskell.lib.buildStackProject { - name = "HaskellR"; - buildInputs = [ R zeromq zlib ]; - } +let R = pkgs.R.override { enableStrictBarrier = true; }; +in +haskell.lib.buildStackProject { + name = "HaskellR"; + buildInputs = [ R zeromq zlib ]; +} +``` You can select a particular GHC version to compile with by setting the `ghc` attribute as an argument to `buildStackProject`. Better yet, let Stack choose what GHC version it wants based on the snapshot specified in `stack.yaml` (only works with Stack >= 1.1.3): +```nix +{nixpkgs ? import <nixpkgs> { }, ghc ? nixpkgs.ghc}: - {nixpkgs ? import <nixpkgs> { }, ghc ? nixpkgs.ghc}: +with nixpkgs; - with nixpkgs; - - let R = pkgs.R.override { enableStrictBarrier = true; }; - in - haskell.lib.buildStackProject { - name = "HaskellR"; - buildInputs = [ R zeromq zlib ]; - inherit ghc; - } +let R = pkgs.R.override { enableStrictBarrier = true; }; +in +haskell.lib.buildStackProject { + name = "HaskellR"; + buildInputs = [ R zeromq zlib ]; + inherit ghc; +} +``` [stack-nix-doc]: http://docs.haskellstack.org/en/stable/nix_integration.html @@ -401,24 +422,26 @@ in `stack.yaml` (only works with Stack >= 1.1.3): The easiest way to create an ad hoc development environment is to run `nix-shell` with the appropriate GHC environment given on the command-line: - - nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])" +```shell +nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])" +``` For more sophisticated use-cases, however, it's more convenient to save the desired configuration in a file called `shell.nix` that looks like this: - - { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: - let - inherit (nixpkgs) pkgs; - ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [ - monad-par mtl - ]); - in - pkgs.stdenv.mkDerivation { - name = "my-haskell-env-0"; - buildInputs = [ ghc ]; - shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)"; - } +```nix +{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: +let + inherit (nixpkgs) pkgs; + ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [ + monad-par mtl + ]); +in +pkgs.stdenv.mkDerivation { + name = "my-haskell-env-0"; + buildInputs = [ ghc ]; + shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)"; +} +``` Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell environment that has the appropriate compiler in `$PATH`. If you use `--pure`, @@ -434,13 +457,14 @@ already! Every Haskell package has an `env` attribute that provides a shell environment suitable for compiling that particular package. If you'd like to hack the `lens` library, for example, then you just have to check out the source code and enter the appropriate environment: +``` +$ cabal get lens-4.11 && cd lens-4.11 +Downloading lens-4.11... +Unpacking to lens-4.11/ - $ cabal get lens-4.11 && cd lens-4.11 - Downloading lens-4.11... - Unpacking to lens-4.11/ - - $ nix-shell "<nixpkgs>" -A haskellPackages.lens.env - [nix-shell:/tmp/lens-4.11]$ +$ nix-shell "<nixpkgs>" -A haskellPackages.lens.env +[nix-shell:/tmp/lens-4.11]$ +``` At point, you can run `cabal configure`, `cabal build`, and all the other development commands. Note that you need `cabal-install` installed in your @@ -459,18 +483,20 @@ convert those automatically into build instructions for Nix using the For example, let's assume that you're working on a private project called `foo`. To generate a Nix build expression for it, change into the project's top-level directory and run the command: - - $ cabal2nix . >foo.nix - +```shell +cabal2nix . > foo.nix +``` Then write the following snippet into a file called `default.nix`: - - { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: - nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { } +```nix +{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: +nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { } +``` Finally, store the following code in a file called `shell.nix`: - - { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: - (import ./default.nix { inherit nixpkgs compiler; }).env +```nix +{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: +(import ./default.nix { inherit nixpkgs compiler; }).env +``` At this point, you can run `nix-build` to have Nix compile your project and install it into a Nix store path. The local directory will contain a symlink @@ -486,9 +512,9 @@ libraries your package might need. If your package does not depend on any system-level libraries, then it's sufficient to run - - $ nix-shell --command "cabal configure" - +```shell +nix-shell --command "cabal configure" +``` once to set up your build. `cabal-install` determines the absolute paths to all resources required for the build and writes them into a config file in the `dist/` directory. Once that's done, you can run `cabal build` and any other @@ -502,14 +528,15 @@ If you want to do some quick-and-dirty hacking and don't want to bother setting up a `default.nix` and `shell.nix` file manually, then you can use the `--shell` flag offered by `cabal2nix` to have it generate a stand-alone `nix-shell` environment for you. With that feature, running - - $ cabal2nix --shell . >shell.nix - $ nix-shell --command "cabal configure" - +```shell +cabal2nix --shell . > shell.nix +nix-shell --command "cabal configure" +``` is usually enough to set up a build environment for any given Haskell package. You can even use that generated file to run `nix-build`, too: - - $ nix-build shell.nix +```shell +nix-build shell.nix +``` ### How to build projects that depend on each other @@ -518,33 +545,34 @@ you'll have to register those packages in the Nixpkgs set to make them visible for the dependency resolution performed by `callPackage`. First of all, change into each of your projects top-level directories and generate a `default.nix` file with `cabal2nix`: - - $ cd ~/src/foo && cabal2nix . >default.nix - $ cd ~/src/bar && cabal2nix . >default.nix - +```shell +cd ~/src/foo && cabal2nix . > default.nix +cd ~/src/bar && cabal2nix . > default.nix +``` Then edit your `~/.config/nixpkgs/config.nix` file to register those builds in the default Haskell package set: - - { - packageOverrides = super: let self = super.pkgs; in - { - haskellPackages = super.haskellPackages.override { - overrides = self: super: { - foo = self.callPackage ../src/foo {}; - bar = self.callPackage ../src/bar {}; - }; - }; - }; - } - +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + haskellPackages = super.haskellPackages.override { + overrides = self: super: { + foo = self.callPackage ../src/foo {}; + bar = self.callPackage ../src/bar {}; + }; + }; + }; +} +``` Once that's accomplished, `nix-env -f "<nixpkgs>" -qA haskellPackages` will show your packages like any other package from Hackage, and you can build them - - $ nix-build "<nixpkgs>" -A haskellPackages.foo - +```shell +nix-build "<nixpkgs>" -A haskellPackages.foo +``` or enter an interactive shell environment suitable for building them: - - $ nix-shell "<nixpkgs>" -A haskellPackages.bar.env +```shell +nix-shell "<nixpkgs>" -A haskellPackages.bar.env +``` ## Miscellaneous Topics @@ -555,20 +583,20 @@ to manipulate the package as much as you please. One useful application of this feature is to replace the default `mkDerivation` function with one that enables library profiling for all packages. To accomplish that, add configure the following snippet in your `~/.config/nixpkgs/config.nix` file: - - { - packageOverrides = super: let self = super.pkgs; in - { - profiledHaskellPackages = self.haskellPackages.override { - overrides = self: super: { - mkDerivation = args: super.mkDerivation (args // { - enableLibraryProfiling = true; - }); - }; - }; +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + profiledHaskellPackages = self.haskellPackages.override { + overrides = self: super: { + mkDerivation = args: super.mkDerivation (args // { + enableLibraryProfiling = true; + }); }; - } - + }; + }; +} +``` Then, replace instances of `haskellPackages` in the `cabal2nix`-generated `default.nix` or `shell.nix` files with `profiledHaskellPackages`. @@ -580,35 +608,39 @@ at the time of this writing. This is fine for users of GHC 7.10.x, but GHC 7.8.4 cannot compile that binary. Now, one way to solve that problem is to register an older version of `ghc-events` in the 7.8.x-specific package set. The first step is to generate Nix build instructions with `cabal2nix`: - - $ cabal2nix cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix - +```shell +cabal2nix cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix +``` Then add the override in `~/.config/nixpkgs/config.nix`: - - { - packageOverrides = super: let self = super.pkgs; in - { - haskell = super.haskell // { - packages = super.haskell.packages // { - ghc784 = super.haskell.packages.ghc784.override { - overrides = self: super: { - ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {}; - }; - }; +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + haskell = super.haskell // { + packages = super.haskell.packages // { + ghc784 = super.haskell.packages.ghc784.override { + overrides = self: super: { + ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {}; }; }; }; - } + }; + }; +} +``` This code is a little crazy, no doubt, but it's necessary because the intuitive version +```nix +{ # ... - haskell.packages.ghc784 = super.haskell.packages.ghc784.override { - overrides = self: super: { - ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {}; - }; + haskell.packages.ghc784 = super.haskell.packages.ghc784.override { + overrides = self: super: { + ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {}; }; - + }; +} +``` doesn't do what we want it to: that code replaces the `haskell` package set in Nixpkgs with one that contains only one entry,`packages`, which contains only one entry `ghc784`. This override loses the `haskell.compiler` set, and it @@ -618,16 +650,16 @@ iterating over each step in hierarchy. Once it's accomplished, however, we can install a variant of `ghc-events` that's compiled with GHC 7.8.4: - - nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events - +```shell +nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events +``` Unfortunately, it turns out that this build fails again while executing the test suite! Apparently, the release archive on Hackage is missing some data files that the test suite requires, so we cannot run it. We accomplish that by re-generating the Nix expression with the `--no-check` flag: - - $ cabal2nix --no-check cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix - +```shell +cabal2nix --no-check cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix +``` Now the builds succeeds. Of course, in the concrete example of `ghc-events` this whole exercise is not @@ -642,91 +674,71 @@ older version might be useful. GHC and distributed build farms don't get along well: - https://ghc.haskell.org/trac/ghc/ticket/4012 + - https://ghc.haskell.org/trac/ghc/ticket/4012 When you see an error like this one - - package foo-0.7.1.0 is broken due to missing package - text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91 - +``` +package foo-0.7.1.0 is broken due to missing package +text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91 +``` then you have to download and re-install `foo` and all its dependents from scratch: - - # nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \ - | xargs -L 1 nix-store --repair-path +```shell +nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \ + | xargs -L 1 nix-store --repair-path +``` If you're using additional Hydra servers other than `hydra.nixos.org`, then it might be necessary to purge the local caches that store data from those machines to disable these binary channels for the duration of the previous command, i.e. by running: - - rm /nix/var/nix/binary-cache-v3.sqlite - rm /nix/var/nix/manifests/* - rm /nix/var/nix/channel-cache/* - -### How to use the Haste Haskell-to-Javascript transpiler - -Open a shell with `haste-compiler` and `haste-cabal-install` (you don't actually need -`node`, but it can be useful to test stuff): - - $ nix-shell -p "haskellPackages.ghcWithPackages (self: with self; [haste-cabal-install haste-compiler])" -p nodejs - -You may not need the following step but if `haste-boot` fails to compile all the -packages it needs, this might do the trick - - $ haste-cabal update - -`haste-boot` builds a set of core libraries so that they can be used from Javascript -transpiled programs: - - $ haste-boot - -Transpile and run a "Hello world" program: - - $ echo 'module Main where main = putStrLn "Hello world"' > hello-world.hs - $ hastec --onexec hello-world.hs - $ node hello-world.js - Hello world +```shell +rm /nix/var/nix/binary-cache-v3.sqlite +rm /nix/var/nix/manifests/* +rm /nix/var/nix/channel-cache/* +``` ### Builds on Darwin fail with `math.h` not found Users of GHC on Darwin have occasionally reported that builds fail, because the compiler complains about a missing include file: - - fatal error: 'math.h' file not found - +``` +fatal error: 'math.h' file not found +``` The issue has been discussed at length in [ticket 6390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good solution has been proposed. As a work-around, users who run into this problem can configure the environment variables - - export NIX_CFLAGS_COMPILE="-idirafter /usr/include" - export NIX_CFLAGS_LINK="-L/usr/lib" - +```shell +export NIX_CFLAGS_COMPILE="-idirafter /usr/include" +export NIX_CFLAGS_LINK="-L/usr/lib" +``` in their `~/.bashrc` file to avoid the compiler error. ### Builds using Stack complain about missing system libraries - -- While building package zlib-0.5.4.2 using: - runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...] - Process exited with code: ExitFailure 1 - Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log - - Configuring zlib-0.5.4.2... - Setup.hs: Missing dependency on a foreign library: - * Missing (or bad) header file: zlib.h - This problem can usually be solved by installing the system package that - provides this library (you may need the "-dev" version). If the library is - already installed but in a non-standard location then you can use the flags - --extra-include-dirs= and --extra-lib-dirs= to specify where it is. - If the header file does exist, it may contain errors that are caught by the C - compiler at the preprocessing stage. In this case you can re-run configure - with the verbosity flag -v3 to see the error messages. +``` +-- While building package zlib-0.5.4.2 using: + runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...] +Process exited with code: ExitFailure 1 +Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log + +Configuring zlib-0.5.4.2... +Setup.hs: Missing dependency on a foreign library: +* Missing (or bad) header file: zlib.h +This problem can usually be solved by installing the system package that +provides this library (you may need the "-dev" version). If the library is +already installed but in a non-standard location then you can use the flags +--extra-include-dirs= and --extra-lib-dirs= to specify where it is. +If the header file does exist, it may contain errors that are caught by the C +compiler at the preprocessing stage. In this case you can re-run configure +with the verbosity flag -v3 to see the error messages. +``` When you run the build inside of the nix-shell environment, the system -is configured to find libz.so without any special flags -- the compiler +is configured to find `libz.so` without any special flags -- the compiler and linker "just know" how to find it. Consequently, Cabal won't record -any search paths for libz.so in the package description, which means +any search paths for `libz.so` in the package description, which means that the package works fine inside of nix-shell, but once you leave the shell the shared object can no longer be found. That issue is by no means specific to Stack: you'll have that problem with any other @@ -735,63 +747,66 @@ environment. You can remedy this issue in several ways. The easiest is to add a `nix` section to the `stack.yaml` like the following: - - nix: - enable: true - packages: [ zlib ] - -Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include` as an -`--extra-lib-dirs` and `extra-include-dirs`, respectively. Alternatively, you -can achieve the same effect by hand. First of all, run - - $ nix-build --no-out-link "<nixpkgs>" -A zlib - /nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8 - +```yaml +nix: + enable: true + packages: [ zlib ] +``` + +Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include` +as an `--extra-lib-dirs` and `extra-include-dirs`, respectively. +Alternatively, you can achieve the same effect by hand. First of all, run +``` +$ nix-build --no-out-link "<nixpkgs>" -A zlib +/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8 +``` to find out the store path of the system's zlib library. Now, you can -1) add that path (plus a "/lib" suffix) to your $LD_LIBRARY_PATH - environment variable to make sure your system linker finds libz.so - automatically. It's no pretty solution, but it will work. + 1. add that path (plus a "/lib" suffix) to your `$LD_LIBRARY_PATH` + environment variable to make sure your system linker finds `libz.so` + automatically. It's no pretty solution, but it will work. -2) As a variant of (1), you can also install any number of system - libraries into your user's profile (or some other profile) and point - $LD_LIBRARY_PATH to that profile instead, so that you don't have to - list dozens of those store paths all over the place. + 2. As a variant of (1), you can also install any number of system + libraries into your user's profile (or some other profile) and point + `$LD_LIBRARY_PATH` to that profile instead, so that you don't have to + list dozens of those store paths all over the place. -3) The solution I prefer is to call stack with an appropriate - --extra-lib-dirs flag like so: + 3. The solution I prefer is to call stack with an appropriate + --extra-lib-dirs flag like so: + ```shell + stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build + ``` - $ stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build + Typically, you'll need `--extra-include-dirs` as well. It's possible + to add those flag to the project's `stack.yaml` or your user's + global `~/.stack/global/stack.yaml` file so that you don't have to + specify them manually every time. But again, you're likely better off + using Stack's Nix support instead. - Typically, you'll need --extra-include-dirs as well. It's possible - to add those flag to the project's "stack.yaml" or your user's - global "~/.stack/global/stack.yaml" file so that you don't have to - specify them manually every time. But again, you're likely better off using - Stack's Nix support instead. - - The same thing applies to `cabal configure`, of course, if you're - building with `cabal-install` instead of Stack. + The same thing applies to `cabal configure`, of course, if you're + building with `cabal-install` instead of Stack. ### Creating statically linked binaries There are two levels of static linking. The first option is to configure the build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions, this can be achieved by setting the attribute: - - enableSharedExecutables = false; - +``` +enableSharedExecutables = false; +``` That gives you a binary with statically linked Haskell libraries and dynamically linked system libraries. To link both Haskell libraries and system libraries statically, the additional flags `--ghc-option=-optl=-static --ghc-option=-optl=-pthread` need to be used. In Nix, this is accomplished with: +``` +configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ]; +``` - configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ]; - -It's important to realize, however, that most system libraries in Nix are built -as shared libraries only, i.e. there is just no static library available that -Cabal could link! +It's important to realize, however, that most system libraries in Nix are +built as shared libraries only, i.e. there is just no static library +available that Cabal could link! ### Building GHC with integer-simple @@ -801,7 +816,7 @@ The implementation can be found in the [integer-gmp](http://hackage.haskell.org/package/integer-gmp) package. A potential problem with this is that GMP is licensed under the -[GNU Lesser General Public License (LGPL)](http://www.gnu.org/copyleft/lesser.html), +[GNU Lesser General Public License (LGPL)](http://www.gnu.org/copyleft/lesser.html), a kind of "copyleft" license. According to the terms of the LGPL, paragraph 5, you may distribute a program that is designed to be compiled and dynamically linked with the library under the terms of your choice (i.e., commercially) but @@ -814,7 +829,7 @@ The LGPL licensing for GMP is a problem for the overall licensing of binary programs compiled with GHC because most distributions (and builds) of GHC use static libraries. (Dynamic libraries are currently distributed only for OS X.) The LGPL licensing situation may be worse: even though -[The Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license) +[The Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license) is essentially a "free software" license (BSD3), according to paragraph 2 of the LGPL, GHC must be distributed under the terms of the LGPL! @@ -825,58 +840,59 @@ alternative implemention for Integer called To get a GHC compiler build with `integer-simple` instead of `integer-gmp` use the attribute: `haskell.compiler.integer-simple."${ghcVersion}"`. For example: - - $ nix-build -E '(import <nixpkgs> {}).haskell.compiler.integer-simple.ghc802' - ... - $ result/bin/ghc-pkg list | grep integer - integer-simple-0.1.1.1 - +``` +$ nix-build -E '(import <nixpkgs> {}).haskell.compiler.integer-simple.ghc802' +... +$ result/bin/ghc-pkg list | grep integer + integer-simple-0.1.1.1 +``` The following command displays the complete list of GHC compilers build with `integer-simple`: - - $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler.integer-simple - haskell.compiler.integer-simple.ghc7102 ghc-7.10.2 - haskell.compiler.integer-simple.ghc7103 ghc-7.10.3 - haskell.compiler.integer-simple.ghc722 ghc-7.2.2 - haskell.compiler.integer-simple.ghc742 ghc-7.4.2 - haskell.compiler.integer-simple.ghc783 ghc-7.8.3 - haskell.compiler.integer-simple.ghc784 ghc-7.8.4 - haskell.compiler.integer-simple.ghc801 ghc-8.0.1 - haskell.compiler.integer-simple.ghc802 ghc-8.0.2 - haskell.compiler.integer-simple.ghcHEAD ghc-8.1.20170106 +``` +$ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler.integer-simple +haskell.compiler.integer-simple.ghc7102 ghc-7.10.2 +haskell.compiler.integer-simple.ghc7103 ghc-7.10.3 +haskell.compiler.integer-simple.ghc722 ghc-7.2.2 +haskell.compiler.integer-simple.ghc742 ghc-7.4.2 +haskell.compiler.integer-simple.ghc783 ghc-7.8.3 +haskell.compiler.integer-simple.ghc784 ghc-7.8.4 +haskell.compiler.integer-simple.ghc801 ghc-8.0.1 +haskell.compiler.integer-simple.ghc802 ghc-8.0.2 +haskell.compiler.integer-simple.ghcHEAD ghc-8.1.20170106 +``` To get a package set supporting `integer-simple` use the attribute: `haskell.packages.integer-simple."${ghcVersion}"`. For example use the following to get the `scientific` package build with `integer-simple`: - - $ nix-build -A haskell.packages.integer-simple.ghc802.scientific - +```shell +nix-build -A haskell.packages.integer-simple.ghc802.scientific +``` ## Other resources -- The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE) - provides an introduction into Haskell NG aimed at beginners. The slides are - available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form - ready for cut & paste -- at - https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md. + - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE) + provides an introduction into Haskell NG aimed at beginners. The slides are + available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form + ready for cut & paste -- at + https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md. -- Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y), - which discusses the subject of Haskell development with Nix but also provides - a basic introduction to Nix as well, i.e. it's suitable for viewers with - almost no prior Nix experience. + - Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y), + which discusses the subject of Haskell development with Nix but also provides + a basic introduction to Nix as well, i.e. it's suitable for viewers with + almost no prior Nix experience. -- Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix). + - Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix). -- The *Journey into the Haskell NG infrastructure* series of postings - describe the new Haskell infrastructure in great detail: + - The *Journey into the Haskell NG infrastructure* series of postings + describe the new Haskell infrastructure in great detail: - - [Part 1](http://lists.science.uu.nl/pipermail/nix-dev/2015-January/015591.html) - explains the differences between the old and the new code and gives - instructions how to migrate to the new setup. + - [Part 1](https://nixos.org/nix-dev/2015-January/015591.html) + explains the differences between the old and the new code and gives + instructions how to migrate to the new setup. - - [Part 2](http://lists.science.uu.nl/pipermail/nix-dev/2015-January/015608.html) - looks in-depth at how to tweak and configure your setup by means of - overrides. + - [Part 2](https://nixos.org/nix-dev/2015-January/015608.html) + looks in-depth at how to tweak and configure your setup by means of + overrides. - - [Part 3](http://lists.science.uu.nl/pipermail/nix-dev/2015-April/016912.html) - describes the infrastructure that keeps the Haskell package set in Nixpkgs - up-to-date. + - [Part 3](https://nixos.org/nix-dev/2015-April/016912.html) + describes the infrastructure that keeps the Haskell package set in Nixpkgs + up-to-date. diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md index b127ba2faaeef..3c9df2e6e821e 100644 --- a/doc/languages-frameworks/python.md +++ b/doc/languages-frameworks/python.md @@ -580,7 +580,7 @@ running `nix-shell` with the following `shell.nix` with import <nixpkgs> {}; (python3.buildEnv.override { - extraLibs = with python3Packages; [ numpy requests2 ]; + extraLibs = with python3Packages; [ numpy requests ]; }).env ``` @@ -622,7 +622,7 @@ attribute. The `shell.nix` file from the previous section can thus be also writt ```nix with import <nixpkgs> {}; -(python33.withPackages (ps: [ps.numpy ps.requests2])).env +(python33.withPackages (ps: [ps.numpy ps.requests])).env ``` In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options @@ -710,7 +710,7 @@ nix-env -if build.nix ``` Now you can use the Python interpreter, as well as the extra packages that you added to the environment. -#### Environment defined in `~/.nixpkgs/config.nix` +#### Environment defined in `~/.config/nixpkgs/config.nix` If you prefer to, you could also add the environment as a package override to the Nixpkgs set. ```nix @@ -923,6 +923,28 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul If you are using the `bepasty-server` package somewhere, for example in `systemPackages` or indirectly from `services.bepasty`, then a `nixos-rebuild switch` will rebuild the system but with the `bepasty-server` package using a different `src` attribute. This way one can modify `python` based software/libraries easily. Using `self` and `super` one can also alter dependencies (`buildInputs`) between the old state (`self`) and new state (`super`). +### How to override a Python package using overlays? + +To alter a python package using overlays, you would use the following approach: + +```nix +self: super: +rec { + python = super.python.override { + packageOverrides = python-self: python-super: { + bepasty-server = python-super.bepasty-server.overrideAttrs ( oldAttrs: { + src = self.pkgs.fetchgit { + url = "https://github.com/bepasty/bepasty-server"; + sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps"; + rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d"; + }; + }); + }; + }; + pythonPackages = python.pkgs; +} +``` + ## Contributing ### Contributing guidelines diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml index b6c8f0e899e6a..1dbbb5341ba38 100644 --- a/doc/languages-frameworks/qt.xml +++ b/doc/languages-frameworks/qt.xml @@ -2,31 +2,55 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-language-qt"> -<title>Qt and KDE</title> - -<para>Qt is a comprehensive desktop and mobile application development toolkit for C++. Legacy support is available for Qt 3 and Qt 4, but all current development uses Qt 5. The Qt 5 packages in Nixpkgs are updated frequently to take advantage of new features, but older versions are typically retained to support packages that may not be compatible with the latest version. When packaging applications and libraries for Nixpkgs, it is important to ensure that compatible versions of Qt 5 are used throughout; this consideration motivates the tools described below.</para> - -<section xml:id="ssec-qt-libraries"><title>Libraries</title> - -<para>Libraries that depend on Qt 5 should be built with each available version to avoid linking a dependent package against incompatible versions of Qt 5. (Although Qt 5 maintains backward ABI compatibility, linking against multiple versions at once is generally not possible; at best it will lead to runtime faults.) Packages that provide libraries should be added to the top-level function <varname>mkLibsForQt5</varname>, which is used to build a set of libraries for every Qt 5 version. The <varname>callPackage</varname> provided in this scope will ensure that only one Qt version will be used throughout the dependency tree. Dependencies should be imported unqualified, i.e. <literal>qtbase</literal> not <literal>qt5.qtbase</literal>, so that <varname>callPackage</varname> can do its work. <emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal> into your package; although it may work fine in the moment, it could well break at the next Qt update.</para> - -<para>If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute. A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version.</para> +<title>Qt</title> + +<para> +Qt is a comprehensive desktop and mobile application development toolkit for C++. +Legacy support is available for Qt 3 and Qt 4, but all current development uses Qt 5. +The Qt 5 packages in Nixpkgs are updated frequently to take advantage of new features, +but older versions are typically retained until their support window ends. +The most important consideration in packaging Qt-based software is ensuring that each package and all its dependencies use the same version of Qt 5; +this consideration motivates most of the tools described below. +</para> + +<section xml:id="ssec-qt-libraries"><title>Packaging Libraries for Nixpkgs</title> + +<para> +Whenever possible, libraries that use Qt 5 should be built with each available version. +Packages providing libraries should be added to the top-level function <varname>mkLibsForQt5</varname>, +which is used to build a set of libraries for every Qt 5 version. +A special <varname>callPackage</varname> function is used in this scope to ensure that the entire dependency tree uses the same Qt 5 version. +Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. +<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>. +</para> + +<para> +If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute. +A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version. +</para> </section> -<section xml:id="ssec-qt-applications"><title>Applications</title> - -<para>Applications generally do not need to be built with every Qt version because they do not provide any libraries for dependent packages to link against. The primary consideration is merely ensuring that the application itself and its dependencies are linked against only one version of Qt. To call your application expression, use <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>. Dependencies should be imported unqualified, i.e. <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. <emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal> into your package; although it may work fine in the moment, it could well break at the next Qt update.</para> - -<para>It is generally best to build an application package against the <varname>libsForQt5</varname> library set. In case a package does not build with the latest Qt version, it is possible to pick a set pinned to a particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that is the latest version the package supports.</para> - -<para>Qt-based applications require that several paths be set at runtime. This is accomplished by wrapping the provided executables in a package with <literal>wrapQtProgram</literal> or <literal>makeQtWrapper</literal> during the <literal>postFixup</literal> phase. To use the wrapper generators, add <literal>makeQtWrapper</literal> to <literal>nativeBuildInputs</literal>. The wrapper generators support the same options as <literal>wrapProgram</literal> and <literal>makeWrapper</literal> respectively. It is usually only necessary to generate wrappers for programs intended to be invoked by the user.</para> - -</section> - -<section xml:id="ssec-qt-kde"><title>KDE</title> - -<para>The KDE Frameworks are a set of libraries for Qt 5 which form the basis of the Plasma desktop environment and the KDE Applications suite. Packaging a Frameworks-based library does not require any steps beyond those described above for general Qt-based libraries. Frameworks-based applications should not use <literal>makeQtWrapper</literal>; instead, use <literal>kdeWrapper</literal> to create the necessary wrappers: <literal>kdeWrapper { unwrapped = <replaceable>expr</replaceable>; targets = <replaceable>exes</replaceable>; }</literal>, where <replaceable>expr</replaceable> is the un-wrapped package expression and <replaceable>exes</replaceable> is a list of strings giving the relative paths to programs in the package which should be wrapped.</para> +<section xml:id="ssec-qt-applications"><title>Packaging Applications for Nixpkgs</title> + +<para> +Call your application expression using <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>. +Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. +<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>. +</para> + +<para> +Qt 5 maintains strict backward compatibility, so it is generally best to build an application package against the latest version using the <varname>libsForQt5</varname> library set. +In case a package does not build with the latest Qt version, it is possible to pick a set pinned to a particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that is the latest version the package supports. +If a package must be pinned to an older Qt version, be sure to file a bug upstream; +because Qt is strictly backwards-compatible, any incompatibility is by definition a bug in the application. +</para> + +<para> +When testing applications in Nixpkgs, it is a common practice to build the package with <literal>nix-build</literal> and run it using the created symbolic link. +This will not work with Qt applications, however, because they have many hard runtime requirements that can only be guaranteed if the package is actually installed. +To test a Qt application, install it with <literal>nix-env</literal> or run it inside <literal>nix-shell</literal>. +</para> </section> diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.md index 5442d706cb0b1..1d6a4fe8da8d6 100644 --- a/doc/languages-frameworks/vim.md +++ b/doc/languages-frameworks/vim.md @@ -8,15 +8,48 @@ date: 2016-06-25 You'll get a vim(-your-suffix) in PATH also loading the plugins you want. Loading can be deferred; see examples. -VAM (=vim-addon-manager) and Pathogen plugin managers are supported. -Vundle, NeoBundle could be your turn. +Vim packages, VAM (=vim-addon-manager) and Pathogen are supported to load +packages. -## dependencies by Vim plugins +## Custom configuration + +Adding custom .vimrc lines can be done using the following code: + +``` +vim_configurable.customize { + name = "vim-with-plugins"; + + vimrcConfig.customRC = '' + set hidden + ''; +} +``` + +## Vim packages + +To store you plugins in Vim packages the following example can be used: + +``` +vim_configurable.customize { + vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; { + # loaded on launch + start = [ youcompleteme fugitive ]; + # manually loadable by calling `:packadd $plugin-name` + opt = [ phpCompletion elm-vim ]; + # To automatically load a plugin when opening a filetype, add vimrc lines like: + # autocmd FileType php :packadd phpCompletion + } +}; +``` + +## VAM + +### dependencies by Vim plugins VAM introduced .json files supporting dependencies without versioning assuming that "using latest version" is ok most of the time. -## HOWTO +### Example First create a vim-scripts file having one plugin name per line. Example: diff --git a/doc/overlays.xml b/doc/overlays.xml index 4b95f3e72880a..f8f554bb5569c 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -78,7 +78,7 @@ self: super: <para>The first argument, usually named <varname>self</varname>, corresponds to the final package set. You should use this set for the dependencies of all packages specified in your overlay. For example, all the dependencies of <varname>rr</varname> in the example above come -from <varname>self</varname>, as well as the overriden dependencies used in the +from <varname>self</varname>, as well as the overridden dependencies used in the <varname>boost</varname> override.</para> <para>The second argument, usually named <varname>super</varname>, diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 0f148f5c898ad..33a61f31938c5 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -516,4 +516,140 @@ to your configuration, rebuild, and run the game with </section> +<section xml:id="sec-emacs"> + +<title>Emacs</title> + +<section xml:id="sec-emacs-config"> + +<title>Configuring Emacs</title> + +<para> + The Emacs package comes with some extra helpers to make it easier to + configure. <varname>emacsWithPackages</varname> allows you to manage + packages from ELPA. This means that you will not have to install + that packages from within Emacs. For instance, if you wanted to use + <literal>company</literal>, <literal>counsel</literal>, + <literal>flycheck</literal>, <literal>ivy</literal>, + <literal>magit</literal>, <literal>projectile</literal>, and + <literal>use-package</literal> you could use this as a + <filename>~/.config/nixpkgs/config.nix</filename> override: +</para> + +<screen> +{ + packageOverrides = pkgs: with pkgs; { + myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ + company + counsel + flycheck + ivy + magit + projectile + use-package + ])); + } +} +</screen> + +<para> + You can install it like any other packages via <command>nix-env -iA + myEmacs</command>. However, this will only install those packages. + It will not <literal>configure</literal> them for us. To do this, we + need to provide a configuration file. Luckily, it is possible to do + this from within Nix! By modifying the above example, we can make + Emacs load a custom config file. The key is to create a package that + provide a <filename>default.el</filename> file in + <filename>/share/emacs/site-start/</filename>. Emacs knows to load + this file automatically when it starts. +</para> + +<screen> +{ + packageOverrides = pkgs: with pkgs; rec { + myEmacsConfig = writeText "default.el" '' +;; initialize package + +(require 'package) +(package-initialize 'noactivate) +(eval-when-compile + (require 'use-package)) + +;; load some packages + +(use-package company + :bind ("<C-tab>" . company-complete) + :diminish company-mode + :commands (company-mode global-company-mode) + :defer 1 + :config + (global-company-mode)) + +(use-package counsel + :commands (counsel-descbinds) + :bind (([remap execute-extended-command] . counsel-M-x) + ("C-x C-f" . counsel-find-file) + ("C-c g" . counsel-git) + ("C-c j" . counsel-git-grep) + ("C-c k" . counsel-ag) + ("C-x l" . counsel-locate) + ("M-y" . counsel-yank-pop))) + +(use-package flycheck + :defer 2 + :config (global-flycheck-mode)) + +(use-package ivy + :defer 1 + :bind (("C-c C-r" . ivy-resume) + ("C-x C-b" . ivy-switch-buffer) + :map ivy-minibuffer-map + ("C-j" . ivy-call)) + :diminish ivy-mode + :commands ivy-mode + :config + (ivy-mode 1)) + +(use-package magit + :defer + :if (executable-find "git") + :bind (("C-x g" . magit-status) + ("C-x G" . magit-dispatch-popup)) + :init + (setq magit-completing-read-function 'ivy-completing-read)) + +(use-package projectile + :commands projectile-mode + :bind-keymap ("C-c p" . projectile-command-map) + :defer 5 + :config + (projectile-global-mode)) + ''; + myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ + (runCommand "default.el" {} '' +mkdir -p $out/share/emacs/site-lisp +cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el +'') + company + counsel + flycheck + ivy + magit + projectile + use-package + ])); + }; +} +</screen> + +<para> + This provides a fairly full Emacs start file. It will load in + addition to the user's presonal config. You can always disable it by + passing <command>-q</command> to the Emacs command. +</para> + +</section> + +</section> + </chapter> diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 5ed959abacec5..ca86e6c9519b6 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -212,7 +212,7 @@ $ nix-env -f . -iA libfoo</screen> <listitem> <para>Optionally commit the new package and open a pull request, or send a patch to - <literal>nix-dev@cs.uu.nl</literal>.</para> + <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.</para> </listitem> diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml index f86928bcd5d07..0813e0968e86e 100644 --- a/doc/reviewing-contributions.xml +++ b/doc/reviewing-contributions.xml @@ -18,7 +18,7 @@ <para>The high change rate of nixpkgs make any pull request that is open for long enough subject to conflicts that will require extra work from the submitter or the merger. Reviewing pull requests in a timely manner and being - responsive to the comments is the key to avoid these. Github provides sort + responsive to the comments is the key to avoid these. GitHub provides sort filters that can be used to see the <link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most recently</link> and the <link diff --git a/doc/stdenv.xml b/doc/stdenv.xml index a2530e102ca8c..e637962fbb7d0 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -318,7 +318,13 @@ containing some shell commands to be executed, or by redefining the shell function <varname><replaceable>name</replaceable>Phase</varname>. The former is convenient to override a phase from the derivation, while the -latter is convenient from a build script.</para> +latter is convenient from a build script. + +However, typically one only wants to <emphasis>add</emphasis> some +commands to a phase, e.g. by defining <literal>postInstall</literal> +or <literal>preFixup</literal>, as skipping some of the default actions +may have unexpected consequences. +</para> <section xml:id="ssec-controlling-phases"><title>Controlling @@ -635,6 +641,16 @@ script) if it exists.</para> </varlistentry> <varlistentry> + <term><varname>configurePlatforms</varname></term> + <listitem><para> + By default, when cross compiling, the configure script has <option>--build=...</option> and <option>--host=...</option> passed. + Packages can instead pass <literal>[ "build" "host" "target" ]</literal> or a subset to control exactly which platform flags are passed. + Compilers and other tools should use this to also pass the target platform, for example. + Note eventually these will be passed when in native builds too, to improve determinism: build-time guessing, as is done today, is a risk of impurity. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>preConfigure</varname></term> <listitem><para>Hook executed at the start of the configure phase.</para></listitem> @@ -1156,7 +1172,7 @@ makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello <term><option>--replace</option> <replaceable>s1</replaceable> <replaceable>s2</replaceable></term> - <listitem><para>Replace every occurence of the string + <listitem><para>Replace every occurrence of the string <replaceable>s1</replaceable> by <replaceable>s2</replaceable>.</para></listitem> </varlistentry> @@ -1164,7 +1180,7 @@ makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello <varlistentry> <term><option>--subst-var</option> <replaceable>varName</replaceable></term> - <listitem><para>Replace every occurence of + <listitem><para>Replace every occurrence of <literal>@<replaceable>varName</replaceable>@</literal> by the contents of the environment variable <replaceable>varName</replaceable>. This is useful for @@ -1177,7 +1193,7 @@ makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello <term><option>--subst-var-by</option> <replaceable>varName</replaceable> <replaceable>s</replaceable></term> - <listitem><para>Replace every occurence of + <listitem><para>Replace every occurrence of <literal>@<replaceable>varName</replaceable>@</literal> by the string <replaceable>s</replaceable>.</para></listitem> </varlistentry> @@ -1225,7 +1241,7 @@ substitute ./foo.in ./foo.out \ <term><function>substituteAll</function> <replaceable>infile</replaceable> <replaceable>outfile</replaceable></term> - <listitem><para>Replaces every occurence of + <listitem><para>Replaces every occurrence of <literal>@<replaceable>varName</replaceable>@</literal>, where <replaceable>varName</replaceable> is any environment variable, in <replaceable>infile</replaceable>, writing the result to @@ -1528,7 +1544,7 @@ bin/blib.a(bios_console.o): In function `bios_handle_cup': depends on such a format string, it will need to be worked around. </para> - <para>Addtionally, some warnings are enabled which might trigger build + <para>Additionally, some warnings are enabled which might trigger build failures if compiler warnings are treated as errors in the package build. In this case, set <option>NIX_CFLAGS_COMPILE</option> to <option>-Wno-error=warning-type</option>.</para> @@ -1558,7 +1574,7 @@ fcntl2.h:50:4: error: call to '__open_missing_mode' declared with attribute erro <term><varname>pic</varname></term> <listitem> <para>Adds the <option>-fPIC</option> compiler options. This options adds - support for position independant code in shared libraries and thus making + support for position independent code in shared libraries and thus making ASLR possible.</para> <para>Most notably, the Linux kernel, kernel modules and other code not running in an operating system environment like boot loaders won't |