nix-pills/pills/02-install-on-your-running.xml

<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="install-on-your-running-system">

  <title>Install on Your Running System</title>

  <para>
    Welcome to the second Nix pill. In the <link
    linkend="why-you-should-give-it-a-try">first</link> pill we
    briefly described Nix.
  </para>

  <para>
    Now we'll install Nix on our running system and understand what
    changed in our system after the installation.
  </para>

  <para>
     <link xlink:href="https://nixos.org/nix/manual/#chap-installation">Installing
     Nix</link> is as easy as installing any other package.
     It will not drastically change our system, it will stay out of our way.
  </para>

  <section>
    <title>Installation</title>

    <para>
      To install Nix, run <command>curl https://nixos.org/nix/install | sh</command>
      as a non-root user and follow the instructions. Alternatively, you may
      prefer to download the installation script and verify its integrity using
      GPG signatures. Instructions for doing so can be found here: <link
      xlink:href="https://nixos.org/nix/download.html">https://nixos.org/nix/download.html</link>.
    </para>

    <para>
      These articles are not a tutorial on <emphasis>using</emphasis> Nix.
      Instead, we're going to walk through the Nix system to understand the fundamentals.
    </para>

    <para>
      The first thing to note: derivations in the Nix store refer to other
      derivations which are themselves in the Nix store. They don't use <literal>libc</literal>
      from our system or anywhere else. It's a self-contained store of all the software we need to bootstrap up
      to any particular package.
    </para>

    <note><para>
      In a multi-user installation, such as the one used in NixOS,
      the store is owned by root and multiple users can install and build
      software through a Nix daemon. You can read more about multi-user
      installations here: <link
      xlink:href="https://nixos.org/nix/manual/#ssec-multi-user">https://nixos.org/nix/manual/#ssec-multi-user</link>.
    </para></note>
  </section>

  <section>
    <title>The beginnings of the Nix store</title>

    <para>
      Start looking at the output of the install command:
    </para>

    <screen>copying Nix to /nix/store..........................</screen>

    <para>
      That's the <filename>/nix/store</filename> we
      were talking in the first article. We're copying in the 
      necessary software to bootstrap a Nix system. You can see bash,
      coreutils, the C compiler toolchain, perl libraries, sqlite and Nix itself
      with its own tools and libnix.
    </para>

    <para>
      You may have noticed that <filename>/nix/store</filename> can contain
      not only directories, but also files, still always in the form
      <replaceable>hash-name</replaceable>.
    </para>
  </section>

  <section>
    <title>The Nix database</title>

    <para>
      Right after copying the store, the installation process
      initializes a database:
    </para>

    <screen>initialising Nix database...</screen>

    <para>
      Yes, Nix also has a database. It's stored under
      <filename>/nix/var/nix/db</filename>. It is a sqlite database
      that keeps track of the dependencies between derivations.
    </para>

    <para>
      The schema is very simple: there's a table of valid paths,
      mapping from an auto increment integer to a store path.
    </para>

    <para>
      Then there's a dependency relation from path to paths upon which they depend.
    </para>

    <para>
      You can inspect the database by installing sqlite
      (<command>nix-env -iA sqlite -f '&lt;nixpkgs&gt;'</command>) and then running
      <command>sqlite3 /nix/var/nix/db/db.sqlite</command>.
    </para>

    <note><para>If this is the first time you're using Nix after the
    initial installation, remember you must close and open your
    terminals first, so that your shell environment will be updated.</para></note>

    <important><para>
      Never change <filename>/nix/store</filename> manually. If you do, then it will
      no longer be in sync with the sqlite db, unless you <emphasis>really</emphasis>
      know what you are doing.
    </para></important>
  </section>

  <section>
    <title>The first profile</title>

    <para>
      Next in the installation, we encounter the concept of the <link
      xlink:href="https://nixos.org/nix/manual/#sec-profiles">profile</link>:
    </para>

    <xi:include href="./02/user-environment.xml" parse="xml" />

    <para>
      A profile in Nix is a general and convenient concept for
      realizing rollbacks. Profiles are used to compose 
      components that are spread among multiple paths under a new
      unified path. Not only that, but profiles are made up of multiple
      "generations": they are versioned. Whenever you change a profile,
      a new generation is created.
    </para>

    <para>
      Generations can be switched and rolled back atomically, which makes
      them convenient for managing changes to your system.
    </para>

    <para>
      Let's take a closer look at our profile:
    </para>

    <xi:include href="./02/profile.xml" parse="xml" />
    <para>
     That <package>nix-2.1.3</package> derivation in the Nix store is
     Nix itself, with binaries and libraries. The process of "installing" 
     the derivation in the profile basically reproduces the hierarchy of the
     <package>nix-2.1.3</package> store derivation in the profile by means of
     symbolic links.
    </para>
    <para>
      The contents of this profile are special, because only one
      program has been installed in our profile, therefore e.g. the
      <filename>bin</filename> directory points to the only program
      which has been installed (Nix itself).
    </para>
    <para>
      But that's only the contents of the latest generation of our
      profile. In fact, <filename>~/.nix-profile</filename> itself is a
      symbolic link to
      <filename>/nix/var/nix/profiles/default</filename>.
    </para>

    <para>
      In turn, that's a symlink to <filename>default-1-link</filename>
      in the same directory. Yes, that means it's the first generation of
      the <literal>default</literal> profile.
    </para>

    <para>
      Finally, <filename>default-1-link</filename> is a symlink to the nix
      store "user-environment" derivation that you saw printed during the installation process.
    </para>

    <para>
      We'll talk about <filename>manifest.nix</filename> more in the next article.
    </para>
  </section>

  <section>
    <title>Nixpkgs expressions</title>

    <para>
      More output from the installer:
    </para>

    <screen><xi:include href="./02/nixpkgs-expressions.txt"
    parse="text" /></screen>

    <para>
      <link
          xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
      expressions</link> are used to describe packages and how to
      build them. <link
      xlink:href="https://nixos.org/nixpkgs/">Nixpkgs</link> is the
      repository containing all of the expressions: <link
      xlink:href="https://github.com/NixOS/nixpkgs">https://github.com/NixOS/nixpkgs</link>.
    </para>

    <para>
      The installer downloaded the package descriptions from commit
      <literal>a1a2851</literal>.
    </para>

    <para>
      The second profile we discover is the channels profile.
      <filename>~/.nix-defexpr/channels</filename> points to
      <filename>/nix/var/nix/profiles/per-user/nix/channels</filename>
      which points to <literal>channels-1-link</literal> which points
      to a Nix store directory containing the downloaded Nix
      expressions.
    </para>

    <para>
      Channels are a set of packages and expressions available for
      download. Similar to Debian stable and unstable, there's a
      stable and unstable channel. In this installation, we're
      tracking <literal>nixpkgs-unstable</literal>.
    </para>

    <para>
      Don't worry about Nix expressions yet, we'll get to them later.
    </para>

    <para>
      Finally, for your convenience, the installer modified
      <filename>~/.profile</filename> to automatically enter the Nix
      environment. What
      <filename>~/.nix-profile/etc/profile.d/nix.sh</filename> really
      does is simply to add <filename>~/.nix-profile/bin</filename> to
      <varname>PATH</varname> and
      <filename>~/.nix-defexpr/channels/nixpkgs</filename> to
      <varname>NIX_PATH</varname>. We'll discuss 
      <varname>NIX_PATH</varname> later.
    </para>

    <para>
      Read <filename>nix.sh</filename>, it's short.
    </para>

  </section>

  <section>
    <title>FAQ: Can I change /nix to something else?</title>

    <para>
      You can, but there's a good reason to keep using
      <filename>/nix</filename> instead of a different directory. All
      the derivations depend on other derivations by using absolute paths. We
      saw in the first article that bash referenced a
      <package>glibc</package> under a specific absolute path in <filename>/nix/store</filename>.
    </para>

    <para>
      You can see for yourself, don't worry if you see multiple
      bash derivations:
    </para>


    <screen><xi:include href="./02/ldd-bash.txt" parse="text" /></screen>

    <para>
      Keeping the store in <filename>/nix</filename> means we can grab
      the binary cache from nixos.org (just like you grab packages
      from debian mirrors) otherwise:

      <itemizedlist>
        <listitem><para>
          <package>glibc</package> would be installed under <filename>/foo/store</filename>
        </para></listitem>
        <listitem><para>
          Thus bash would need to point to <package>glibc</package> under <filename>/foo/store</filename>,
          instead of under <filename>/nix/store</filename>
        </para></listitem>
        <listitem><para>
          So the binary cache can't help, because we need a <emphasis>different</emphasis> bash,
          and so we'd have to recompile everything ourselves.
        </para></listitem>
      </itemizedlist>
    </para>

    <para>
      After all <filename>/nix</filename> is a sensible place for the store.
    </para>
  </section>

  <section>
    <title>Conclusion</title>
    <para>
      We've installed Nix on our system, fully isolated and owned by
      the <literal>nix</literal> user as we're still coming to terms with
      this new system.
    </para>
    <para>
      We learned some new concepts like profiles and channels. In
      particular, with profiles we're able to manage multiple
      generations of a composition of packages, while with channels
      we're able to download binaries from <literal>nixos.org</literal>.
    </para>
    <para>
      The installation put everything under <filename>/nix</filename>,
      and some symlinks in the Nix user home. That's because every
      user is able to install and use software in her own environment.
    </para>
    <para>
      I hope I left nothing uncovered so that you think there's
      some kind of magic going on behind the scenes. It's all
      about putting components in the store and symlinking
      these components together.
    </para>
  </section>

  <section>
    <title>Next pill...</title>

    <para>
      ...we will enter the Nix environment and learn how to interact
      with the store.
    </para>
  </section>

</chapter>