maurice/snix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add 'third_party/nix/' from commit 'be66c7a6b24e3c3c6157fd37b86c7203d14acf10'

Browse source 
git-subtree-dir: third_party/nix
git-subtree-mainline: cf8cd640c1
git-subtree-split: be66c7a6b24e3c3c6157fd37b86c7203d14acf10
This commit is contained in:
Vincent Ambo 2020-05-17 15:52:38 +01:00
commit 7994fd1d54
737 changed files with 105390 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

268
third_party/nix/doc/manual/introduction/about-nix.xml vendored Normal file
View file

@ -0,0 +1,268 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-about-nix">
<title>About Nix</title>
<para>Nix is a <emphasis>purely functional package manager</emphasis>.
This means that it treats packages like values in purely functional
programming languages such as Haskell — they are built by functions
that don’t have side-effects, and they never change after they have
been built. Nix stores packages in the <emphasis>Nix
store</emphasis>, usually the directory
<filename>/nix/store</filename>, where each package has its own unique
subdirectory such as
<programlisting>
/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
</programlisting>
where <literal>b6gvzjyb2pg0…</literal> is a unique identifier for the
package that captures all its dependencies (it’s a cryptographic hash
of the package’s build dependency graph). This enables many powerful
features.</para>
<simplesect><title>Multiple versions</title>
<para>You can have multiple versions or variants of a package
installed at the same time. This is especially important when
different applications have dependencies on different versions of the
same package — it prevents the “DLL hell”. Because of the hashing
scheme, different versions of a package end up in different paths in
the Nix store, so they don’t interfere with each other.</para>
<para>An important consequence is that operations like upgrading or
uninstalling an application cannot break other applications, since
these operations never “destructively” update or delete files that are
used by other packages.</para>
</simplesect>
<simplesect><title>Complete dependencies</title>
<para>Nix helps you make sure that package dependency specifications
are complete. In general, when you’re making a package for a package
management system like RPM, you have to specify for each package what
its dependencies are, but there are no guarantees that this
specification is complete. If you forget a dependency, then the
package will build and work correctly on <emphasis>your</emphasis>
machine if you have the dependency installed, but not on the end
user's machine if it's not there.</para>
<para>Since Nix on the other hand doesn’t install packages in “global”
locations like <filename>/usr/bin</filename> but in package-specific
directories, the risk of incomplete dependencies is greatly reduced.
This is because tools such as compilers don’t search in per-packages
directories such as
<filename>/nix/store/5lbfaxb722zp…-openssl-0.9.8d/include</filename>,
so if a package builds correctly on your system, this is because you
specified the dependency explicitly. This takes care of the build-time
dependencies.</para>
<para>Once a package is built, runtime dependencies are found by
scanning binaries for the hash parts of Nix store paths (such as
<literal>r8vvq9kq…</literal>). This sounds risky, but it works
extremely well.</para>
</simplesect>
<simplesect><title>Multi-user support</title>
<para>Nix has multi-user support. This means that non-privileged
users can securely install software. Each user can have a different
<emphasis>profile</emphasis>, a set of packages in the Nix store that
appear in the user’s <envar>PATH</envar>. If a user installs a
package that another user has already installed previously, the
package won’t be built or downloaded a second time. At the same time,
it is not possible for one user to inject a Trojan horse into a
package that might be used by another user.</para>
</simplesect>
<simplesect><title>Atomic upgrades and rollbacks</title>
<para>Since package management operations never overwrite packages in
the Nix store but just add new versions in different paths, they are
<emphasis>atomic</emphasis>. So during a package upgrade, there is no
time window in which the package has some files from the old version
and some files from the new version — which would be bad because a
program might well crash if it’s started during that period.</para>
<para>And since packages aren’t overwritten, the old versions are still
there after an upgrade. This means that you can <emphasis>roll
back</emphasis> to the old version:</para>
<screen>
$ nix-env --upgrade <replaceable>some-packages</replaceable>
$ nix-env --rollback
</screen>
</simplesect>
<simplesect><title>Garbage collection</title>
<para>When you uninstall a package like this…
<screen>
$ nix-env --uninstall firefox
</screen>
the package isn’t deleted from the system right away (after all, you
might want to do a rollback, or it might be in the profiles of other
users). Instead, unused packages can be deleted safely by running the
<emphasis>garbage collector</emphasis>:
<screen>
$ nix-collect-garbage
</screen>
This deletes all packages that aren’t in use by any user profile or by
a currently running program.</para>
</simplesect>
<simplesect><title>Functional package language</title>
<para>Packages are built from <emphasis>Nix expressions</emphasis>,
which is a simple functional language. A Nix expression describes
everything that goes into a package build action (a “derivation”):
other packages, sources, the build script, environment variables for
the build script, etc. Nix tries very hard to ensure that Nix
expressions are <emphasis>deterministic</emphasis>: building a Nix
expression twice should yield the same result.</para>
<para>Because it’s a functional language, it’s easy to support
building variants of a package: turn the Nix expression into a
function and call it any number of times with the appropriate
arguments. Due to the hashing scheme, variants don’t conflict with
each other in the Nix store.</para>
</simplesect>
<simplesect><title>Transparent source/binary deployment</title>
<para>Nix expressions generally describe how to build a package from
source, so an installation action like
<screen>
$ nix-env --install firefox
</screen>
<emphasis>could</emphasis> cause quite a bit of build activity, as not
only Firefox but also all its dependencies (all the way up to the C
library and the compiler) would have to built, at least if they are
not already in the Nix store. This is a <emphasis>source deployment
model</emphasis>. For most users, building from source is not very
pleasant as it takes far too long. However, Nix can automatically
skip building from source and instead use a <emphasis>binary
cache</emphasis>, a web server that provides pre-built binaries. For
instance, when asked to build
<literal>/nix/store/b6gvzjyb2pg0…-firefox-33.1</literal> from source,
Nix would first check if the file
<uri>https://cache.nixos.org/b6gvzjyb2pg0….narinfo</uri> exists, and
if so, fetch the pre-built binary referenced from there; otherwise, it
would fall back to building from source.</para>
</simplesect>
<!--
<simplesect><title>Binary patching</title>
<para>In addition to downloading binaries automatically if they’re
available, Nix can download binary deltas that patch an existing
package in the Nix store into a new version. This speeds up
upgrades.</para>
</simplesect>
-->
<simplesect><title>Nix Packages collection</title>
<para>We provide a large set of Nix expressions containing hundreds of
existing Unix packages, the <emphasis>Nix Packages
collection</emphasis> (Nixpkgs).</para>
</simplesect>
<simplesect><title>Managing build environments</title>
<para>Nix is extremely useful for developers as it makes it easy to
automatically set up the build environment for a package. Given a
Nix expression that describes the dependencies of your package, the
command <command>nix-shell</command> will build or download those
dependencies if they’re not already in your Nix store, and then start
a Bash shell in which all necessary environment variables (such as
compiler search paths) are set.</para>
<para>For example, the following command gets all dependencies of the
Pan newsreader, as described by <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix">its
Nix expression</link>:</para>
<screen>
$ nix-shell '&lt;nixpkgs>' -A pan
</screen>
<para>You’re then dropped into a shell where you can edit, build and test
the package:</para>
<screen>
[nix-shell]$ tar xf $src
[nix-shell]$ cd pan-*
[nix-shell]$ ./configure
[nix-shell]$ make
[nix-shell]$ ./pan/gui/pan
</screen>
<!--
<para>Since Nix packages are reproducible and have complete dependency
specifications, Nix makes an excellent basis for <a
href="[%root%]hydra">a continuous build system</a>.</para>
-->
</simplesect>
<simplesect><title>Portability</title>
<para>Nix runs on Linux and macOS.</para>
</simplesect>
<simplesect><title>NixOS</title>
<para>NixOS is a Linux distribution based on Nix. It uses Nix not
just for package management but also to manage the system
configuration (e.g., to build configuration files in
<filename>/etc</filename>). This means, among other things, that it
is easy to roll back the entire configuration of the system to an
earlier state. Also, users can install software without root
privileges. For more information and downloads, see the <link
xlink:href="http://nixos.org/">NixOS homepage</link>.</para>
</simplesect>
<simplesect><title>License</title>
<para>Nix is released under the terms of the <link
xlink:href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">GNU
LGPLv2.1 or (at your option) any later version</link>.</para>
</simplesect>
</chapter>

