diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/coding-conventions.xml | 6 | ||||
| -rw-r--r-- | doc/configuration.xml | 224 | ||||
| -rw-r--r-- | doc/cross-compilation.xml | 216 | ||||
| -rw-r--r-- | doc/default.nix | 8 | ||||
| -rw-r--r-- | doc/functions.xml | 22 | ||||
| -rw-r--r-- | doc/languages-frameworks/haskell.md | 834 | ||||
| -rw-r--r-- | doc/languages-frameworks/index.xml | 2 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.md | 382 | ||||
| -rw-r--r-- | doc/languages-frameworks/qt.xml | 62 | ||||
| -rw-r--r-- | doc/languages-frameworks/ruby.xml | 5 | ||||
| -rw-r--r-- | doc/languages-frameworks/rust.md | 91 | ||||
| -rw-r--r-- | doc/languages-frameworks/vim.md | 102 | ||||
| -rw-r--r-- | doc/manual.xml | 1 | ||||
| -rw-r--r-- | doc/multiple-output.xml | 1 | ||||
| -rw-r--r-- | doc/old/cross.txt | 12 | ||||
| -rw-r--r-- | doc/overlays.xml | 8 | ||||
| -rw-r--r-- | doc/package-notes.xml | 2 | ||||
| -rw-r--r-- | doc/stdenv.xml | 132 |
18 files changed, 1438 insertions, 672 deletions
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index 4348dc8bf720..f89437af445c 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -623,7 +623,7 @@ evaluate correctly.</para> from bad to good: <itemizedlist> <listitem> - <para>Uses <literal>git://</literal> which won't be proxied. + <para>Bad: Uses <literal>git://</literal> which won't be proxied. <programlisting> src = fetchgit { url = "git://github.com/NixOS/nix.git"; @@ -634,7 +634,7 @@ src = fetchgit { </para> </listitem> <listitem> - <para>This is ok, but an archive fetch will still be faster. + <para>Better: This is ok, but an archive fetch will still be faster. <programlisting> src = fetchgit { url = "https://github.com/NixOS/nix.git"; @@ -645,7 +645,7 @@ src = fetchgit { </para> </listitem> <listitem> - <para>Fetches a snapshot archive and you get the rev you want. + <para>Best: Fetches a snapshot archive and you get the rev you want. <programlisting> src = fetchFromGitHub { owner = "NixOS"; diff --git a/doc/configuration.xml b/doc/configuration.xml index caff1e510cdd..56950e07ab5c 100644 --- a/doc/configuration.xml +++ b/doc/configuration.xml @@ -2,85 +2,223 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-packageconfig"> -<title><filename>~/.nixpkgs/config.nix</filename>: global configuration</title> +<title>Global configuration</title> -<para>Nix packages can be configured to allow or deny certain options.</para> +<para>Nix comes with certain defaults about what packages can and +cannot be installed, based on a package's metadata. By default, Nix +will prevent installation if any of the following criteria are +true:</para> -<para>To apply the configuration edit -<filename>~/.nixpkgs/config.nix</filename> and set it like +<itemizedlist> + <listitem><para>The package is thought to be broken, and has had + its <literal>meta.broken</literal> set to + <literal>true</literal>.</para></listitem> + + <listitem><para>The package's <literal>meta.license</literal> is set + to a license which is considered to be unfree.</para></listitem> + + <listitem><para>The package has known security vulnerabilities but + has not or can not be updated for some reason, and a list of issues + has been entered in to the package's + <literal>meta.knownVulnerabilities</literal>.</para></listitem> +</itemizedlist> + +<para>Note that all this is checked during evaluation already, +and the check includes any package that is evaluated. +In particular, all build-time dependencies are checked. +<literal>nix-env -qa</literal> will (attempt to) hide any packages +that would be refused. +</para> + +<para>Each of these criteria can be altered in the nixpkgs +configuration.</para> + +<para>The nixpkgs configuration for a NixOS system is set in the +<literal>configuration.nix</literal>, as in the following example: +<programlisting> +{ + nixpkgs.config = { + allowUnfree = true; + }; +} +</programlisting> +However, this does not allow unfree software for individual users. +Their configurations are managed separately.</para> +<para>A user's of nixpkgs configuration is stored in a user-specific +configuration file located at +<filename>~/.config/nixpkgs/config.nix</filename>. For example: <programlisting> { allowUnfree = true; } </programlisting> +</para> -and will allow the Nix package manager to install unfree licensed packages.</para> +<section xml:id="sec-allow-broken"> + <title>Installing broken packages</title> -<para>The configuration as listed also applies to NixOS under -<option>nixpkgs.config</option> set.</para> -<itemizedlist> + <para>There are two ways to try compiling a package which has been + marked as broken.</para> - <listitem> - <para>Allow installing of packages that are distributed under - unfree license by setting <programlisting>allowUnfree = - true;</programlisting> or deny them by setting it to - <literal>false</literal>.</para> + <itemizedlist> + <listitem><para> + For allowing the build of a broken package once, you can use an + environment variable for a single invocation of the nix tools: - <para>Same can be achieved by setting the environment variable: + <programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting> + </para></listitem> + + <listitem><para> + For permanently allowing broken packages to be built, you may + add <literal>allowBroken = true;</literal> to your user's + configuration file, like this: <programlisting> -$ export NIXPKGS_ALLOW_UNFREE=1 +{ + allowBroken = true; +} </programlisting> + </para></listitem> + </itemizedlist> +</section> + +<section xml:id="sec-allow-unfree"> + <title>Installing unfree packages</title> - </para> - </listitem> + <para>There are several ways to tweak how Nix handles a package + which has been marked as unfree.</para> - <listitem> - <para>Whenever unfree packages are not allowed, single packages - can still be allowed by a predicate function that accepts package - as an argument and should return a boolean: + <itemizedlist> + <listitem><para> + To temporarily allow all unfree packages, you can use an + environment variable for a single invocation of the nix tools: + <programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting> + </para></listitem> + + <listitem><para> + It is possible to permanently allow individual unfree packages, + while still blocking unfree packages by default using the + <literal>allowUnfreePredicate</literal> configuration + option in the user configuration file.</para> + + <para>This option is a function which accepts a package as a + parameter, and returns a boolean. The following example + configuration accepts a package and always returns false: <programlisting> -allowUnfreePredicate = (pkg: ...); +{ + allowUnfreePredicate = (pkg: false); +} </programlisting> + </para> - Example to allow flash player and visual studio code only: + <para>A more useful example, the following configuration allows + only allows flash player and visual studio code: <programlisting> -allowUnfreePredicate = with builtins; (pkg: elem (parseDrvName pkg.name).name [ "flashplayer" "vscode" ]); +{ + allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]); +} </programlisting> + </para></listitem> - </para> - </listitem> + <listitem> + <para>It is also possible to whitelist and blacklist licenses + that are specifically acceptable or not acceptable, using + <literal>whitelistedLicenses</literal> and + <literal>blacklistedLicenses</literal>, respectively. + </para> - <listitem> - <para>Whenever unfree packages are not allowed, packages can still - be whitelisted by their license: + <para>The following example configuration whitelists the + licenses <literal>amd</literal> and <literal>wtfpl</literal>: <programlisting> -whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ]; +{ + whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ]; +} </programlisting> - </para> - </listitem> + </para> - <listitem> - <para>In addition to whitelisting licenses which are denied by the - <literal>allowUnfree</literal> setting, you can also explicitely - deny installation of packages which have a certain license: + <para>The following example configuration blacklists the + <literal>gpl3</literal> and <literal>agpl3</literal> licenses: <programlisting> -blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ]; +{ + blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ]; +} </programlisting> - </para> - </listitem> + </para> + </listitem> + </itemizedlist> + + <para>A complete list of licenses can be found in the file + <filename>lib/licenses.nix</filename> of the nixpkgs tree.</para> +</section> -</itemizedlist> -<para>A complete list of licenses can be found in the file -<filename>lib/licenses.nix</filename> of the nix package tree.</para> +<section xml:id="sec-allow-insecure"> + <title> + Installing insecure packages + </title> + <para>There are several ways to tweak how Nix handles a package + which has been marked as insecure.</para> + + <itemizedlist> + <listitem><para> + To temporarily allow all insecure packages, you can use an + environment variable for a single invocation of the nix tools: + + <programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting> + </para></listitem> + + <listitem><para> + It is possible to permanently allow individual insecure + packages, while still blocking other insecure packages by + default using the <literal>permittedInsecurePackages</literal> + configuration option in the user configuration file.</para> + + <para>The following example configuration permits the + installation of the hypothetically insecure package + <literal>hello</literal>, version <literal>1.2.3</literal>: +<programlisting> +{ + permittedInsecurePackages = [ + "hello-1.2.3" + ]; +} +</programlisting> + </para> + </listitem> + + <listitem><para> + It is also possible to create a custom policy around which + insecure packages to allow and deny, by overriding the + <literal>allowInsecurePredicate</literal> configuration + option.</para> + + <para>The <literal>allowInsecurePredicate</literal> option is a + function which accepts a package and returns a boolean, much + like <literal>allowUnfreePredicate</literal>.</para> + + <para>The following configuration example only allows insecure + packages with very short names: + +<programlisting> +{ + allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) <= 5); +} +</programlisting> + </para> + + <para>Note that <literal>permittedInsecurePackages</literal> is + only checked if <literal>allowInsecurePredicate</literal> is not + specified. + </para></listitem> + </itemizedlist> +</section> <!--============================================================--> @@ -89,7 +227,7 @@ packages via <literal>packageOverrides</literal></title> <para>You can define a function called <varname>packageOverrides</varname> in your local -<filename>~/.nixpkgs/config.nix</filename> to overide nix packages. It +<filename>~/.config/nixpkgs/config.nix</filename> to overide nix packages. It must be a function that takes pkgs as an argument and return modified set of packages. diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml new file mode 100644 index 000000000000..728616a9f263 --- /dev/null +++ b/doc/cross-compilation.xml @@ -0,0 +1,216 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="chap-cross"> + +<title>Cross-compilation</title> + +<section xml:id="sec-cross-intro"> + <title>Introduction</title> + <para> + "Cross-compilation" means compiling a program on one machine for another type of machine. + For example, a typical use of cross compilation is to compile programs for embedded devices. + These devices often don't have the computing power and memory to compile their own programs. + One might think that cross-compilation is a fairly niche concern, but there are advantages to being rigorous about distinguishing build-time vs run-time environments even when one is developing and deploying on the same machine. + Nixpkgs is increasingly adopting this opinion in that packages should be written with cross-compilation in mind, and nixpkgs should evaluate in a similar way (by minimizing cross-compilation-specific special cases) whether or not one is cross-compiling. + </para> + + <para> + This chapter will be organized in three parts. + First, it will describe the basics of how to package software in a way that supports cross-compilation. + Second, it will describe how to use Nixpkgs when cross-compiling. + Third, it will describe the internal infrastructure supporting cross-compilation. + </para> +</section> + +<!--============================================================--> + +<section xml:id="sec-cross-packaging"> + <title>Packaging in a cross-friendly manner</title> + + <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. + <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> + </para> + <variablelist> + <varlistentry> + <term><varname>buildPlatform</varname></term> + <listitem><para> + The "build platform" is the platform on which a package is built. + Once someone has a built package, or pre-built binary package, the build platform should not matter and be safe to ignore. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>hostPlatform</varname></term> + <listitem><para> + The "host platform" is the platform on which a package is run. + This is the simplest platform to understand, but also the one with the worst name. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>targetPlatform</varname></term> + <listitem> + <para> + 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. + </para> + <para> + There is no fundamental need to think about the target ahead of time like this. + LLVM, for example, was designed from the beginning with cross-compilation in mind, and so a normal LLVM binary will support every architecture that LLVM supports. + If the tool supports modular or pluggable backends, one might imagine specifying a <emphasis>set</emphasis> of target platforms / backends one wishes to support, rather than a single one. + </para> + <para> + The biggest reason for mess, if there is one, is that many compilers have the bad habit a build process that builds the compiler and standard library/runtime together. + Then the specifying target platform is essential, because it determines the host platform of the standard library/runtime. + Nixpkgs tries to avoid this where possible too, but still, because the concept of a target platform is so ingrained now in Autoconf and other tools, it is best to support it as is. + Tools like LLVM that don't need up-front target platforms can safely ignore it like normal packages, and it will do no harm. + </para> + </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. + For now, here are few fields can count on them containing: + </para> + <variablelist> + <varlistentry> + <term><varname>system</varname></term> + <listitem> + <para> + This is a two-component shorthand for the platform. + Examples of this would be "x86_64-darwin" and "i686-linux"; see <literal>lib.systems.doubles</literal> for more. + This format isn't very standard, but has built-in support in Nix, such as the <varname>builtins.currentSystem</varname> impure string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>config</varname></term> + <listitem> + <para> + This is a 3- or 4- component shorthand for the platform. + Examples of this would be "x86_64-unknown-linux-gnu" and "aarch64-apple-darwin14". + This is a standard format called the "LLVM target triple", as they are pioneered by LLVM and traditionally just used for the <varname>targetPlatform</varname>. + This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. + This needs a better name than <varname>config</varname>! + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>parsed</varname></term> + <listitem> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>platform</varname></term> + <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. + Please help us triage these flags and give them better homes! + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Specifying Dependencies</title> + <para> + As mentioned in the introduction to this chapter, one can think about a build time vs run time distinction whether cross-compiling or not. + In the case of cross-compilation, this corresponds with whether a derivation running on the native or foreign platform is produced. + An interesting thing to think about is how this corresponds with the three Autoconf platforms. + In the run-time case, the depending and depended-on package simply have matching build, host, and target platforms. + But in the build-time case, one can imagine "sliding" the platforms one over. + The depended-on package's host and target platforms (respectively) become the depending package's build and host platforms. + This is the most important guiding principle behind cross-compilation with Nixpkgs, and will be called the <wordasword>sliding window principle</wordasword>. + In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive dependencies. + </para> + <para> + Some examples will probably make this clearer. + If a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, bar, bar)</literal>, then its build-time dependencies would have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> build-time dependencies would have triple of <literal>(foo, foo, foo)</literal>. + In other words, it should take two "rounds" of following build-time dependency edges before one reaches a fixed point where, by the sliding window principle, the platform triple no longer changes. + Indeed, this happens with cross compilation, where only rounds of native dependencies starting with the second necessarily coincide with native packages. + </para> + <note><para> + 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. + 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" />. + 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. + For now, feel free to use either method. + </para> + <note><para> + There is also a "backlink" <varname>__targetPackages</varname>, yielding a package set whose <varname>buildPackages</varname> is the current package set. + This is a hack, though, to accommodate compilers with lousy build systems. + Please do not use this unless you are absolutely sure you are packaging such a compiler and there is no other way. + </para></note> + </section> + +</section> + +<!--============================================================--> + +<section xml:id="sec-cross-usage"> + <title>Cross-building packages</title> + <note><para> + 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. + </para> + <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. + A simple "build vs deploy" dichotomy is adequate: the sliding window principle described in the previous section shows how to interpolate between the these two "end points" to get the 3 platform triple for each bootstrapping stage. + That means for any package a given package set, even those not bound on the top level but only reachable via dependencies or <varname>buildPackages</varname>, the three platforms will be defined as one of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the former replacing the latter as one traverses build-time dependencies. + A last simple difference then is <varname>crossSystem</varname> should be null when one doesn't want to cross-compile, while the <varname>*Platform</varname>s are always non-null. + <varname>localSystem</varname> is always non-null. + </para> +</section> + +<!--============================================================--> + +<section xml:id="sec-cross-infra"> + <title>Cross-compilation infrastructure</title> + <para>To be written.</para> + <note><para> + If one explores nixpkgs, they will see derivations with names like <literal>gccCross</literal>. + Such <literal>*Cross</literal> derivations is a holdover from before we properly distinguished between the host and target platforms + —the derivation with "Cross" in the name covered the <literal>build = host != target</literal> case, while the other covered the <literal>host = target</literal>, with build platform the same or not based on whether one was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>. + This ugliness will disappear soon. + </para></note> +</section> + +</chapter> diff --git a/doc/default.nix b/doc/default.nix index 625c716b0319..540a209c2ac9 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -68,6 +68,14 @@ pkgs.stdenv.mkDerivation { inputFile = ../pkgs/development/r-modules/README.md; outputFile = "languages-frameworks/r.xml"; } + + toDocbook { + inputFile = ./languages-frameworks/rust.md; + outputFile = "./languages-frameworks/rust.xml"; + } + + toDocbook { + inputFile = ./languages-frameworks/vim.md; + outputFile = "./languages-frameworks/vim.xml"; + } + '' echo ${lib.nixpkgsVersion} > .version diff --git a/doc/functions.xml b/doc/functions.xml index 6374c15ddf2b..4e7159638cae 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -119,7 +119,7 @@ evaluation-per-function application incurs a performance penalty, which can become a problem if many overrides are used. It is only intended for ad-hoc customisation, such as in - <filename>~/.nixpkgs/config.nix</filename>. + <filename>~/.config/nixpkgs/config.nix</filename>. </para> </warning> @@ -133,7 +133,7 @@ <varname>stdenv.mkDerivation</varname>, are defined using this function, which means most packages in the nixpkgs expression, <varname>pkgs</varname>, have this function. - </para> + </para> <para> Example usage: @@ -228,7 +228,7 @@ ] name)</code> from the <literal>INI</literal> generator. It gets the name of a section and returns a sanitized name. The default <literal>mkSectionName</literal> escapes <literal>[</literal> and - <literal>]</literal> with a backslash. + <literal>]</literal> with a backslash. </para> <note><para>Nix store paths can be converted to strings by enclosing a @@ -524,6 +524,22 @@ using its <varname>buildArgs</varname> attribute. </para> + + + <note> + <para> + If you see errors similar to <literal>getProtocolByName: does not exist (no such protocol name: tcp)</literal> + you may need to add <literal>pkgs.iana-etc</literal> to <varname>contents</varname>. + </para> + </note> + + <note> + <para> + If you see errors similar to <literal>Error_Protocol ("certificate has unknown CA",True,UnknownCa)</literal> + you may need to add <literal>pkgs.cacert</literal> to <varname>contents</varname>. + </para> + </note> + </section> <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry"> diff --git a/doc/languages-frameworks/haskell.md b/doc/languages-frameworks/haskell.md index 6728f4abba0e..2ae3e39bb654 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 `~/.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 - ]); - }; - } - +of an override. After adding the following snippet to `~/.config/nixpkgs/config.nix`, +```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 - -Then edit your `~/.nixpkgs/config.nix` file to register those builds in the +```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 @@ -554,21 +582,21 @@ Every Haskell package set takes a function called `overrides` that you can use 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 `~/.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; - }); - }; - }; +following snippet in your `~/.config/nixpkgs/config.nix` file: +```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 - -Then add the override in `~/.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 {}; - }; - }; +```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`: +```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,98 @@ 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/* +```shell +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 - +```shell +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 - +```shell +haste-cabal update +``` `haste-boot` builds a set of core libraries so that they can be used from Javascript transpiled programs: - - $ haste-boot - +```shell +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 +``` +$ echo 'module Main where main = putStrLn "Hello world"' > hello-world.hs +$ hastec --onexec hello-world.hs +$ node hello-world.js +Hello world +``` ### 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,91 +774,152 @@ 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" ]; - -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! - +``` +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! + +### Building GHC with integer-simple + +By default GHC implements the Integer type using the +[GNU Multiple Precision Arithmetic (GMP) library](https://gmplib.org/). +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), +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 +if your program incorporates portions of the library, if it is linked +statically, then your program is a "derivative"--a "work based on the +library"--and according to paragraph 2, section c, you "must cause the whole of +the work to be licensed" under the terms of the LGPL (including for free). + +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) +is essentially a "free software" license (BSD3), according to +paragraph 2 of the LGPL, GHC must be distributed under the terms of the LGPL! + +To work around these problems GHC can be build with a slower but LGPL-free +alternative implemention for Integer called +[integer-simple](http://hackage.haskell.org/package/integer-simple). + +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 +``` +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 +``` + +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`: +```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](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 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](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 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](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. diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 81352ec2a9a6..fc15d847d15f 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -27,7 +27,9 @@ such as Perl or Haskell. These are described in this chapter.</para> <xi:include href="qt.xml" /> <xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md --> <xi:include href="ruby.xml" /> +<xi:include href="rust.xml" /> <xi:include href="texlive.xml" /> +<xi:include href="vim.xml" /> </chapter> diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md index 3f5d500620bb..d9306ae56bd5 100644 --- a/doc/languages-frameworks/python.md +++ b/doc/languages-frameworks/python.md @@ -3,7 +3,7 @@ ## User Guide Several versions of Python are available on Nix as well as a high amount of -packages. The default interpreter is CPython 3.5. +packages. The default interpreter is CPython 2.7. ### Using Python @@ -74,7 +74,6 @@ can do is write a simple Nix expression which sets up an environment for you, requiring you only to type `nix-shell`. Say we want to have Python 3.5, `numpy` and `toolz`, like before, in an environment. With a `shell.nix` file containing - ```nix with import <nixpkgs> {}; @@ -101,22 +100,25 @@ On Nix all packages are built by functions. The main function in Nix for buildin Let's see how we would build the `toolz` package. According to [`python-packages.nix`](https://raw.githubusercontent.com/NixOS/nixpkgs/master/pkgs/top-level/python-packages.nix) `toolz` is build using ```nix -toolz = buildPythonPackage rec{ - name = "toolz-${version}"; - version = "0.7.4"; +{ # ... - src = pkgs.fetchurl{ - url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz"; - sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd"; - }; + toolz = buildPythonPackage rec { + name = "toolz-${version}"; + version = "0.7.4"; - meta = { - homepage = "http://github.com/pytoolz/toolz/"; - description = "List processing tools and functional utilities"; - license = licenses.bsd3; - maintainers = with maintainers; [ fridh ]; + src = pkgs.fetchurl { + url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz"; + sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd"; + }; + + meta = { + homepage = "http://github.com/pytoolz/toolz/"; + description = "List processing tools and functional utilities"; + license = licenses.bsd3; + maintainers = with maintainers; [ fridh ]; + }; }; -}; +} ``` What happens here? The function `buildPythonPackage` is called and as argument @@ -129,7 +131,7 @@ specify some (optional) [meta information](http://nixos.org/nixpkgs/manual/#chap The output of the function is a derivation, which is an attribute with the name `toolz` of the set `pythonPackages`. Actually, sets are created for all interpreter versions, -so `python27Packages`, `python34Packages`, `python35Packages` and `pypyPackages`. +so e.g. `python27Packages`, `python35Packages` and `pypyPackages`. The above example works when you're directly working on `pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though, @@ -143,7 +145,7 @@ pkgs.python35Packages.buildPythonPackage rec { name = "toolz-${version}"; version = "0.8.0"; - src = pkgs.fetchurl{ + src = pkgs.fetchurl { url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz"; sha256 = "e8451af61face57b7c5d09e71c0d27b8005f001ead56e9fdf470417e5cc6d479"; }; @@ -174,7 +176,7 @@ with import <nixpkgs> {}; name = "toolz-${version}"; version = "0.8.0"; - src = pkgs.fetchurl{ + src = pkgs.fetchurl { url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz"; sha256 = "e8451af61face57b7c5d09e71c0d27b8005f001ead56e9fdf470417e5cc6d479"; }; @@ -215,25 +217,28 @@ The following example shows which arguments are given to `buildPythonPackage` in order to build [`datashape`](https://github.com/blaze/datashape). ```nix -datashape = buildPythonPackage rec { - name = "datashape-${version}"; - version = "0.4.7"; +{ # ... - src = pkgs.fetchurl { - url = "mirror://pypi/D/DataShape/${name}.tar.gz"; - sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278"; - }; + datashape = buildPythonPackage rec { + name = "datashape-${version}"; + version = "0.4.7"; - buildInputs = with self; [ pytest ]; - propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ]; + src = pkgs.fetchurl { + url = "mirror://pypi/D/DataShape/${name}.tar.gz"; + sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278"; + }; - meta = { - homepage = https://github.com/ContinuumIO/datashape; - description = "A data description language"; - license = licenses.bsd2; - maintainers = with maintainers; [ fridh ]; + buildInputs = with self; [ pytest ]; + propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ]; + + meta = { + homepage = https://github.com/ContinuumIO/datashape; + description = "A data description language"; + license = licenses.bsd2; + maintainers = with maintainers; [ fridh ]; + }; }; -}; +} ``` We can see several runtime dependencies, `numpy`, `multipledispatch`, and @@ -247,23 +252,26 @@ Python bindings to `libxml2` and `libxslt`. These libraries are only required when building the bindings and are therefore added as `buildInputs`. ```nix -lxml = buildPythonPackage rec { - name = "lxml-3.4.4"; +{ # ... - src = pkgs.fetchurl { - url = "mirror://pypi/l/lxml/${name}.tar.gz"; - sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk"; - }; + lxml = buildPythonPackage rec { + name = "lxml-3.4.4"; - buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ]; + src = pkgs.fetchurl { + url = "mirror://pypi/l/lxml/${name}.tar.gz"; + sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk"; + }; - meta = { - description = "Pythonic binding for the libxml2 and libxslt libraries"; - homepage = http://lxml.de; - license = licenses.bsd3; - maintainers = with maintainers; [ sjourdois ]; + buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ]; + + meta = { + description = "Pythonic binding for the libxml2 and libxslt libraries"; + homepage = http://lxml.de; + license = licenses.bsd3; + maintainers = with maintainers; [ sjourdois ]; + }; }; -}; +} ``` In this example `lxml` and Nix are able to work out exactly where the relevant @@ -277,33 +285,37 @@ find each of them in a different folder, and therefore we have to set `LDFLAGS` and `CFLAGS`. ```nix -pyfftw = buildPythonPackage rec { - name = "pyfftw-${version}"; - version = "0.9.2"; +{ # ... - src = pkgs.fetchurl { - url = "mirror://pypi/p/pyFFTW/pyFFTW-${version}.tar.gz"; - sha256 = "f6bbb6afa93085409ab24885a1a3cdb8909f095a142f4d49e346f2bd1b789074"; - }; + pyfftw = buildPythonPackage rec { + name = "pyfftw-${version}"; + version = "0.9.2"; - buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble]; + src = pkgs.fetchurl { + url = "mirror://pypi/p/pyFFTW/pyFFTW-${version}.tar.gz"; + sha256 = "f6bbb6afa93085409ab24885a1a3cdb8909f095a142f4d49e346f2bd1b789074"; + }; - propagatedBuildInputs = with self; [ numpy scipy ]; + buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble]; - # Tests cannot import pyfftw. pyfftw works fine though. - doCheck = false; + propagatedBuildInputs = with self; [ numpy scipy ]; - LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib" - CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include" - ''; + # Tests cannot import pyfftw. pyfftw works fine though. + doCheck = false; - meta = { - description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms"; - homepage = http://hgomersall.github.com/pyFFTW/; - license = with licenses; [ bsd2 bsd3 ]; - maintainer = with maintainers; [ fridh ]; + preConfigure = '' + export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib" + export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include" + ''; + + meta = { + description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms"; + homepage = http://hgomersall.github.com/pyFFTW/; + license = with licenses; [ bsd2 bsd3 ]; + maintainer = with maintainers; [ fridh ]; + }; }; -}; +} ``` Note also the line `doCheck = false;`, we explicitly disabled running the test-suite. @@ -316,10 +328,7 @@ That way, you can run updated code without having to reinstall after each and ev Development mode is also available. Let's see how you can use it. In the previous Nix expression the source was fetched from an url. We can also refer to a local source instead using - -```nix -src = ./path/to/source/tree; -``` +`src = ./path/to/source/tree;` If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src` is a local source, and if the local source has a `setup.py`, then development @@ -338,7 +347,7 @@ buildPythonPackage rec { name = "mypackage"; src = ./path/to/package/source; propagatedBuildInputs = [ pytest numpy pkgs.libsndfile ]; -}; +} ``` It is important to note that due to how development mode is implemented on Nix it is not possible to have multiple packages simultaneously in development mode. @@ -371,7 +380,7 @@ buildPythonPackage rec { name = "toolz-${version}"; version = "0.7.4"; - src = pkgs.fetchurl{ + src = pkgs.fetchurl { url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz"; sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd"; }; @@ -382,7 +391,7 @@ buildPythonPackage rec { license = licenses.bsd3; maintainers = with maintainers; [ fridh ]; }; -}; +} ``` It takes two arguments, `pkgs` and `buildPythonPackage`. @@ -392,7 +401,10 @@ We now call this function using `callPackage` in the definition of our environme with import <nixpkgs> {}; ( let - toolz = pkgs.callPackage ~/path/to/toolz/release.nix { pkgs=pkgs; buildPythonPackage=pkgs.python35Packages.buildPythonPackage; }; + toolz = pkgs.callPackage /path/to/toolz/release.nix { + pkgs = pkgs; + buildPythonPackage = pkgs.python35Packages.buildPythonPackage; + }; in pkgs.python35.withPackages (ps: [ ps.numpy toolz ]) ).env ``` @@ -410,8 +422,8 @@ and in this case the `python35` interpreter is automatically used. ### Interpreters -Versions 2.6, 2.7, 3.3, 3.4 and 3.5 of the CPython interpreter are available as respectively -`python26`, `python27`, `python33`, `python34` and `python35`. The PyPy interpreter +Versions 2.7, 3.3, 3.4, 3.5 and 3.6 of the CPython interpreter are available as +respectively `python27`, `python33`, `python34`, `python35` and `python36`. The PyPy interpreter is available as `pypy`. The aliases `python2` and `python3` correspond to respectively `python27` and `python35`. The default interpreter, `python`, maps to `python2`. The Nix expressions for the interpreters can be found in @@ -460,6 +472,7 @@ sets are * `pkgs.python33Packages` * `pkgs.python34Packages` * `pkgs.python35Packages` +* `pkgs.python36Packages` * `pkgs.pypyPackages` and the aliases @@ -474,22 +487,27 @@ The `buildPythonPackage` function is implemented in `pkgs/development/interpreters/python/build-python-package.nix` The following is an example: +```nix +{ # ... - twisted = buildPythonPackage { - name = "twisted-8.1.0"; + twisted = buildPythonPackage { + name = "twisted-8.1.0"; - src = pkgs.fetchurl { - url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2; - sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl"; - }; + src = pkgs.fetchurl { + url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2; + sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl"; + }; - propagatedBuildInputs = [ self.ZopeInterface ]; + propagatedBuildInputs = [ self.ZopeInterface ]; - meta = { - homepage = http://twistedmatrix.com/; - description = "Twisted, an event-driven networking engine written in Python"; - license = stdenv.lib.licenses.mit; }; - }; + meta = { + homepage = http://twistedmatrix.com/; + description = "Twisted, an event-driven networking engine written in Python"; + license = stdenv.lib.licenses.mit; + }; + }; +} +``` The `buildPythonPackage` mainly does four things: @@ -539,29 +557,32 @@ Because with an application we're not interested in multiple version the prefix Python environments can be created using the low-level `pkgs.buildEnv` function. This example shows how to create an environment that has the Pyramid Web Framework. Saving the following as `default.nix` +```nix +with import <nixpkgs> {}; - with import <nixpkgs> {}; - - python.buildEnv.override { - extraLibs = [ pkgs.pythonPackages.pyramid ]; - ignoreCollisions = true; - } +python.buildEnv.override { + extraLibs = [ pkgs.pythonPackages.pyramid ]; + ignoreCollisions = true; +} +``` and running `nix-build` will create - - /nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env +``` +/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env +``` with wrapped binaries in `bin/`. You can also use the `env` attribute to create local environments with needed packages installed. This is somewhat comparable to `virtualenv`. For example, running `nix-shell` with the following `shell.nix` +```nix +with import <nixpkgs> {}; - with import <nixpkgs> {}; - - (python3.buildEnv.override { - extraLibs = with python3Packages; [ numpy requests2 ]; - }).env +(python3.buildEnv.override { + extraLibs = with python3Packages; [ numpy requests ]; +}).env +``` will drop you into a shell where Python will have the specified packages in its path. @@ -576,34 +597,40 @@ specified packages in its path. #### python.withPackages function The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality. -It takes a function as an argument that is passed the set of python packages and returns the list +It takes a function as an argument that is passed the set of python packages and returns the list of the packages to be included in the environment. Using the `withPackages` function, the previous example for the Pyramid Web Framework environment can be written like this: +```nix +with import <nixpkgs> {}; - with import <nixpkgs> {}; - - python.withPackages (ps: [ps.pyramid]) +python.withPackages (ps: [ps.pyramid]) +``` -`withPackages` passes the correct package set for the specific interpreter version as an +`withPackages` passes the correct package set for the specific interpreter version as an argument to the function. In the above example, `ps` equals `pythonPackages`. But you can also easily switch to using python3: - - with import <nixpkgs> {}; +```nix +with import <nixpkgs> {}; - python3.withPackages (ps: [ps.pyramid]) +python3.withPackages (ps: [ps.pyramid]) +``` Now, `ps` is set to `python3Packages`, matching the version of the interpreter. As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env` attribute. The `shell.nix` file from the previous section can thus be also written like this: +```nix +with import <nixpkgs> {}; - 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 such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`. +Python 2 namespace packages may provide `__init__.py` that collide. In that case `python.buildEnv` +should be used with `ignoreCollisions = true`. + ### Development mode Development or editable mode is supported. To develop Python packages @@ -613,22 +640,24 @@ install -e . --prefix $TMPDIR/`for the package. Warning: `shellPhase` is executed only if `setup.py` exists. Given a `default.nix`: +```nix +with import <nixpkgs> {}; - with import <nixpkgs> {}; - - buildPythonPackage { name = "myproject"; +buildPythonPackage { name = "myproject"; - buildInputs = with pkgs.pythonPackages; [ pyramid ]; +buildInputs = with pkgs.pythonPackages; [ pyramid ]; - src = ./.; } +src = ./.; } +``` Running `nix-shell` with no arguments should give you the environment in which the package would be built with `nix-build`. Shortcut to setup environments with C headers/libraries and python packages: - - $ nix-shell -p pythonPackages.pyramid zlib libjpeg git +```shell +nix-shell -p pythonPackages.pyramid zlib libjpeg git +``` Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is invoked. @@ -641,6 +670,19 @@ community to help save time. No tool is preferred at the moment. - [pypi2nix](https://github.com/garbas/pypi2nix) by Rok Garbas - [pypi2nix](https://github.com/offlinehacker/pypi2nix) by Jaka Hudoklin +### Deterministic builds + +Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly. +Minor modifications had to be made to the interpreters in order to generate +deterministic bytecode. This has security implications and is relevant for +those using Python in a `nix-shell`. + +When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will have timestamp 1. +The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1` and +[PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED). +Both are also exported in `nix-shell`. + + ## FAQ ### How can I install a working Python environment? @@ -663,7 +705,7 @@ with import <nixpkgs> {}; pkgs.python35.withPackages (ps: with ps; [ numpy ipython ]) ``` and install it in your profile with -``` +```shell nix-env -if build.nix ``` Now you can use the Python interpreter, as well as the extra packages that you added to the environment. @@ -671,15 +713,19 @@ Now you can use the Python interpreter, as well as the extra packages that you a #### Environment defined in `~/.nixpkgs/config.nix` If you prefer to, you could also add the environment as a package override to the Nixpkgs set. -``` +```nix +{ # ... + packageOverrides = pkgs: with pkgs; { myEnv = python35.withPackages (ps: with ps; [ numpy ipython ]); }; +} ``` and install it in your profile with -``` +```shell nix-env -iA nixpkgs.myEnv ``` + We're installing using the attribute path and assume the channels is named `nixpkgs`. Note that I'm using the attribute path here. @@ -688,9 +734,12 @@ Note that I'm using the attribute path here. For the sake of completeness, here's another example how to install the environment system-wide. ```nix -environment.systemPackages = with pkgs; [ - (python35.withPackages(ps: with ps; [ numpy ipython ])) -]; +{ # ... + + environment.systemPackages = with pkgs; [ + (python35.withPackages(ps: with ps; [ numpy ipython ])) + ]; +} ``` ### How to solve circular dependencies? @@ -727,19 +776,18 @@ All packages in the Python package set will now use the updated `scipy` version. ```nix with import <nixpkgs> {}; -( -let - packageOverrides = self: super: { - scipy = super.scipy_0_17; - }; -in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze]) +( let + packageOverrides = self: super: { + scipy = super.scipy_0_17; + }; + in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze]) ).env ``` The requested package `blaze` depends on `pandas` which itself depends on `scipy`. If you want the whole of Nixpkgs to use your modifications, then you can use `overlays` as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`. -``` +```nix let pkgs = import <nixpkgs> {}; newpkgs = import pkgs.path { overlays = [ (pkgsself: pkgssuper: { @@ -762,32 +810,32 @@ This is because files are included that depend on items in the Nix store which h The command `bdist_wheel` takes into account `SOURCE_DATE_EPOCH`, and `nix-shell` sets this to 1. By setting it to a value corresponding to 1980 or later, or by unsetting it, it is possible to build wheels. Use 1980 as timestamp: -``` +```shell nix-shell --run "SOURCE_DATE_EPOCH=315532800 python3 setup.py bdist_wheel" ``` or the current time: -``` +```shell nix-shell --run "SOURCE_DATE_EPOCH=$(date +%s) python3 setup.py bdist_wheel" ``` or unset: -``` +```shell nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel" ``` ### `install_data` / `data_files` problems If you get the following error: - - could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': - Permission denied - -This is a [known bug](https://bitbucket.org/pypa/setuptools/issue/130/install_data-doesnt-respect-prefix) in setuptools. +``` +could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': +Permission denied +``` +This is a [known bug](https://github.com/pypa/setuptools/issues/130) in `setuptools`. Setuptools `install_data` does not respect `--prefix`. An example of such package using the feature is `pkgs/tools/X11/xpra/default.nix`. As workaround install it as an extra `preInstall` step: - - ${python.interpreter} setup.py install_data --install-dir=$out --root=$out - sed -i '/ = data\_files/d' setup.py - +```shell +${python.interpreter} setup.py install_data --install-dir=$out --root=$out +sed -i '/ = data\_files/d' setup.py +``` ### Rationale of non-existent global site-packages @@ -811,11 +859,11 @@ and install python modules through `pip` the traditional way. Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`. -``` +```nix with import <nixpkgs> {}; with pkgs.python27Packages; -stdenv.mkDerivation { +stdenv.mkDerivation { name = "impurePythonEnv"; buildInputs = [ # these packages are required for virtualenv and pip to work: @@ -823,10 +871,10 @@ stdenv.mkDerivation { python27Full python27Packages.virtualenv python27Packages.pip - # the following packages are related to the dependencies of your python - # project. - # In this particular example the python modules listed in the - # requirements.tx require the following packages to be installed locally + # the following packages are related to the dependencies of your python + # project. + # In this particular example the python modules listed in the + # requirements.tx require the following packages to be installed locally # in order to compile any binary extensions they may require. # taglib @@ -841,7 +889,7 @@ stdenv.mkDerivation { shellHook = '' # set SOURCE_DATE_EPOCH so that we can use python wheels SOURCE_DATE_EPOCH=$(date +%s) - virtualenv --no-setuptools venv + virtualenv --no-setuptools venv export PATH=$PWD/venv/bin:$PATH pip install -r requirements.txt ''; @@ -849,10 +897,31 @@ stdenv.mkDerivation { ``` Note that the `pip install` is an imperative action. So every time `nix-shell` -is executed it will attempt to download the python modules listed in +is executed it will attempt to download the python modules listed in requirements.txt. However these will be cached locally within the `virtualenv` folder and not downloaded again. +### How to override a Python package from `configuration.nix`? + +If you need to change a package's attribute(s) from `configuration.nix` you could do: + +```nix + nixpkgs.config.packageOverrides = superP: { + pythonPackages = superP.pythonPackages.override { + overrides = self: super: { + bepasty-server = super.bepasty-server.overrideAttrs ( oldAttrs: { + src = pkgs.fetchgit { + url = "https://github.com/bepasty/bepasty-server"; + sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps"; + rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d"; + }; + }); + }; + }; + }; +``` + +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`). ## Contributing @@ -860,7 +929,8 @@ folder and not downloaded again. Following rules are desired to be respected: -* Make sure package builds for all python interpreters. Use `disabled` argument to `buildPythonPackage` to set unsupported interpreters. -* If tests need to be disabled for a package, make sure you leave a comment about reasoning. -* Packages in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts. -* Python libraries are supposed to be in `python-packages.nix` and packaged with `buildPythonPackage`. Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`. +* Python libraries are supposed to be called from `python-packages.nix` and packaged with `buildPythonPackage`. The expression of a library should be in `pkgs/development/python-modules/<name>/default.nix`. Libraries in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts. +* Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`. +* Make sure libraries build for all Python interpreters. +* By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why. +* Commit names of Python libraries should include `pythonPackages`, for example `pythonPackages.numpy: 1.11 -> 1.12`. diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml index 093c33c25a17..b6c8f0e899e6 100644 --- a/doc/languages-frameworks/qt.xml +++ b/doc/languages-frameworks/qt.xml @@ -2,67 +2,31 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-language-qt"> -<title>Qt</title> +<title>Qt and KDE</title> -<para>The information in this section applies to Qt 5.5 and later.</para> - -<para>Qt is an application development toolkit for C++. Although it is -not a distinct programming language, there are special considerations -for packaging Qt-based programs and libraries. A small set of tools -and conventions has grown out of these considerations.</para> +<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>Packages that provide libraries should be listed in -<varname>qt5LibsFun</varname> so that the library is built with each -Qt version. A set of packages is provided for each version of Qt; for -example, <varname>qt5Libs</varname> always provides libraries built -with the latest version, <varname>qt55Libs</varname> provides -libraries built with Qt 5.5, and so on. To avoid version conflicts, no -top-level attributes are created for these packages.</para> +<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> </section> -<section xml:id="ssec-qt-programs"><title>Programs</title> - -<para>Application packages do not need to be built with every Qt -version. To ensure consistency between the package's dependencies, -call the package with <literal>qt5Libs.callPackage</literal> instead -of the usual <literal>callPackage</literal>. An older version may be -selected in case of incompatibility. For example, to build with Qt -5.5, call the package with -<literal>qt55Libs.callPackage</literal>.</para> - -<para>Several environment variables must be set at runtime for Qt -applications to function correctly, including:</para> - -<itemizedlist> - <listitem><para><envar>QT_PLUGIN_PATH</envar></para></listitem> - <listitem><para><envar>QML_IMPORT_PATH</envar></para></listitem> - <listitem><para><envar>QML2_IMPORT_PATH</envar></para></listitem> - <listitem><para><envar>XDG_DATA_DIRS</envar></para></listitem> -</itemizedlist> - -<para>To ensure that these are set correctly, the program must be wrapped by -invoking <literal>wrapQtProgram <replaceable>program</replaceable></literal> -during installation (for example, during -<literal>fixupPhase</literal>). <literal>wrapQtProgram</literal> -accepts the same options as <literal>makeWrapper</literal>. -</para> +<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>Many of the considerations above also apply to KDE packages, -especially the need to set the correct environment variables at -runtime. To ensure that this is done, invoke <literal>wrapKDEProgram -<replaceable>program</replaceable></literal> during -installation. <literal>wrapKDEProgram</literal> also generates a -<literal>ksycoca</literal> database so that required data and services -can be found. Like its Qt counterpart, -<literal>wrapKDEProgram</literal> accepts the same options as -<literal>makeWrapper</literal>.</para> +<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> diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml index b52361212f3a..b13da92dcc41 100644 --- a/doc/languages-frameworks/ruby.xml +++ b/doc/languages-frameworks/ruby.xml @@ -16,8 +16,7 @@ $ cd sensu $ cat > Gemfile source 'https://rubygems.org' gem 'sensu' -$ nix-shell -p bundler --command "bundler package --path /tmp/vendor/bundle" -$ $(nix-build '<nixpkgs>' -A bundix)/bin/bundix +$ $(nix-build '<nixpkgs>' -A bundix)/bin/bundix --magic $ cat > default.nix { lib, bundlerEnv, ruby }: @@ -47,7 +46,7 @@ bundlerEnv rec { so it has all the libraries necessary for <literal>sensu</literal> in its paths. The second one can be used to make derivations from custom Ruby scripts which have <filename>Gemfile</filename>s with their dependencies specified. It is a derivation with <command>ruby</command> wrapped so it can find all the needed dependencies. For example, to make a derivation <literal>my-script</literal> for a <filename>my-script.rb</filename> (which should be placed in <filename>bin</filename>) you should -run <command>bundix</command> as specified above and then use <literal>bundlerEnv</literal> lile this:</para> +run <command>bundix</command> as specified above and then use <literal>bundlerEnv</literal> like this:</para> <programlisting> <. + +## Packaging Rust applications + +Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`: + +``` +with rustPlatform; + +buildRustPackage rec { + name = "ripgrep-${version}"; + version = "0.4.0"; + + src = fetchFromGitHub { + owner = "BurntSushi"; + repo = "ripgrep"; + rev = "${version}"; + sha256 = "0y5d1n6hkw85jb3rblcxqas2fp82h3nghssa4xqrhqnz25l799pj"; + }; + + depsSha256 = "0q68qyl2h6i0qsz82z840myxlnjay8p1w5z7hfyr8fqp7wgwa9cx"; + + meta = with stdenv.lib; { + description = "A utility that combines the usability of The Silver Searcher with the raw speed of grep"; + homepage = https://github.com/BurntSushi/ripgrep; + license = with licenses; [ unlicense ]; + maintainers = [ maintainers.tailhook ]; + platforms = platforms.all; + }; +} +``` + +`buildRustPackage` requires a `depsSha256` attribute which is computed over +all crate sources of this package. Currently it is obtained by inserting a +fake checksum into the expression and building the package once. The correct +checksum can be then take from the failed build. + +To install crates with nix there is also an experimental project called +[nixcrates](https://github.com/fractalide/nixcrates). + +## Using the Rust nightlies overlay + +Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope. +This overlay can _also_ be used to install recent unstable or stable versions +of Rust, if desired. + +To use this overlay, clone +[nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla), +and create a symbolic link to the file +[rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix) +in the `~/.config/nixpkgs/overlays` directory. + + $ git clone https://github.com/mozilla/nixpkgs-mozilla.git + $ mkdir -p ~/.config/nixpkgs/overlays + $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix + +The latest version can be installed with the following command: + + $ nix-env -Ai nixos.rustChannels.stable.rust + +Or using the attribute with nix-shell: + + $ nix-shell -p nixos.rustChannels.stable.rust + +To install the beta or nightly channel, "stable" should be substituted by +"nightly" or "beta", or +use the function provided by this overlay to pull a version based on a +build date. + +The overlay automatically updates itself as it uses the same source as +[rustup](https://www.rustup.rs/). diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.md new file mode 100644 index 000000000000..5442d706cb0b --- /dev/null +++ b/doc/languages-frameworks/vim.md @@ -0,0 +1,102 @@ +--- +title: User's Guide for Vim in Nixpkgs +author: Marc Weber +date: 2016-06-25 +--- +# User's Guide to Vim Plugins/Addons/Bundles/Scripts in Nixpkgs + +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. + +## dependencies by Vim plugins + +VAM introduced .json files supporting dependencies without versioning +assuming that "using latest version" is ok most of the time. + +## HOWTO + +First create a vim-scripts file having one plugin name per line. Example: + + "tlib" + {'name': 'vim-addon-sql'} + {'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']} + +Such vim-scripts file can be read by VAM as well like this: + + call vam#Scripts(expand('~/.vim-scripts'), {}) + +Create a default.nix file: + + { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }: + nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; } + +Create a generate.vim file: + + ActivateAddons vim-addon-vim2nix + let vim_scripts = "vim-scripts" + call nix#ExportPluginsForNix({ + \ 'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"], + \ 'cache_file': '/tmp/vim2nix-cache', + \ 'try_catch': 0, + \ 'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)') + \ }) + +Then run + + nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'" + +You should get a Vim buffer with the nix derivations (output1) and vam.pluginDictionaries (output2). +You can add your vim to your system's configuration file like this and start it by "vim-my": + + my-vim = + let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in { + copy paste output1 here + }; in vim_configurable.customize { + name = "vim-my"; + + vimrcConfig.vam.knownPlugins = plugins; # optional + vimrcConfig.vam.pluginDictionaries = [ + copy paste output2 here + ]; + + # Pathogen would be + # vimrcConfig.pathogen.knownPlugins = plugins; # plugins + # vimrcConfig.pathogen.pluginNames = ["tlib"]; + }; + + +Sample output1: + + "reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation + name = "reload"; + src = fetchgit { + url = "git://github.com/xolox/vim-reload"; + rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1"; + sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh"; + }; + dependencies = ["nim-misc"]; + + }; + [...] + +Sample output2: + + [ + ''vim-addon-manager'' + ''tlib'' + { "name" = ''vim-addon-sql''; } + { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; } + ] + + +## Important repositories + +- [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository + from VAM plugin manager meant to be used by others as well used by + +- [vim2nix](http://github.com/MarcWeber/vim-addon-vim2nix) which generates the + .nix code + diff --git a/doc/manual.xml b/doc/manual.xml index 1c0dac6e4df7..75bd21557fd1 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -13,6 +13,7 @@ <xi:include href="quick-start.xml" /> <xi:include href="stdenv.xml" /> <xi:include href="multiple-output.xml" /> + <xi:include href="cross-compilation.xml" /> <xi:include href="configuration.xml" /> <xi:include href="functions.xml" /> <xi:include href="meta.xml" /> diff --git a/doc/multiple-output.xml b/doc/multiple-output.xml index b7a363c750e6..a81ad6ca9eb4 100644 --- a/doc/multiple-output.xml +++ b/doc/multiple-output.xml @@ -16,7 +16,6 @@ <section><title>Installing a split package</title> <para>When installing a package via <varname>systemPackages</varname> or <command>nix-env</command> you have several options:</para> - <warning><para>Currently <command>nix-env</command> almost always installs all outputs until https://github.com/NixOS/nix/pull/815 gets merged.</para></warning> <itemizedlist> <listitem><para>You can install particular outputs explicitly, as each is available in the Nix language as an attribute of the package. The <varname>outputs</varname> attribute contains a list of output names.</para></listitem> <listitem><para>You can let it use the default outputs. These are handled by <varname>meta.outputsToInstall</varname> attribute that contains a list of output names.</para> diff --git a/doc/old/cross.txt b/doc/old/cross.txt index 82a69f6f3792..73103ea0c6d9 100644 --- a/doc/old/cross.txt +++ b/doc/old/cross.txt @@ -61,7 +61,7 @@ stdenv.mkDerivation { builder = ./builder.sh; src = fetchurl { url = http://ftp.nluug.nl/gnu/binutils/binutils-2.16.1.tar.bz2; - md5 = "6a9d529efb285071dad10e1f3d2b2967"; + sha256 = "1ian3kwh2vg6hr3ymrv48s04gijs539vzrq62xr76bxbhbwnz2np"; }; inherit noSysDirs; configureFlags = "--target=arm-linux"; @@ -81,11 +81,11 @@ Step 2: build kernel headers for the target architecture assert stdenv.system == "i686-linux"; stdenv.mkDerivation { - name = "linux-headers-2.6.13.4-arm"; + name = "linux-headers-2.6.13.1-arm"; builder = ./builder.sh; src = fetchurl { - url = http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.13.4.tar.bz2; - md5 = "94768d7eef90a9d8174639b2a7d3f58d"; + url = http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.13.1.tar.bz2; + sha256 = "12qxmc827fjhaz53kjy7vyrzsaqcg78amiqsb3qm20z26w705lma"; }; } --- @@ -152,9 +152,7 @@ stdenv.mkDerivation { builder = ./builder.sh; src = fetchurl { url = ftp://ftp.nluug.nl/pub/gnu/gcc/gcc-4.0.2/gcc-core-4.0.2.tar.bz2; - md5 = "f7781398ada62ba255486673e6274b26"; - #url = ftp://ftp.nluug.nl/pub/gnu/gcc/gcc-4.0.2/gcc-4.0.2.tar.bz2; - #md5 = "a659b8388cac9db2b13e056e574ceeb0"; + sha256 = "02fxh0asflm8825w23l2jq1wvs7hbnam0jayrivg7zdv2ifnc0rc"; }; # !!! apply only if noSysDirs is set patches = [./no-sys-dirs.patch ./gcc-inhibit.patch]; diff --git a/doc/overlays.xml b/doc/overlays.xml index cb54c33cf65f..4b95f3e72880 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -28,13 +28,13 @@ first one present is considered, and all the rest are ignored: <listitem> - <para>In the directory pointed by the environment variable - <varname>NIXPKGS_OVERLAYS</varname>.</para> + <para>In the directory pointed to by the Nix search path entry + <literal><nixpkgs-overlays></literal>.</para> </listitem> <listitem> - <para>In the directory <filename>~/.nixpkgs/overlays/</filename>.</para> + <para>In the directory <filename>~/.config/nixpkgs/overlays/</filename>.</para> </listitem> </orderedlist> @@ -50,7 +50,7 @@ the same recipe. In the case where overlays are loaded from a directory, they ar alphabetical order.</para> <para>To install an overlay using the last option, you can clone the overlay's repository and add -a symbolic link to it in <filename>~/.nixpkgs/overlays/</filename> directory.</para> +a symbolic link to it in <filename>~/.config/nixpkgs/overlays/</filename> directory.</para> </section> diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 0ba7ec4c44d4..0f148f5c898a 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -278,7 +278,7 @@ packageOverrides = pkgs: { </screen> to your Nixpkgs configuration - (<filename>~/.nixpkgs/config.nix</filename>) and install it by + (<filename>~/.config/nixpkgs/config.nix</filename>) and install it by running <command>nix-env -f '<nixpkgs>' -iA myEclipse</command> and afterward run Eclipse as usual. It is possible to find out which plugins are available for installation diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 44a0e4601fc1..a2530e102ca8 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -194,33 +194,52 @@ genericBuild tools.</para></listitem> </varlistentry> +</variablelist> + +<variablelist> + <title>Variables specifying dependencies</title> + + <varlistentry> + <term><varname>nativeBuildInputs</varname></term> + <listitem><para> + A list of dependencies used by the new derivation at <emphasis>build</emphasis>-time. + I.e. these dependencies should not make it into the package's runtime-closure, though this is currently not checked. + For each dependency <replaceable>dir</replaceable>, the directory <filename><replaceable>dir</replaceable>/bin</filename>, if it exists, is added to the <envar>PATH</envar> environment variable. + Other environment variables are also set up via a pluggable mechanism. + For instance, if <varname>buildInputs</varname> contains Perl, then the <filename>lib/site_perl</filename> subdirectory of each input is added to the <envar>PERL5LIB</envar> environment variable. + See <xref linkend="ssec-setup-hooks"/> for details. + </para></listitem> + </varlistentry> + <varlistentry> <term><varname>buildInputs</varname></term> - <listitem><para>A list of dependencies used by - <literal>stdenv</literal> to set up the environment for the build. - For each dependency <replaceable>dir</replaceable>, the directory - <filename><replaceable>dir</replaceable>/bin</filename>, if it - exists, is added to the <envar>PATH</envar> environment variable. - Other environment variables are also set up via a pluggable - mechanism. For instance, if <varname>buildInputs</varname> - contains Perl, then the <filename>lib/site_perl</filename> - subdirectory of each input is added to the <envar>PERL5LIB</envar> - environment variable. See <xref linkend="ssec-setup-hooks"/> for - details.</para></listitem> + <listitem><para> + A list of dependencies used by the new derivation at <emphasis>run</emphasis>-time. + Currently, the build-time environment is modified in the exact same way as with <varname>nativeBuildInputs</varname>. + This is problematic in that when cross-compiling, foreign executables can clobber native ones on the <envar>PATH</envar>. + Even more confusing is static-linking. + A statically-linked library should be listed here because ultimately that generated machine code will be used at run-time, even though a derivation containing the object files or static archives will only be used at build-time. + A less confusing solution to this would be nice. + </para></listitem> </varlistentry> - + + + <varlistentry> + <term><varname>propagatedNativeBuildInputs</varname></term> + <listitem><para> + Like <varname>nativeBuildInputs</varname>, but these dependencies are <emphasis>propagated</emphasis>: + that is, the dependencies listed here are added to the <varname>nativeBuildInputs</varname> of any package that uses <emphasis>this</emphasis> package as a dependency. + So if package Y has <literal>propagatedBuildInputs = [X]</literal>, and package Z has <literal>buildInputs = [Y]</literal>, then package X will appear in Z’s build environment automatically. + </para></listitem> + </varlistentry> + <varlistentry> <term><varname>propagatedBuildInputs</varname></term> - <listitem><para>Like <varname>buildInputs</varname>, but these - dependencies are <emphasis>propagated</emphasis>: that is, the - dependencies listed here are added to the - <varname>buildInputs</varname> of any package that uses - <emphasis>this</emphasis> package as a dependency. So if package - Y has <literal>propagatedBuildInputs = [X]</literal>, and package - Z has <literal>buildInputs = [Y]</literal>, then package X will - appear in Z’s build environment automatically.</para></listitem> + <listitem><para> + Like <varname>buildInputs</varname>, but propagated just like <varname>propagatedNativeBuildInputs</varname>. + This inherits <varname>buildInputs</varname>'s flaws of clobbering native executables when cross-compiling and being confusing for static linking. + </para></listitem> </varlistentry> - </variablelist> @@ -322,7 +341,7 @@ executed and in what order: $preInstallPhases installPhase fixupPhase $preDistPhases distPhase $postPhases</literal>. </para> - + <para>Usually, if you just want to add a few phases, it’s more convenient to set one of the variables below (such as <varname>preInstallPhases</varname>), as you then don’t specify @@ -706,7 +725,7 @@ makeFlagsArray=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar") </variablelist> -<para> +<para> You can set flags for <command>make</command> through the <varname>makeFlags</varname> variable.</para> @@ -773,7 +792,7 @@ doCheck = true;</programlisting> </variablelist> - + </section> @@ -840,12 +859,12 @@ install phase. The default <function>fixupPhase</function> does the following: <itemizedlist> - + <listitem><para>It moves the <filename>man/</filename>, <filename>doc/</filename> and <filename>info/</filename> subdirectories of <envar>$out</envar> to <filename>share/</filename>.</para></listitem> - + <listitem><para>It strips libraries and executables of debug information.</para></listitem> @@ -1091,13 +1110,41 @@ functions.</para> <variablelist> + + <varlistentry xml:id='fun-makeWrapper'> + <term><function>makeWrapper</function> + <replaceable>executable</replaceable> + <replaceable>wrapperfile</replaceable> + <replaceable>args</replaceable></term> + <listitem><para>Constructs a wrapper for a program with various + possible arguments. For example: + +<programlisting> +# adds `FOOBAR=baz` to `$out/bin/foo`’s environment +makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz + +# prefixes the binary paths of `hello` and `git` +# Be advised that paths often should be patched in directly +# (via string replacements or in `configurePhase`). +makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]} +</programlisting> + + There’s many more kinds of arguments, they are documented in + <literal>nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh</literal>.</para> + + <para><literal>wrapProgram</literal> is a convenience function you probably + want to use most of the time.</para> + + </listitem> + </varlistentry> + <varlistentry xml:id='fun-substitute'> <term><function>substitute</function> <replaceable>infile</replaceable> <replaceable>outfile</replaceable> <replaceable>subs</replaceable></term> - + <listitem> <para>Performs string substitution on the contents of <replaceable>infile</replaceable>, writing the result to @@ -1125,7 +1172,7 @@ functions.</para> <literal>@<replaceable>...</replaceable>@</literal> in the template as placeholders.</para></listitem> </varlistentry> - + <varlistentry> <term><option>--subst-var-by</option> <replaceable>varName</replaceable> @@ -1134,7 +1181,7 @@ functions.</para> <literal>@<replaceable>varName</replaceable>@</literal> by the string <replaceable>s</replaceable>.</para></listitem> </varlistentry> - + </variablelist> </para> @@ -1162,7 +1209,7 @@ substitute ./foo.in ./foo.out \ </listitem> </varlistentry> - + <varlistentry xml:id='fun-substituteInPlace'> <term><function>substituteInPlace</function> @@ -1173,7 +1220,7 @@ substitute ./foo.in ./foo.out \ <replaceable>file</replaceable>.</para></listitem> </varlistentry> - + <varlistentry xml:id='fun-substituteAll'> <term><function>substituteAll</function> <replaceable>infile</replaceable> @@ -1233,7 +1280,7 @@ echo @foo@ <listitem><para>Strips the directory and hash part of a store path, outputting the name part to <literal>stdout</literal>. For example: - + <programlisting> # prints coreutils-8.24 stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" @@ -1241,7 +1288,7 @@ stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" If you wish to store the result in another variable, then the following idiom may be useful: - + <programlisting> name="/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" someVar=$(stripHash $name) @@ -1249,8 +1296,24 @@ someVar=$(stripHash $name) </para></listitem> </varlistentry> - + + <varlistentry xml:id='fun-wrapProgram'> + <term><function>wrapProgram</function> + <replaceable>executable</replaceable> + <replaceable>makeWrapperArgs</replaceable></term> + <listitem><para>Convenience function for <literal>makeWrapper</literal> + that automatically creates a sane wrapper file + + It takes all the same arguments as <literal>makeWrapper</literal>, + except for <literal>--argv0</literal>.</para> + + <para>It cannot be applied multiple times, since it will overwrite the wrapper + file.</para> + </listitem> + </varlistentry> + + </variablelist> </section> @@ -1607,4 +1670,3 @@ Arch Wiki</link>. </section> </chapter> - |