diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/default.nix | 6 | ||||
| -rw-r--r-- | doc/functions.xml | 75 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.md | 40 | ||||
| -rw-r--r-- | doc/languages-frameworks/texlive.xml | 1 | ||||
| -rw-r--r-- | doc/multiple-output.xml | 33 | ||||
| -rw-r--r-- | doc/stdenv.xml | 11 |
6 files changed, 121 insertions, 45 deletions
diff --git a/doc/default.nix b/doc/default.nix index 03134cf4cc86..625c716b0319 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -97,7 +97,9 @@ pkgs.stdenv.mkDerivation { cp -r $dst/images $dst/epub/OEBPS echo "application/epub+zip" > mimetype - zip -0Xq "$dst/Nixpkgs Contributors Guide - NixOS community.epub" mimetype - zip -Xr9D "$dst/Nixpkgs Contributors Guide - NixOS community.epub" $dst/epub/* + manual="$dst/nixpkgs-manual.epub" + zip -0Xq "$manual" mimetype + cd $dst/epub && zip -Xr9D "$manual" * + rm -rf $dst/epub ''; } diff --git a/doc/functions.xml b/doc/functions.xml index 908e9571ed69..3850e58c0168 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -52,6 +52,20 @@ in ...</programlisting> It's equivalent to <varname>pkgs</varname> in the above example. </para> + <para> + Note that in previous versions of nixpkgs, this method replaced any changes from <link + linkend="sec-modify-via-packageOverrides">config.packageOverrides</link>, + along with that from previous calls if this function was called repeatedly. + Now those previous changes will be preserved so this function can be "chained" meaningfully. + To recover the old behavior, make sure <varname>config.packageOverrides</varname> is unset, + and call this only once off a "freshly" imported nixpkgs: + + <programlisting>let + pkgs = import <nixpkgs> { config: {}; }; + newpkgs = pkgs.overridePackages ...; +in ...</programlisting> + </para> + </section> <section xml:id="sec-pkg-override"> @@ -85,10 +99,71 @@ in ...</programlisting> </section> +<section xml:id="sec-pkg-overrideAttrs"> + <title><pkg>.overrideAttrs</title> + + <para> + The function <varname>overrideAttrs</varname> allows overriding the + attribute set passed to a <varname>stdenv.mkDerivation</varname> call, + producing a new derivation based on the original one. + This function is available on all derivations produced by the + <varname>stdenv.mkDerivation</varname> function, which is most packages + in the nixpkgs expression <varname>pkgs</varname>. + </para> + + <para> + Example usage: + + <programlisting>helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { + separateDebugInfo = true; +});</programlisting> + </para> + + <para> + In the above example, the <varname>separateDebugInfo</varname> attribute is + overriden to be true, thus building debug info for + <varname>helloWithDebug</varname>, while all other attributes will be + retained from the original <varname>hello</varname> package. + </para> + + <para> + The argument <varname>oldAttrs</varname> is conventionally used to refer to + the attr set originally passed to <varname>stdenv.mkDerivation</varname>. + </para> + + <note> + <para> + Note that <varname>separateDebugInfo</varname> is processed only by the + <varname>stdenv.mkDerivation</varname> function, not the generated, raw + Nix derivation. Thus, using <varname>overrideDerivation</varname> will + not work in this case, as it overrides only the attributes of the final + derivation. It is for this reason that <varname>overrideAttrs</varname> + should be preferred in (almost) all cases to + <varname>overrideDerivation</varname>, i.e. to allow using + <varname>sdenv.mkDerivation</varname> to process input arguments, as well + as the fact that it is easier to use (you can use the same attribute + names you see in your Nix code, instead of the ones generated (e.g. + <varname>buildInputs</varname> vs <varname>nativeBuildInputs</varname>, + and involves less typing. + </para> + </note> + +</section> + + <section xml:id="sec-pkg-overrideDerivation"> <title><pkg>.overrideDerivation</title> <warning> + <para>You should prefer <varname>overrideAttrs</varname> in almost all + cases, see its documentation for the reasons why. + <varname>overrideDerivation</varname> is not deprecated and will continue + to work, but is less nice to use and does not have as many abilities as + <varname>overrideAttrs</varname>. + </para> + </warning> + + <warning> <para>Do not use this function in Nixpkgs as it evaluates a Derivation before modifying it, which breaks package abstraction and removes error-checking of function arguments. In addition, this diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md index e7dbe3bd7db0..127614a71b75 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 2.7. +packages. The default interpreter is CPython 3.5. ### Using Python @@ -409,36 +409,21 @@ 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 on -Nix and are available as `python26`, `python27`, `python33`, `python34` and -`python35`. The PyPy interpreter is also available as `pypy`. Currently, the -aliases `python` and `python3` correspond to respectively `python27` and -`python35`. The Nix expressions for the interpreters can be found in +Versions 2.6, 2.7, 3.3, 3.4 and 3.5 of the CPython interpreter are as respectively +`python26`, `python27`, `python33`, `python34` and `python35`. The PyPy interpreter +is available as `pypy`. The aliases `python2` and `python3` correspond to respectively `python27` and +`python35`. The default interpreter, `python`, maps to `python3`. +The Nix expressions for the interpreters can be found in `pkgs/development/interpreters/python`. - -#### Missing modules standard library - -The interpreters `python26` and `python27` do not include modules that -require external dependencies. This is done in order to reduce the closure size. -The following modules need to be added as `buildInput` explicitly: - -* `python.modules.bsddb` -* `python.modules.curses` -* `python.modules.curses_panel` -* `python.modules.crypt` -* `python.modules.gdbm` -* `python.modules.sqlite3` -* `python.modules.tkinter` -* `python.modules.readline` - -For convenience `python27Full` and `python26Full` are provided with all -modules included. - All packages depending on any Python interpreter get appended `out/{python.sitePackages}` to `$PYTHONPATH` if such directory exists. +#### Missing `tkinter` module standard library + +To reduce closure size the `Tkinter`/`tkinter` is available as a separate package, `pythonPackages.tkinter`. + #### Attributes on interpreters packages Each interpreter has the following attributes: @@ -448,7 +433,7 @@ Each interpreter has the following attributes: - `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation. - `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation. - `sitePackages`. Alias for `lib/${libPrefix}/site-packages`. -- `executable`. Name of the interpreter executable, ie `python3.4`. +- `executable`. Name of the interpreter executable, e.g. `python3.4`. ### Building packages and applications @@ -475,8 +460,9 @@ sets are and the aliases -* `pkgs.pythonPackages` pointing to `pkgs.python27Packages` +* `pkgs.python2Packages` pointing to `pkgs.python27Packages` * `pkgs.python3Packages` pointing to `pkgs.python35Packages` +* `pkgs.pythonPackages` pointing to `pkgs.python3Packages` #### `buildPythonPackage` function diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml index 0e3c1dd13d72..fdee1e405ecc 100644 --- a/doc/languages-frameworks/texlive.xml +++ b/doc/languages-frameworks/texlive.xml @@ -35,6 +35,7 @@ texlive.combine { You can list packages e.g. by <command>nix-repl</command>. <programlisting> $ nix-repl +nix-repl> :l <nixpkgs> nix-repl> texlive.collection-<TAB> </programlisting> </para></listitem> diff --git a/doc/multiple-output.xml b/doc/multiple-output.xml index 0bbb9ef8be3a..b7a363c750e6 100644 --- a/doc/multiple-output.xml +++ b/doc/multiple-output.xml @@ -45,34 +45,48 @@ <title>File type groups</title> <para>The support code currently recognizes some particular kinds of outputs and either instructs the build system of the package to put files into their desired outputs or it moves the files during the fixup phase. Each group of file types has an <varname>outputFoo</varname> variable specifying the output name where they should go. If that variable isn't defined by the derivation writer, it is guessed – a default output name is defined, falling back to other possibilities if the output isn't defined.</para> <variablelist> + <varlistentry><term><varname> $outputDev</varname></term><listitem><para> is for development-only files. These include C(++) headers, pkg-config, cmake and aclocal files. They go to <varname>dev</varname> or <varname>out</varname> by default. - </para></listitem></varlistentry> + </para></listitem> + </varlistentry> + <varlistentry><term><varname> $outputBin</varname></term><listitem><para> is meant for user-facing binaries, typically residing in bin/. They go to <varname>bin</varname> or <varname>out</varname> by default. - </para></listitem></varlistentry> + </para></listitem></varlistentry> + <varlistentry><term><varname> $outputLib</varname></term><listitem><para> is meant for libraries, typically residing in <filename>lib/</filename> and <filename>libexec/</filename>. They go to <varname>lib</varname> or <varname>out</varname> by default. - </para></listitem></varlistentry> + </para></listitem></varlistentry> + <varlistentry><term><varname> $outputDoc</varname></term><listitem><para> is for user documentation, typically residing in <filename>share/doc/</filename>. It goes to <varname>doc</varname> or <varname>out</varname> by default. - </para></listitem></varlistentry> + </para></listitem></varlistentry> + <varlistentry><term><varname> - $outputDocdev</varname></term><listitem><para> - is for <emphasis>developer</emphasis> documentation. Currently we count gtk-doc and man3 pages in there. It goes to <varname>devdoc</varname> or is removed (!) by default. This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users. - </para></listitem></varlistentry> + $outputDevdoc</varname></term><listitem><para> + is for <emphasis>developer</emphasis> documentation. Currently we count gtk-doc in there. It goes to <varname>devdoc</varname> or is removed (!) by default. This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users. + </para></listitem></varlistentry> + <varlistentry><term><varname> $outputMan</varname></term><listitem><para> is for man pages (except for section 3). They go to <varname>man</varname> or <varname>doc</varname> or <varname>$outputBin</varname> by default. - </para></listitem></varlistentry> + </para></listitem></varlistentry> + + <varlistentry><term><varname> + $outputDevman</varname></term><listitem><para> + is for section 3 man pages. They go to <varname>devman</varname> or <varname>$outputMan</varname> by default. + </para></listitem></varlistentry> + <varlistentry><term><varname> $outputInfo</varname></term><listitem><para> is for info pages. They go to <varname>info</varname> or <varname>doc</varname> or <varname>$outputMan</varname> by default. - </para></listitem></varlistentry> + </para></listitem></varlistentry> + </variablelist> </section> @@ -88,4 +102,3 @@ </section><!--Writing a split derivation--> </chapter> - diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 3da3dd8df96e..68441ea9393a 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -27,7 +27,7 @@ stdenv.mkDerivation { name = "libfoo-1.2.3"; src = fetchurl { url = http://example.org/libfoo-1.2.3.tar.bz2; - md5 = "e1ec107956b6ddcb0b8b0679367e9ac9"; + sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m"; }; }</programlisting> @@ -1231,13 +1231,12 @@ echo @foo@ <term><function>stripHash</function> <replaceable>path</replaceable></term> <listitem><para>Strips the directory and hash part of a store - path, storing the name part in the environment variable - <literal>strippedName</literal>. For example: + path, outputting the name part to <literal>stdout</literal>. + For example: <programlisting> -stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" # prints coreutils-8.24 -echo $strippedName +stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" </programlisting> If you wish to store the result in another variable, then the @@ -1245,7 +1244,7 @@ echo $strippedName <programlisting> name="/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" -someVar=$(stripHash $name; echo $strippedName) +someVar=$(stripHash $name) </programlisting> </para></listitem> |