From d97069da1a884600688ceee314c8f9d876744a52 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 17 Jun 2008 14:19:59 +0000 Subject: * Quick start section. * Updated some packages that are referenced in that section. svn path=/nixpkgs/trunk/; revision=12139 --- doc/quick-start.xml | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 doc/quick-start.xml (limited to 'doc/quick-start.xml') diff --git a/doc/quick-start.xml b/doc/quick-start.xml new file mode 100644 index 000000000000..dac34b7cee3d --- /dev/null +++ b/doc/quick-start.xml @@ -0,0 +1,240 @@ + + +Quick Start to Adding a Package + +To add a package to Nixpkgs: + + + + + Checkout the Nixpkgs source tree: + + +$ svn checkout https://svn.nixos.org/repos/nix/nixpkgs/trunk nixpkgs +$ cd nixpkgs + + + + + + Find a good place in the Nixpkgs tree to add the Nix + expression for your package. For instance, a library package + typically goes into + pkgs/development/libraries/pkgname, + while a web browser goes into + pkgs/applications/networking/browsers/pkgname. + See Section XXX for some hints on the tree organisation. Create a + directory for your package, e.g. + + +$ svn mkdir pkgs/development/libraries/libfoo + + + + + + 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 function 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 + default.nix. + + +$ emacs pkgs/development/libraries/libfoo/default.nix +$ svn add pkgs/development/libraries/libfoo/default.nix + + + + You can have a look at the existing Nix expressions under + pkgs/ to see how it’s done. Here are some + good ones: + + + + + GNU cpio: pkgs/tools/archivers/cpio/default.nix. + The simplest possible package. The generic builder in + stdenv does everything for you. It has + no dependencies beyond stdenv. + + + + GNU Hello: pkgs/applications/misc/hello/ex-2/default.nix. + Also trivial, but it specifies some meta + attributes which is good practice. + + + + GNU Multiple Precision arithmetic library (GMP): pkgs/development/libraries/gmp/default.nix. + Also done by the generic builder, but has a dependency on + m4. + + + + Pan, a GTK-based newsreader: pkgs/applications/networking/newsreaders/pan/default.nix. + Has an optional dependency on gtkspell, + which is only built if spellCheck is + true. + + + + Apache HTTPD: pkgs/servers/http/apache-httpd/default.nix. + A bunch of optional features, variable substitutions in the + configure flags, a post-install hook, and miscellaneous + hackery. + + + + BitTorrent (wxPython-based): pkgs/tools/networking/p2p/bittorrent/default.nix. + Uses an external build + script, 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. + + + + + Firefox: pkgs/applications/networking/browsers/firefox-3/default.nix. + Lots of dependencies. + + + + JDiskReport, a Java utility: pkgs/tools/misc/jdiskreport/default.nix + (and the builder). + Nixpkgs doesn’t have a decent stdenv for + Java yet so this is pretty ad-hoc. + + + + XML::Simple, a Perl module: pkgs/top-level/all-packages.nix + (search for the perlXMLSimple + attribute). Most Perl modules are so simple to build that + they are defined directly in + all-packages.nix, no need to make a + separate file for them. + + + + Adobe Reader: pkgs/applications/misc/acrobat-reader/default.nix. + Shows how binary-only packages can be supported. In + particular the builder + uses patchelf to set the RUNPATH and ELF + interpreter of the executables so that the right libraries + are found at runtime. + + + + + + + Some notes: + + + + + All meta attributes are optional, + but it’s still a good idea to provide at least the + description and + homepage. + + + + You can use nix-prefetch-url + url to get the SHA-256 hash of + source distributions. + + + + A list of schemes for mirror:// + URLs can be found in pkgs/build-support/fetchurl/mirrors.nix. + + + + + + + The exact syntax and semantics of the Nix expression + language, including the built-in function, are described in the + Nix manual in the chapter + on writing Nix expressions. + + + + + Add a call to the function defined in the previous step to + pkgs/top-level/all-packages.nix + with some descriptive name for the variable, + e.g. libfoo. + + +$ emacs pkgs/top-level/all-packages.nix + + + + 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. + + + + Test whether the package builds: + + +$ nix-build -A libfoo + + where libfoo should be the variable name + defined in the previous step. You may want to add the flag + to keep the temporary build directory in case + something fails. If the build succeeds, a symlink + ./result to the package in the Nix store is + created. + + + + If you want to install the package into your profile + (optional), do + + +$ nix-env -f . -iA libfoo + + + + + + Optionally commit the new package (svn + ci) or send a patch to + nix-dev@cs.uu.nl. + + + + If you want the TU Delft build farm to build binaries of the + package and make them available in the nixpkgs + channel, add it to pkgs/top-level/build-for-release.nix. + + + + + + + \ No newline at end of file -- cgit v1.2.3