Get rid of footnotes

Markdown doesn't support them.
This commit is contained in:
Eelco Dolstra 2020-07-24 11:43:44 +02:00
parent a71d1cedff
commit 8d0b311a1c
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
18 changed files with 79 additions and 110 deletions

View file

@ -106,7 +106,7 @@ input.</para>
<varlistentry><term><option>--find-file</option></term>
<listitem><para>Look up the given files in Nixs 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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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>

View file

@ -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>

View file

@ -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>&lt;nixpkgs&gt;</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>

View file

@ -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

View file

@ -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 dont 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 dont interfere with each other.
Here is what a part of a typical Nix store looks like:</para>
<mediaobject>
<imageobject>

View file

@ -82,11 +82,10 @@ See also [???](#sec-common-options) for a list of common options.
- `--find-file`
Look up the given files in Nixs 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

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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”).

View file

@ -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`.

View file

@ -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.

View file

@ -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 dont
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
dont interfere with each other. Here is what a part of a typical Nix
store looks like:
![](../figures/user-environments.png)
@ -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.