alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

nixpkgs/manual: address review comments

Browse source 
Mostly taken from requested changes exactly as recommended.
This commit is contained in:
Matthew Bauer 2019-01-27 11:57:36 -05:00
parent 498a242bf4
commit d7b62cb601
3 changed files with 90 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
doc/functions/fetchers.xml
View file

@ -6,8 +6,8 @@
<para>
When using Nix, you will frequently need to download source code
and other file from the internet. Nixpkgs comes with a few helper
functions that allow you to fetch fixed-output derivations in
and other files from the internet. Nixpkgs comes with a few helper
functions that allow you to fetch fixed-output derivations in a
structured way.
</para>
@ -48,7 +48,11 @@ stdenv.mkDerivation {
<para>
<function>fetchpatch</function> works very similarly to
<function>fetchurl</function> with the same arguments expected.
<function>fetchurl</function> with the same arguments expected. It
expects patch files as a source and and performs normalization on
them before computing the checksum. For example it will remove
comments or other unstable parts that are sometimes added by
version control systems and can change over time.
</para>
<para>
@ -80,6 +84,9 @@ stdenv.mkDerivation {
<para>
Used with Git. Expects <literal>url</literal> to a Git repo,
<literal>rev</literal>, and <literal>sha256</literal>.
<literal>rev</literal> in this case can be full the git commit
id (SHA1 hash) or a tag name like
<literal>refs/tags/v1.0</literal>.
</para>
</listitem>
</varlistentry>
@ -141,9 +148,10 @@ stdenv.mkDerivation {
GitHub HTML page as
<literal>owner</literal>/<literal>repo</literal>.
<literal>rev</literal> corresponds to the Git commit hash or
tag that will be downloaded from Git. Finally,
<literal>sha256</literal>. Again, other hash algorithms are
also available but <literal>sha256</literal> is currently
tag (e.g <literal>v1.0</literal>) that will be downloaded from
Git. Finally, <literal>sha256</literal> corresponds to the
hash of the extracted directory. Again, other hash algorithms
are also available but <literal>sha256</literal> is currently
preferred.
</para>
</listitem>

83
doc/functions/trivial-builders.xml
View file

@ -5,10 +5,10 @@
<title>Trivial builders</title>
<para>
There are a couple of functions provide in Nixpkgs that help with
building derivations. The most important one,
Nixpkgs provides a couple of functions that help with building
derivations. The most important one,
<function>stdenv.mkDerivation</function>, has already been
documented above. These wrap
documented above. The following functions wrap
<function>stdenv.mkDerivation</function>, making it easier to use
in certain cases.
</para>
@ -22,14 +22,42 @@
<para>
This takes three arguments, <literal>name</literal>,
<literal>env</literal>, and <literal>buildCommand</literal>.
<literal>name</literal> is just the name that Nix will use to
refer to the derivation. <literal>env</literal> is an attribute
set specifying environment variables that will be set for this
derivation. <literal>buildCommand</literal> specifies the
commands that will be run to create this derivation. Note that
you will need to create <literal>$out</literal> for Nix to
register the command as successful.
</para>
<literal>name</literal> is just the name that Nix will append
to the store path in the same way that
<literal>stdenv.mkDerivation</literal> uses its
<literal>name</literal> attribute. <literal>env</literal> is an
attribute set specifying environment variables that will be set
for this derivation. These attributes are then passed to the
wrapped <literal>stdenv.mkDerivation</literal>.
<literal>buildCommand</literal> specifies the commands that
will be run to create this derivation. Note that you will need
to create <literal>$out</literal> for Nix to register the
command as successful.
</para>
<para>
An example of using <literal>runCommand</literal> is provided
below.
</para>
<programlisting>
(import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''
echo My example command is running
mkdir $out
echo I can write data to the Nix store > $out/message
echo I can also run basic commands like:
echo ls
ls
echo whoami
whoami
echo date
date
''
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
@ -47,19 +75,30 @@
</varlistentry>
<varlistentry>
<term>
<literal>writeTextFile</literal>
<literal>writeTextFile</literal>, <literal>writeText</literal>,
<literal>writeTextDir</literal>, <literal>writeScript</literal>,
<literal>writeScriptBin</literal>
</term>
<listitem>
<para>
This writes <literal>text</literal> to the Nix store. This is
useful for creating scripts from Nix expressions. This takes an
attribute set and expects two arguments,
<literal>name</literal> and <literal>text</literal>.
<literal>name</literal> corresponds to the name used in the Nix
store path. <literal>text</literal> will be the contents of the
file. You can also set <literal>executable</literal> to true to
make this file have the executable bit set.
</para>
These functions write <literal>text</literal> to the Nix store.
This is useful for creating scripts from Nix expressions.
<literal>writeTextFile</literal> takes an attribute set and
expects two arguments, <literal>name</literal> and
<literal>text</literal>. <literal>name</literal> corresponds to
the name used in the Nix store path. <literal>text</literal>
will be the contents of the file. You can also set
<literal>executable</literal> to true to make this file have
the executable bit set.
</para>
<para>
Many more commands wrap <literal>writeTextFile</literal>
including <literal>writeText</literal>,
<literal>writeTextDir</literal>,
<literal>writeScript</literal>, and
<literal>writeScriptBin</literal>. These are convenience
functions over <literal>writeTextFile</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -75,7 +114,7 @@
<literal>name</literal> is the name used in the Nix store path
for the created derivation. <literal>paths</literal> is a list of
paths that will be symlinked. These paths can be to Nix store
derivations or any other directory.
derivations or any other subdirectory contained within.
</para>
</listitem>
</varlistentry>

28
doc/stdenv.xml
View file

@ -2207,7 +2207,8 @@ addEnvHooks "$hostOffset" myBashFunction
This setup hook moves any installed documentation to the
<literal>/share</literal> subdirectory directory. This includes
the man, doc and info directories. This is needed for legacy
programs that do not know use the share subdirectory.
programs that do not know how to use the
<literal>share</literal> subdirectory.
</para>
</listitem>
</varlistentry>
@ -2219,7 +2220,7 @@ addEnvHooks "$hostOffset" myBashFunction
<para>
This setup hook compresses any man pages that have been
installed. The compression is done using the gzip program. This
helps to reduce installed size of packages.
helps to reduce the installed size of packages.
</para>
</listitem>
</varlistentry>
@ -2230,9 +2231,9 @@ addEnvHooks "$hostOffset" myBashFunction
<listitem>
<para>
This runs the strip command on installed binaries and
libraries. This removed things like debug symbols when they are
not needed. This also helps to reduce installed size of
packages.
libraries. This removes unnecessary information like debug
symbols when they are not needed. This also helps to reduce the
installed size of packages.
</para>
</listitem>
</varlistentry>
@ -2244,10 +2245,11 @@ addEnvHooks "$hostOffset" myBashFunction
<para>
This setup hook patches installed scripts to use the full path
to the shebang interpreter. A shebang interpreter is the first
commented line of a script telling the operating system
what to use to run this script. In Nix, we want an exact path
to that interpreter to be used. This often replcaes
<literal>/bin/sh</literal> with a path in the Nix store.
commented line of a script telling the operating system which
program will run the script (e.g <literal>#!/bin/bash</literal>). In
Nix, we want an exact path to that interpreter to be used. This
often replaces <literal>/bin/sh</literal> with a path in the
Nix store.
</para>
</listitem>
</varlistentry>
@ -2260,7 +2262,7 @@ addEnvHooks "$hostOffset" myBashFunction
This verifies that no references are left from the install
binaries to the directory used to build those binaries. This
ensures that the binaries do not need things outside the Nix
store. This currently Linux only.
store. This is currently supported in Linux only.
</para>
</listitem>
</varlistentry>
@ -2425,9 +2427,9 @@ addEnvHooks "$hostOffset" myBashFunction
<para>
Here are some more packages that provide a setup hook. Since the
mechanism is modular, this probably isn't an exhaustive list. Then
again, since the mechanism is only to be used as a last resort, it
might be.
list of hooks is extensible, this is not an exhaustive list the
mechanism is only to be used as a last resort, it might cover most
uses.
<variablelist>
<varlistentry>
<term>