Get rid of footnotes
Markdown doesn't support them.
This commit is contained in:
Eelco Dolstra
parent
a71d1cedff
commit
8d0b311a1c
|
|
@ -106,7 +106,7 @@ input.</para>
|
|||
<varlistentry><term><option>--find-file</option></term>
|
||||
|
||||
<listitem><para>Look up the given files in Nix’s search path (as
|
||||
specified by the <envar linkend="env-NIX_PATH">NIX_PATH</literal>
|
||||
specified by the <literal linkend="env-NIX_PATH">NIX_PATH</literal>
|
||||
environment variable). If found, print the corresponding absolute
|
||||
paths on standard output. For instance, if
|
||||
<literal>NIX_PATH</literal> is
|
||||
|
|
|
|||
|
|
@ -369,7 +369,7 @@
|
|||
<varlistentry xml:id="opt-I"><term><option>-I</option> <emphasis>path</emphasis></term>
|
||||
|
||||
<listitem><para>Add a path to the Nix expression search path. This
|
||||
option may be given multiple times. See the <envar
|
||||
option may be given multiple times. See the <literal
|
||||
linkend="env-NIX_PATH">NIX_PATH</literal> environment variable for
|
||||
information on the semantics of the Nix search path. Paths added
|
||||
through <option>-I</option> take precedence over
|
||||
|
|
|
|||
|
|
@ -33,13 +33,10 @@ steps:</para>
|
|||
|
||||
<para>When Nix runs a builder, it initially completely clears the
|
||||
environment (except for the attributes declared in the
|
||||
derivation). For instance, the <literal>PATH</literal> variable is
|
||||
empty<footnote><para>Actually, it's initialised to
|
||||
<filename>/path-not-set</filename> to prevent Bash from setting it
|
||||
to a default value.</para></footnote>. This is done to prevent
|
||||
undeclared inputs from being used in the build process. If for
|
||||
example the <literal>PATH</literal> contained
|
||||
<filename>/usr/bin</filename>, then you might accidentally use
|
||||
derivation). This is done to prevent undeclared inputs from being
|
||||
used in the build process. If for example the
|
||||
<literal>PATH</literal> contained <filename>/usr/bin</filename>,
|
||||
then you might accidentally use
|
||||
<filename>/usr/bin/gcc</filename>.</para>
|
||||
|
||||
<para>So the first step is to set up the environment. This is
|
||||
|
|
|
|||
|
|
@ -13,16 +13,15 @@ of which specify the inputs of the build.</para>
|
|||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem xml:id="attr-system"><para>There must be an attribute named
|
||||
<varname>system</varname> whose value must be a string specifying a
|
||||
Nix platform identifier, such as <literal>"i686-linux"</literal> or
|
||||
<literal>"x86_64-darwin"</literal><footnote><para>To figure out
|
||||
your platform identifier, look at the line <quote>Checking for the
|
||||
canonical Nix system name</quote> in the output of Nix's
|
||||
<filename>configure</filename> script.</para></footnote> The build
|
||||
can only be performed on a machine and operating system matching the
|
||||
platform identifier. (Nix can automatically forward builds for
|
||||
other platforms by forwarding them to other machines; see <xref
|
||||
<listitem xml:id="attr-system"><para>There must be an attribute
|
||||
named <varname>system</varname> whose value must be a string
|
||||
specifying a Nix system type, such as
|
||||
<literal>"i686-linux"</literal> or
|
||||
<literal>"x86_64-darwin"</literal>. (To figure out your system type,
|
||||
run <literal>nix -vv --version</literal>.) The build can only be
|
||||
performed on a machine and operating system matching the system
|
||||
type. (Nix can automatically forward builds for other platforms by
|
||||
forwarding them to other machines; see <xref
|
||||
linkend='chap-distributed-builds' />.)</para></listitem>
|
||||
|
||||
<listitem><para>There must be an attribute named
|
||||
|
|
|
|||
|
|
@ -42,14 +42,14 @@ genericBuild ③</programlisting>
|
|||
<filename>bin</filename> subdirectory, it's added to
|
||||
<literal>PATH</literal>; if it has a <filename>include</filename>
|
||||
subdirectory, it's added to GCC's header search path; and so
|
||||
on.<footnote><para>How does it work? <filename>setup</filename>
|
||||
tries to source the file
|
||||
on. (This is implemented in a modular way:
|
||||
<filename>setup</filename> tries to source the file
|
||||
<filename><emphasis>pkg</emphasis>/nix-support/setup-hook</filename>
|
||||
of all dependencies. These “setup hooks” can then set up whatever
|
||||
environment variables they want; for instance, the setup hook for
|
||||
Perl sets the <literal>PERL5LIB</literal> environment variable to
|
||||
contain the <filename>lib/site_perl</filename> directories of all
|
||||
inputs.</para></footnote>
|
||||
inputs.)
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ is, in a normal (non-recursive) set, attributes are not added to the
|
|||
lexical scope; in a recursive set, they are.</para>
|
||||
|
||||
<para>Recursive sets of course introduce the danger of infinite
|
||||
recursion. For example,
|
||||
recursion. For example, the expression
|
||||
|
||||
<programlisting>
|
||||
rec {
|
||||
|
|
@ -34,9 +34,8 @@ rec {
|
|||
y = x;
|
||||
}.x</programlisting>
|
||||
|
||||
does not terminate<footnote><para>Actually, Nix detects infinite
|
||||
recursion in this case and aborts (<quote>infinite recursion
|
||||
encountered</quote>).</para></footnote>.</para>
|
||||
will crash with an <literal>infinite recursion encountered</literal>
|
||||
error message.</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
|
|
|||
|
|
@ -154,11 +154,10 @@ stdenv.mkDerivation {
|
|||
|
||||
<listitem><para><emphasis>Paths</emphasis>, e.g.,
|
||||
<filename>/bin/sh</filename> or <filename>./builder.sh</filename>.
|
||||
A path must contain at least one slash to be recognised as such; for
|
||||
instance, <filename>builder.sh</filename> is not a
|
||||
path<footnote><para>It's parsed as an expression that selects the
|
||||
attribute <varname>sh</varname> from the variable
|
||||
<varname>builder</varname>.</para></footnote>. If the file name is
|
||||
A path must contain at least one slash to be recognised as such. For
|
||||
instance, <filename>builder.sh</filename> is not a path: it's parsed
|
||||
as an expression that selects the attribute <varname>sh</varname>
|
||||
from the variable <varname>builder</varname>. If the file name is
|
||||
relative, i.e., if it does not begin with a slash, it is made
|
||||
absolute at parse time relative to the directory of the Nix
|
||||
expression that contained it. For instance, if a Nix expression in
|
||||
|
|
@ -176,7 +175,7 @@ stdenv.mkDerivation {
|
|||
<para>Paths can also be specified between angle brackets, e.g.
|
||||
<literal><nixpkgs></literal>. This means that the directories
|
||||
listed in the environment variable
|
||||
<envar linkend="env-NIX_PATH">NIX_PATH</literal> will be searched
|
||||
<literal linkend="env-NIX_PATH">NIX_PATH</literal> will be searched
|
||||
for the given file or directory name.
|
||||
</para>
|
||||
|
||||
|
|
|
|||
|
|
@ -21,10 +21,9 @@ need to do three things:
|
|||
such as dependencies, sources, and so on.</para></listitem>
|
||||
|
||||
<listitem><para>Write a <emphasis>builder</emphasis>. This is a
|
||||
shell script<footnote><para>In fact, it can be written in any
|
||||
language, but typically it's a <command>bash</command> shell
|
||||
script.</para></footnote> that actually builds the package from
|
||||
the inputs.</para></listitem>
|
||||
shell script that builds the package from the inputs. (In fact, it
|
||||
can be written in any language, but typically it's a
|
||||
<command>bash</command> shell script.)</para></listitem>
|
||||
|
||||
<listitem><para>Add the package to the file
|
||||
<filename>pkgs/top-level/all-packages.nix</filename>. The Nix
|
||||
|
|
|
|||
|
|
@ -18,13 +18,12 @@ of the Subversion package might be stored in a directory
|
|||
while another version might be stored in
|
||||
<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>.
|
||||
The long strings prefixed to the directory names are cryptographic
|
||||
hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in
|
||||
a base-32 notation, to be precise.</para></footnote> of
|
||||
<emphasis>all</emphasis> inputs involved in building the package —
|
||||
sources, dependencies, compiler flags, and so on. So if two packages
|
||||
differ in any way, they end up in different locations in the file
|
||||
system, so they don’t interfere with each other. Here is what a part
|
||||
of a typical Nix store looks like:</para>
|
||||
hashes (to be precise, 160-bit truncations of SHA-256 hashes encoded
|
||||
in a base-32 notation) of <emphasis>all</emphasis> inputs involved in
|
||||
building the package — sources, dependencies, compiler flags, and so
|
||||
on. So if two packages differ in any way, they end up in different
|
||||
locations in the file system, so they don’t interfere with each other.
|
||||
Here is what a part of a typical Nix store looks like:</para>
|
||||
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
|
|
|
|||
|
|
@ -82,11 +82,10 @@ See also [???](#sec-common-options) for a list of common options.
|
|||
|
||||
- `--find-file`
|
||||
Look up the given files in Nix’s search path (as specified by the
|
||||
NIX\_PATH\</literal\> environment variable). If found, print the
|
||||
corresponding absolute paths on standard output. For instance, if
|
||||
`NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate
|
||||
--find-file nixpkgs/default.nix` will print
|
||||
`/home/alice/nixpkgs/default.nix`.
|
||||
`NIX_PATH` environment variable). If found, print the corresponding
|
||||
absolute paths on standard output. For instance, if `NIX_PATH` is
|
||||
`nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file
|
||||
nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`.
|
||||
|
||||
- `--strict`
|
||||
When used with `--eval`, recursively evaluate list elements and
|
||||
|
|
|
|||
|
|
@ -206,9 +206,9 @@ Most Nix commands accept the following command-line options:
|
|||
|
||||
- `-I` *path*
|
||||
Add a path to the Nix expression search path. This option may be
|
||||
given multiple times. See the NIX\_PATH\</literal\> environment
|
||||
variable for information on the semantics of the Nix search path.
|
||||
Paths added through `-I` take precedence over `NIX_PATH`.
|
||||
given multiple times. See the `NIX_PATH` environment variable for
|
||||
information on the semantics of the Nix search path. Paths added
|
||||
through `-I` take precedence over `NIX_PATH`.
|
||||
|
||||
- `--option` *name* *value*
|
||||
Set the Nix configuration option *name* to *value*. This overrides
|
||||
|
|
|
|||
|
|
@ -19,10 +19,9 @@ steps to elucidate what a builder does. It performs the following steps:
|
|||
|
||||
1. When Nix runs a builder, it initially completely clears the
|
||||
environment (except for the attributes declared in the derivation).
|
||||
For instance, the `PATH` variable is empty\[1\]. This is done to
|
||||
prevent undeclared inputs from being used in the build process. If
|
||||
for example the `PATH` contained `/usr/bin`, then you might
|
||||
accidentally use `/usr/bin/gcc`.
|
||||
This is done to prevent undeclared inputs from being used in the
|
||||
build process. If for example the `PATH` contained `/usr/bin`, then
|
||||
you might accidentally use `/usr/bin/gcc`.
|
||||
|
||||
So the first step is to set up the environment. This is done by
|
||||
calling the `setup` script of the standard environment. The
|
||||
|
|
@ -67,6 +66,3 @@ If you are wondering about the absence of error checking on the result
|
|||
of various commands called in the builder: this is because the shell
|
||||
script is evaluated with Bash's `-e` option, which causes the script to
|
||||
be aborted if any command fails without an error check.
|
||||
|
||||
1. Actually, it's initialised to `/path-not-set` to prevent Bash from
|
||||
setting it to a default value.
|
||||
|
|
|
|||
|
|
@ -5,11 +5,12 @@ describe a single derivation (a build action). It takes as input a set,
|
|||
the attributes of which specify the inputs of the build.
|
||||
|
||||
- There must be an attribute named `system` whose value must be a
|
||||
string specifying a Nix platform identifier, such as `"i686-linux"`
|
||||
or `"x86_64-darwin"`\[1\] The build can only be performed on a
|
||||
machine and operating system matching the platform identifier. (Nix
|
||||
can automatically forward builds for other platforms by forwarding
|
||||
them to other machines; see [???](#chap-distributed-builds).)
|
||||
string specifying a Nix system type, such as `"i686-linux"` or
|
||||
`"x86_64-darwin"`. (To figure out your system type, run `nix -vv
|
||||
--version`.) The build can only be performed on a machine and
|
||||
operating system matching the system type. (Nix can automatically
|
||||
forward builds for other platforms by forwarding them to other
|
||||
machines; see [???](#chap-distributed-builds).)
|
||||
|
||||
- There must be an attribute named `name` whose value must be a
|
||||
string. This is used as a symbolic name for the package by
|
||||
|
|
@ -146,9 +147,3 @@ The builder is executed as follows:
|
|||
supported by Nix. This is because the Nix archives used in
|
||||
deployment have no concept of ownership information, and because it
|
||||
makes the build result dependent on the user performing the build.
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
1. To figure out your platform identifier, look at the line “Checking
|
||||
for the canonical Nix system name” in the output of Nix's
|
||||
`configure` script.
|
||||
|
|
|
|||
|
|
@ -27,8 +27,12 @@ Here is what each line means:
|
|||
1. The `buildInputs` variable tells `setup` to use the indicated
|
||||
packages as “inputs”. This means that if a package provides a `bin`
|
||||
subdirectory, it's added to `PATH`; if it has a `include`
|
||||
subdirectory, it's added to GCC's header search path; and so
|
||||
on.\[1\]
|
||||
subdirectory, it's added to GCC's header search path; and so on.
|
||||
(This is implemented in a modular way: `setup` tries to source the
|
||||
file `pkg/nix-support/setup-hook` of all dependencies. These “setup
|
||||
hooks” can then set up whatever environment variables they want; for
|
||||
instance, the setup hook for Perl sets the `PERL5LIB` environment
|
||||
variable to contain the `lib/site_perl` directories of all inputs.)
|
||||
|
||||
2. The function `genericBuild` is defined in the file `$stdenv/setup`.
|
||||
|
||||
|
|
@ -55,10 +59,3 @@ shorter:
|
|||
In fact, `mkDerivation` provides a default builder that looks exactly
|
||||
like that, so it is actually possible to omit the builder for Hello
|
||||
entirely.
|
||||
|
||||
1. How does it work? `setup` tries to source the file
|
||||
`pkg/nix-support/setup-hook` of all dependencies. These “setup
|
||||
hooks” can then set up whatever environment variables they want;
|
||||
for instance, the setup hook for Perl sets the `PERL5LIB`
|
||||
environment variable to contain the `lib/site_perl` directories of
|
||||
all inputs.
|
||||
|
|
|
|||
|
|
@ -17,14 +17,14 @@ would be invalid if no such variable exists. That is, in a normal
|
|||
recursive set, they are.
|
||||
|
||||
Recursive sets of course introduce the danger of infinite recursion. For
|
||||
example,
|
||||
example, the expression
|
||||
|
||||
rec {
|
||||
x = y;
|
||||
y = x;
|
||||
}.x
|
||||
|
||||
does not terminate\[1\].
|
||||
will crash with an `infinite recursion encountered` error message.
|
||||
|
||||
## Let-expressions
|
||||
|
||||
|
|
@ -304,6 +304,3 @@ establishes the same scope as
|
|||
Comments can be single-line, started with a `#` character, or
|
||||
inline/multi-line, enclosed within `/*
|
||||
... */`.
|
||||
|
||||
1. Actually, Nix detects infinite recursion in this case and aborts
|
||||
(“infinite recursion encountered”).
|
||||
|
|
|
|||
|
|
@ -108,12 +108,14 @@ Nix has the following basic data types:
|
|||
floating point number will have a floating point number as a result.
|
||||
|
||||
- *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
|
||||
least one slash to be recognised as such; for instance, `builder.sh`
|
||||
is not a path\[1\]. If the file name is relative, i.e., if it does
|
||||
not begin with a slash, it is made absolute at parse time relative
|
||||
to the directory of the Nix expression that contained it. For
|
||||
instance, if a Nix expression in `/foo/bar/bla.nix` refers to
|
||||
`../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`.
|
||||
least one slash to be recognised as such. For instance, `builder.sh`
|
||||
is not a path: it's parsed as an expression that selects the
|
||||
attribute `sh` from the variable `builder`. If the file name is
|
||||
relative, i.e., if it does not begin with a slash, it is made
|
||||
absolute at parse time relative to the directory of the Nix
|
||||
expression that contained it. For instance, if a Nix expression in
|
||||
`/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
|
||||
is `/foo/xyzzy/fnord.nix`.
|
||||
|
||||
If the first component of a path is a `~`, it is interpreted as if
|
||||
the rest of the path were relative to the user's home directory.
|
||||
|
|
@ -122,8 +124,8 @@ Nix has the following basic data types:
|
|||
|
||||
Paths can also be specified between angle brackets, e.g.
|
||||
`<nixpkgs>`. This means that the directories listed in the
|
||||
environment variable NIX\_PATH\</literal\> will be searched for the
|
||||
given file or directory name.
|
||||
environment variable `NIX_PATH` will be searched for the given file
|
||||
or directory name.
|
||||
|
||||
- *Booleans* with values `true` and `false`.
|
||||
|
||||
|
|
@ -210,6 +212,3 @@ passed in first , e.g.,
|
|||
evaluates to `2`. This can be used to attach metadata to a function
|
||||
without the caller needing to treat it specially, or to implement a form
|
||||
of object-oriented programming, for example.
|
||||
|
||||
1. It's parsed as an expression that selects the attribute `sh` from
|
||||
the variable `builder`.
|
||||
|
|
|
|||
|
|
@ -12,16 +12,12 @@ do three things:
|
|||
describes all the inputs involved in building the package, such as
|
||||
dependencies, sources, and so on.
|
||||
|
||||
2. Write a *builder*. This is a shell script\[1\] that actually builds
|
||||
the package from the inputs.
|
||||
2. Write a *builder*. This is a shell script that builds the package
|
||||
from the inputs. (In fact, it can be written in any language, but
|
||||
typically it's a `bash` shell script.)
|
||||
|
||||
3. Add the package to the file `pkgs/top-level/all-packages.nix`. The
|
||||
Nix expression written in the first step is a *function*; it
|
||||
requires other packages in order to build it. In this step you put
|
||||
it all together, i.e., you call the function with the right
|
||||
arguments to build the actual package.
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
1. In fact, it can be written in any language, but typically it's a
|
||||
`bash` shell script.
|
||||
|
|
|
|||
|
|
@ -10,12 +10,13 @@ in a directory
|
|||
`/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while
|
||||
another version might be stored in
|
||||
`/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long
|
||||
strings prefixed to the directory names are cryptographic hashes\[1\] of
|
||||
*all* inputs involved in building the package — sources, dependencies,
|
||||
compiler flags, and so on. So if two packages differ in any way, they
|
||||
end up in different locations in the file system, so they don’t
|
||||
interfere with each other. Here is what a part of a typical Nix store
|
||||
looks like:
|
||||
strings prefixed to the directory names are cryptographic hashes (to be
|
||||
precise, 160-bit truncations of SHA-256 hashes encoded in a base-32
|
||||
notation) of *all* inputs involved in building the package — sources,
|
||||
dependencies, compiler flags, and so on. So if two packages differ in
|
||||
any way, they end up in different locations in the file system, so they
|
||||
don’t interfere with each other. Here is what a part of a typical Nix
|
||||
store looks like:
|
||||
|
||||
|
||||
|
||||
|
|
@ -113,6 +114,3 @@ All `nix-env` operations work on the profile pointed to by
|
|||
$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion
|
||||
|
||||
This will *not* change the `~/.nix-profile` symlink.
|
||||
|
||||
1. 160-bit truncations of SHA-256 hashes encoded in a base-32 notation,
|
||||
to be precise.
|
||||
|
|
|
|||
Loading…
Reference in a new issue