path: root/doc/manual/quick-start.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         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 the following chapters.</para>

<orderedlist>

<listitem><para>Download a source tarball or RPM or Debian/Ubuntu
package from <link xlink:href='http://nixos.org/'/>.  Build source
distributions using the regular sequence:
        
<screen>
$ tar xvfj nix-<replaceable>version</replaceable>.tar.bz2
$ ./configure
$ make
$ make install <lineannotation>(as root)</lineannotation></screen>

This will install the Nix binaries in <filename>/usr/local</filename>
and keep the Nix store and other state in <filename>/nix</filename>.
You can change the former by specifying
<option>--prefix=<replaceable>path</replaceable></option>.  The
location of the store can be changed using
<option>--with-store-dir=<replaceable>path</replaceable></option>.
However, you shouldn't change the store location, if at all possible,
since that will make it impossible to use pre-built binaries from the
Nixpkgs channel and other channels.  The location of the state can be
changed using
<option>--localstatedir=<replaceable>path</replaceable>.</option></para></listitem>

<listitem><para>You should add
<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
to your <filename>~/.bashrc</filename> (or some other login
file).</para></listitem>

<listitem><para>Subscribe to the Nix Packages channel.

<screen>
$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen>

</para></listitem>

<listitem><para>Download the latest Nix expressions available in the channel.
<screen>
$ nix-channel --update</screen>

Note that this in itself doesn't download any packages, it just
downloads the Nix expressions that build them and stores them
somewhere (under <filename>~/.nix-defexpr</filename>, in case you're
curious).  Also, it registers the fact that pre-built binaries are
available remotely.</para></listitem>

<listitem><para>See what installable packages are currently available
in the channel:

<screen>
$ nix-env -qa \*
docbook-xml-4.2
firefox-1.0pre-PR-0.10.1
hello-2.1.1
libxslt-1.1.0
<replaceable>...</replaceable></screen>

</para></listitem>

<listitem><para>Install some packages from the channel:
        
<screen>
$ nix-env -i hello firefox <replaceable>...</replaceable> </screen>

This should download pre-built packages; it should not build them
locally (if it does, something went wrong).</para></listitem>

<listitem><para>Test that they work:

<screen>
$ which hello
/home/eelco/.nix-profile/bin/hello
$ hello
Hello, world!
$ firefox
<lineannotation>(read Slashdot or something)</lineannotation></screen>

</para></listitem>
    
<listitem><para>Uninstall a package:

<screen>
$ nix-env -e hello</screen>

</para></listitem>

<listitem><para>To keep up-to-date with the channel, do:

<screen>
$ nix-channel --update
$ 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></listitem>

<listitem><para>You can also install specific packages directly from
your web browser.  For instance, you can go to <link
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
/> and click on any link for the individual packages for your
platform.  Associate <literal>application/nix-package</literal> with
the program <command>nix-install-package</command>.  A window should
appear asking you whether it’s okay to install the package.  Say
<literal>Y</literal>.  The package and all its dependencies will be
installed.</para></listitem>

<listitem><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></listitem>

<listitem><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></listitem>

</orderedlist>

</chapter>