* Quick start section.

* Updated some packages that are referenced in that section.

svn path=/nixpkgs/trunk/; revision=12139

doc/introduction.xml

@@ -4,6 +4,18 @@
 
 <title>Introduction</title>
 
-<para>Bla</para>
+<para>This manual tells you how to write packages for the Nix Packages
+collection (Nixpkgs).  Thus it’s for packagers and developers who want
+to add packages to Nixpkgs.  End users are kindly referred to the
+<link xlink:href="http://nixos.org/releases/nix/unstable/manual/">Nix
+manual</link>.</para>
+
+<para>This manual does not describe the syntax and semantics of the
+Nix expression language, which are given in the Nix manual in the
+<link
+xlink:href="http://nixos.org/releases/nix/unstable/manual/#chap-writing-nix-expressions">chapter
+on writing Nix expressions</link>.  It only describes the facilities
+provided by Nixpkgs to make writing packages easier, such as the
+standard build environment (<literal>stdenv</literal>).</para>
 
 </chapter>

doc/manual.xml

@@ -29,5 +29,7 @@
   </info>
 
   <xi:include href="introduction.xml" />
+  <xi:include href="quick-start.xml" />
+  <xi:include href="stdenv.xml" />
   
 </book>

doc/outline.txt

@@ -170,3 +170,7 @@
     - fetchcvs
 
     - fetchdarcs
+
+
+- Appendix: Nixpkgs config options
+

doc/quick-start.xml

