From 3778586b2aaf2b5c905866d91d6f67e617ceb203 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Tue, 20 Jan 2004 15:37:55 +0000
Subject: [PATCH] * Nix Quick Start guide.

---
 doc/manual/Makefile.am      |   2 +-
 doc/manual/installation.xml |   2 +-
 doc/manual/manual.xml       |   4 +-
 doc/manual/overview.xml     |   2 +-
 doc/manual/quick-start.xml  | 136 ++++++++++++++++++++++++++++++++++++
 5 files changed, 142 insertions(+), 4 deletions(-)
 create mode 100644 doc/manual/quick-start.xml

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index f0344ef64..b1f5c3f46 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -9,7 +9,7 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
 SOURCES = manual.xml introduction.xml installation.xml overview.xml \
  nix-env.xml nix-store.xml nix-instantiate.xml \
  troubleshooting.xml bugs.xml opt-verbose.xml \
- style.css images
+ quick-start.xml style.css images
 
 manual.is-valid: $(SOURCES) version.xml
 	$(XMLLINT) --noout --valid manual.xml
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index ebc4f168a..39f6654ef 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -1,4 +1,4 @@
-<chapter>
+<chapter id='chap-installation'>
   <title>Installation</title>
 
   <sect1>
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index e95b0fc91..d47e57123 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -4,6 +4,7 @@
     "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [
 <!ENTITY introduction SYSTEM "introduction.xml">
+<!ENTITY quick-start SYSTEM "quick-start.xml">
 <!ENTITY installation SYSTEM "installation.xml">
 <!ENTITY overview SYSTEM "overview.xml">
 <!ENTITY opt-verbose SYSTEM "opt-verbose.xml">
@@ -26,12 +27,13 @@
       <surname>Dolstra</surname>
     </author>
     <copyright>
-      <year>2003</year>
+      <year>2004</year>
       <holder>Eelco Dolstra</holder>
     </copyright>
   </bookinfo>
 
   &introduction;
+  &quick-start;
   &installation;
   &overview;
 
diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml
index 9925be994..191f7a6fe 100644
--- a/doc/manual/overview.xml
+++ b/doc/manual/overview.xml
@@ -1,4 +1,4 @@
-<chapter>
+<chapter id='chap-overview'>
   <title>Overview</title>
 
   <para>
diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml
new file mode 100644
index 000000000..62dc64939
--- /dev/null
+++ b/doc/manual/quick-start.xml
@@ -0,0 +1,136 @@
+<chapter>
+  <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 <xref linkend='chap-installation' /> and <xref
+    linkend='chap-overview' />.
+  </para>
+
+  <orderedlist>
+
+    <listitem>
+      <para>
+        Download a source tarball or RPM from <ulink
+        url='http://www.cs.uu.nl/groups/ST/Trace/NixDeploymentSystem'/>.
+        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 Nix in <filename>/nix</filename>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Get some Nix expressions for pre-built packages by downloading
+        the latest <literal>nixpkgs</literal> distribution (from the
+        same location), and unpack them.
+
+        <screen>
+$ wget http://<replaceable>...</replaceable>/nix/nixpkgs-<replaceable>version</replaceable>/nixpkgs-<replaceable>version</replaceable>.tar.bz2
+$ tar xfj nixpkgs-<replaceable>version</replaceable>.tar.bz2</screen>
+
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Pull the Nix cache.  This ensures that when you install
+        packages they are downloaded in pre-built form from the
+        network, rather than built from source.
+
+        <screen>
+$ nix-pull http://<replaceable>...</replaceable>/nix/nixpkgs-<replaceable>version</replaceable>/</screen>
+
+      </para>
+
+      <para>
+        Note that currently we only pre-build for Linux on x86
+        platforms.
+      </para>
+        
+    </listitem>
+        
+    <listitem>
+      <para>
+        See what's available:
+
+        <screen>
+$ nix-env -qaf nixpkgs-<replaceable>version</replaceable>
+MozillaFirebird-0.7
+hello-2.1.1
+docbook-xml-4.2
+libxslt-1.1.0
+<replaceable>...</replaceable></screen>
+
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Install some packages:
+        
+        <screen>
+$ nix-env -iBf nixpkgs-<replaceable>version</replaceable> hello MozillaFirebird <replaceable>...</replaceable> </screen>
+
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Test that they work:
+
+        <screen>
+$ which hello
+/home/eelco/.nix-userenv/bin/hello
+$ hello
+Hello, world!
+$ MozillaFirebird
+<lineannotation>(read Slashdot or something)</lineannotation></screen>
+
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        Uninstall a package:
+
+        <screen>
+$ nix-env -e hello</screen>
+
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If a new release of <literal>nixpkgs</literal> comes along,
+        you can upgrade all installed packages to the latest versions
+        by downloading and unpacking the new release and doing:
+
+        <screen>
+$ nix-env -uBf nixpkgs-<replaceable>version</replaceable> '*'</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
+        actual delete them:
+
+        <screen>
+$ nix-collect-garbage | xargs nix-store --delete</screen>
+
+      </para>
+    </listitem>
+
+  </orderedlist>
+
+</chapter>
\ No newline at end of file