about summary refs log tree commit diff
path: root/third_party/nix/doc/manual/introduction
diff options
context:
space:
mode:
authorVincent Ambo <mail@tazj.in>2022-05-18T15·39+0200
committerclbot <clbot@tvl.fyi>2022-05-19T14·08+0000
commitd127f9bd0e7b9b2e0df2de8a2227f77c0907468d (patch)
tree68455040d88b8e0c2817601db88ede450873ff8e /third_party/nix/doc/manual/introduction
parentc85291c602ac666421627d6934ebc6d5be1b93e1 (diff)
chore(3p/nix): unvendor tvix 0.1 r/4098
Nothing is using this now, and we'll likely never pick this up again,
but we learned a lot in the process.

Every now and then this breaks in some bizarre way on channel bumps
and it's just a waste of time to maintain that.

Change-Id: Idcf2f5acd4ca7070ce18d7149cbfc0d967dc0a44
Reviewed-on: https://cl.tvl.fyi/c/depot/+/5632
Tested-by: BuildkiteCI
Reviewed-by: sterni <sternenseemann@systemli.org>
Reviewed-by: lukegb <lukegb@tvl.fyi>
Autosubmit: tazjin <tazjin@tvl.su>
Diffstat (limited to 'third_party/nix/doc/manual/introduction')
-rw-r--r--third_party/nix/doc/manual/introduction/about-nix.xml268
-rw-r--r--third_party/nix/doc/manual/introduction/introduction.xml12
-rw-r--r--third_party/nix/doc/manual/introduction/quick-start.xml124
3 files changed, 0 insertions, 404 deletions
diff --git a/third_party/nix/doc/manual/introduction/about-nix.xml b/third_party/nix/doc/manual/introduction/about-nix.xml
deleted file mode 100644
index c21ed34ddc74..000000000000
--- a/third_party/nix/doc/manual/introduction/about-nix.xml
+++ /dev/null
@@ -1,268 +0,0 @@
-<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>
diff --git a/third_party/nix/doc/manual/introduction/introduction.xml b/third_party/nix/doc/manual/introduction/introduction.xml
deleted file mode 100644
index 12b2cc761063..000000000000
--- a/third_party/nix/doc/manual/introduction/introduction.xml
+++ /dev/null
@@ -1,12 +0,0 @@
-<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>
diff --git a/third_party/nix/doc/manual/introduction/quick-start.xml b/third_party/nix/doc/manual/introduction/quick-start.xml
deleted file mode 100644
index 1ce6c8d50a1b..000000000000
--- a/third_party/nix/doc/manual/introduction/quick-start.xml
+++ /dev/null
@@ -1,124 +0,0 @@
-<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>