@@ -0,0 +1,240 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="chap-overvie">
+
+<title>Quick Start to Adding a Package</title>
+
+<para>To add a package to Nixpkgs:
+
+<orderedlist>
+
+  <listitem>
+    <para>Checkout the Nixpkgs source tree:
+
+<screen>
+$ svn checkout https://svn.nixos.org/repos/nix/nixpkgs/trunk nixpkgs
+$ cd nixpkgs</screen>
+
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>Find a good place in the Nixpkgs tree to add the Nix
+    expression for your package.  For instance, a library package
+    typically goes into
+    <filename>pkgs/development/libraries/<replaceable>pkgname</replaceable></filename>,
+    while a web browser goes into
+    <filename>pkgs/applications/networking/browsers/<replaceable>pkgname</replaceable></filename>.
+    See Section XXX for some hints on the tree organisation.  Create a
+    directory for your package, e.g.
+
+<screen>
+$ svn mkdir pkgs/development/libraries/libfoo</screen>
+  
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>In the package directory, create a Nix expression — a piece
+    of code that describes how to build the package.  In this case, it
+    should be a <emphasis>function</emphasis> that is called with the
+    package dependencies as arguments, and returns a build of the
+    package in the Nix store.  The expression should usually be called
+    <filename>default.nix</filename>.
+
+<screen>
+$ emacs pkgs/development/libraries/libfoo/default.nix
+$ svn add pkgs/development/libraries/libfoo/default.nix</screen>
+
+    </para>
+
+    <para>You can have a look at the existing Nix expressions under
+    <filename>pkgs/</filename> to see how it’s done.  Here are some
+    good ones:
+
+      <itemizedlist>
+
+        <listitem>
+          <para>GNU cpio: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>.
+          The simplest possible package.  The generic builder in
+          <varname>stdenv</varname> does everything for you.  It has
+          no dependencies beyond <varname>stdenv</varname>.</para>
+        </listitem>
+
+        <listitem>
+          <para>GNU Hello: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/misc/hello/ex-2/default.nix"><filename>pkgs/applications/misc/hello/ex-2/default.nix</filename></link>.
+          Also trivial, but it specifies some <varname>meta</varname>
+          attributes which is good practice.</para>
+        </listitem>
+
+        <listitem>
+          <para>GNU Multiple Precision arithmetic library (GMP): <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/libraries/gmp/default.nix"><filename>pkgs/development/libraries/gmp/default.nix</filename></link>.
+          Also done by the generic builder, but has a dependency on
+          <varname>m4</varname>.</para>
+        </listitem>
+
+        <listitem>
+          <para>Pan, a GTK-based newsreader: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/networking/newsreaders/pan/default.nix"><filename>pkgs/applications/networking/newsreaders/pan/default.nix</filename></link>.
+          Has an optional dependency on <varname>gtkspell</varname>,
+          which is only built if <varname>spellCheck</varname> is
+          <literal>true</literal>.</para>
+        </listitem>
+
+        <listitem>
+          <para>Apache HTTPD: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/servers/http/apache-httpd/default.nix"><filename>pkgs/servers/http/apache-httpd/default.nix</filename></link>.
+          A bunch of optional features, variable substitutions in the
+          configure flags, a post-install hook, and miscellaneous
+          hackery.</para>
+        </listitem>
+
+        <listitem>
+          <para>BitTorrent (wxPython-based): <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/networking/p2p/bittorrent/default.nix"><filename>pkgs/tools/networking/p2p/bittorrent/default.nix</filename></link>.
+          Uses an external <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/networking/p2p/bittorrent/builder.sh">build
+          script</link>, which can be useful if you have lots of code
+          that you don’t want cluttering up the Nix expression.  But
+          external builders are mostly obsolete.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>Firefox: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/networking/browsers/firefox-3/default.nix"><filename>pkgs/applications/networking/browsers/firefox-3/default.nix</filename></link>.
+          Lots of dependencies.</para>
+        </listitem>
+
+        <listitem>
+          <para>JDiskReport, a Java utility: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link>
+          (and the <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>).
+          Nixpkgs doesn’t have a decent <varname>stdenv</varname> for
+          Java yet so this is pretty ad-hoc.</para>
+        </listitem>
+
+        <listitem>
+          <para>XML::Simple, a Perl module: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
+          (search for the <varname>perlXMLSimple</varname>
+          attribute).  Most Perl modules are so simple to build that
+          they are defined directly in
+          <filename>all-packages.nix</filename>, no need to make a
+          separate file for them.</para>
+        </listitem>
+
+        <listitem>
+          <para>Adobe Reader: <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/misc/acrobat-reader/default.nix"><filename>pkgs/applications/misc/acrobat-reader/default.nix</filename></link>.
+          Shows how binary-only packages can be supported.  In
+          particular the <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/misc/acrobat-reader/builder.sh">builder</link>
+          uses <command>patchelf</command> to set the RUNPATH and ELF
+          interpreter of the executables so that the right libraries
+          are found at runtime.</para>
+        </listitem>
+
+      </itemizedlist>
+
+    </para>
+
+    <para>Some notes:
+
+      <itemizedlist>
+
+        <listitem>
+          <para>All <varname>meta</varname> attributes are optional,
+          but it’s still a good idea to provide at least the
+          <varname>description</varname> and
+          <varname>homepage</varname>.</para>
+        </listitem>
+
+        <listitem>
+          <para>You can use <command>nix-prefetch-url</command>
+          <replaceable>url</replaceable> to get the SHA-256 hash of
+          source distributions.</para>
+        </listitem>
+
+        <listitem>
+          <para>A list of schemes for <literal>mirror://</literal>
+          URLs can be found in <link
+          xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.</para>
+        </listitem>
+
+      </itemizedlist>
+
+    </para>
+
+    <para>The exact syntax and semantics of the Nix expression
+    language, including the built-in function, are described in the
+    Nix manual in the <link
+    xlink:href="http://nixos.org/releases/nix/unstable/manual/#chap-writing-nix-expressions">chapter
+    on writing Nix expressions</link>.</para>
+    
+  </listitem>
+
+  <listitem>
+    <para>Add a call to the function defined in the previous step to
+    <link
+    xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
+    with some descriptive name for the variable,
+    e.g. <varname>libfoo</varname>.
+
+    <screen>
+$ emacs pkgs/top-level/all-packages.nix</screen>
+      
+    </para>
+
+    <para>The attributes in that file are sorted by category (like
+    “Development / Libraries”) that more-or-less correspond to the
+    directory structure of Nixpkgs, and then by attribute name.</para>
+  </listitem>
+
+  <listitem>
+    <para>Test whether the package builds:
+
+    <screen>
+$ nix-build -A libfoo</screen>
+
+    where <varname>libfoo</varname> should be the variable name
+    defined in the previous step.  You may want to add the flag
+    <option>-K</option> to keep the temporary build directory in case
+    something fails.  If the build succeeds, a symlink
+    <filename>./result</filename> to the package in the Nix store is
+    created.</para>
+  </listitem>
+
+  <listitem>
+    <para>If you want to install the package into your profile
+    (optional), do
+
+    <screen>
+$ nix-env -f . -iA libfoo</screen>
+
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>Optionally commit the new package (<command>svn
+    ci</command>) or send a patch to
+    <literal>nix-dev@cs.uu.nl</literal>.</para>
+  </listitem>
+
+  <listitem>
+    <para>If you want the TU Delft build farm to build binaries of the
+    package and make them available in the <link
+    xlink:href="http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable/"><literal>nixpkgs</literal>
+    channel</link>, add it to <link
+    xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/build-for-release.nix"><filename>pkgs/top-level/build-for-release.nix</filename></link>.</para>
+  </listitem>
+
+</orderedlist>
+
+</para>
+
+</chapter>

doc/stdenv.xml