12
third_party/nix/doc/manual/introduction/introduction.xml vendored Normal file
View file

@ -0,0 +1,12 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="chap-introduction">
<title>Introduction</title>
<xi:include href="about-nix.xml" />
<xi:include href="quick-start.xml" />
</part>

124
third_party/nix/doc/manual/introduction/quick-start.xml vendored Normal file
View file

@ -0,0 +1,124 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="chap-quick-start">
<title>Quick Start</title>
<para>This chapter is for impatient people who don't like reading
documentation. For more in-depth information you are kindly referred
to subsequent chapters.</para>
<procedure>
<step><para>Install single-user Nix by running the following:
<screen>
$ bash &lt;(curl https://nixos.org/nix/install)
</screen>
This will install Nix in <filename>/nix</filename>. The install script
will create <filename>/nix</filename> using <command>sudo</command>,
so make sure you have sufficient rights. (For other installation
methods, see <xref linkend="chap-installation"/>.)</para></step>
<step><para>See what installable packages are currently available
in the channel:
<screen>
$ nix-env -qa
docbook-xml-4.3
docbook-xml-4.5
firefox-33.0.2
hello-2.9
libxslt-1.1.28
<replaceable>...</replaceable></screen>
</para></step>
<step><para>Install some packages from the channel:
<screen>
$ nix-env -i hello</screen>
This should download pre-built packages; it should not build them
locally (if it does, something went wrong).</para></step>
<step><para>Test that they work:
<screen>
$ which hello
/home/eelco/.nix-profile/bin/hello
$ hello
Hello, world!
</screen>
</para></step>
<step><para>Uninstall a package:
<screen>
$ nix-env -e hello</screen>
</para></step>
<step><para>You can also test a package without installing it:
<screen>
$ nix-shell -p hello
</screen>
This builds or downloads GNU Hello and its dependencies, then drops
you into a Bash shell where the <command>hello</command> command is
present, all without affecting your normal environment:
<screen>
[nix-shell:~]$ hello
Hello, world!
[nix-shell:~]$ exit
$ hello
hello: command not found
</screen>
</para></step>
<step><para>To keep up-to-date with the channel, do:
<screen>
$ nix-channel --update nixpkgs
$ nix-env -u '*'</screen>
The latter command will upgrade each installed package for which there
is a “newer” version (as determined by comparing the version
numbers).</para></step>
<step><para>If you're unhappy with the result of a
<command>nix-env</command> action (e.g., an upgraded package turned
out not to work properly), you can go back:
<screen>
$ nix-env --rollback</screen>
</para></step>
<step><para>You should periodically run the Nix garbage collector
to get rid of unused packages, since uninstalls or upgrades don't
actually delete them:
<screen>
$ nix-collect-garbage -d</screen>
<!--
The first command deletes old “generations” of your profile (making
rollbacks impossible, but also making the packages in those old
generations available for garbage collection), while the second
command actually deletes them.-->
</para></step>
</procedure>
</chapter>