@@ -0,0 +1,10 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="chap-stdenv">
+
+<title>The Standard Environment</title>
+
+<para></para>
+
+</chapter>
+

pkgs/applications/misc/hello/ex-2/default.nix

@@ -1,10 +1,20 @@
-{stdenv, fetchurl, perl}:
+{stdenv, fetchurl}:
 
 stdenv.mkDerivation {
-  name = "hello-2.1.1";
+  name = "hello-2.3";
+  
   src = fetchurl {
-    url = mirror://gnu/hello/hello-2.1.1.tar.gz;
+    url = mirror://gnu/hello/hello-2.3.tar.bz2;
-    md5 = "70c9ccf9fac07f762c24f2df2290784d";
+    sha256 = "0c7vijq8y68bpr7g6dh1gny0bff8qq81vnp4ch8pjzvg56wb3js1";
+  };
+  
+  meta = {
+    description = "A program that produces a familiar, friendly greeting";
+    longDescription = ''
+      GNU Hello is a program that prints "Hello, world!" when you run it.
+      It is fully customizable.
+    '';
+    homepage = http://www.gnu.org/software/hello/manual/;
+    license = "GPLv3+";
   };
-  buildInputs = [perl];
 }

pkgs/applications/networking/newsreaders/pan/default.nix

@@ -3,8 +3,7 @@
 , perl, pcre, gmime, gettext
 }:
 
-assert spellChecking -> gtkspell != null /* !!! && gtk == gtkspell.gtk */;
+assert spellChecking -> gtkspell != null;
-# !!! assert gtk.glib == gnet.glib;
 
 stdenv.mkDerivation {
   name = "pan-0.132";
@@ -22,14 +21,11 @@ stdenv.mkDerivation {
     })
   ];
 
-  buildInputs = [
+  buildInputs = [pkgconfig gtk perl pcre gmime gettext]
-    pkgconfig gtk perl pcre gmime gettext
+    ++ stdenv.lib.optional spellChecking gtkspell;
-    (if spellChecking then gtkspell else null)
-  ];
-
-  inherit spellChecking stdenv;
 
   meta = {
     description = "A GTK+-based Usenet newsreader good at both text and binaries";
+    homepage = http://pan.rebelbase.com/;
   };
 }

pkgs/tools/misc/jdiskreport/default.nix

@@ -3,12 +3,16 @@
 #assert jdk.swingSupport;
 
 stdenv.mkDerivation {
-  name = "jdiskreport-1.2.3";
+  name = "jdiskreport-1.3.0";
+  
   builder = ./builder.sh;
+  
   src = fetchurl {
-    url = http://www.jgoodies.com/download/jdiskreport/jdiskreport-1_2_3.zip;
+    url = http://www.jgoodies.com/download/jdiskreport/jdiskreport-1_3_0.zip;
-    md5 = "4a33c5c1344ed9e0fa531e2cb1875cb8";
+    sha256 = "1vgiq797gqc6i89w4kscg57snn74wi8x566bhi9xn8r0fbphihxb";
   };
+  
   buildInputs = [unzip];
+  
   inherit jdk;
 }

pkgs/tools/networking/p2p/bittorrent/builder.sh

@@ -1,19 +1,19 @@
 source $stdenv/setup
 
+
 # Workaround for:
 #  File "...-python-2.4.4/lib/python2.4/posixpath.py", line 62, in join
 #    elif path == '' or path.endswith('/'):
 # AttributeError: 'NoneType' object has no attribute 'endswith'
 export HOME=$TMP
 
-buildPhase=buildPhase
+
 buildPhase() {
     #substituteInPlace BitTorrent/GUI_wx/__init__.py --replace "'2.6'" "'2.8'"
     python setup.py build
 }
 
 
-installPhase=installPhase
 installPhase() {
     python setup.py install --prefix=$out
 
@@ -24,4 +24,5 @@ installPhase() {
     done
 }
 
+
 genericBuild

pkgs/tools/networking/p2p/bittorrent/default.nix

@@ -7,6 +7,7 @@ assert gui -> wxPython != null;
 
 stdenv.mkDerivation {
   name = "bittorrent-5.2.0";
+  
   builder = ./builder.sh;
   
   src = fetchurl {

pkgs/top-level/all-packages.nix

@@ -5862,8 +5862,8 @@ let pkgs = rec {
     inherit fetchurl stdenv;
   };
 
-  hello = import ../applications/misc/hello/ex-1 {
+  hello = import ../applications/misc/hello/ex-2 {
-    inherit fetchurl stdenv perl;
+    inherit fetchurl stdenv;
   };
 
   i810switch = import ../applications/misc/i810 {