1 files changed, 84 insertions, 0 deletions
diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml
new file mode 100644
index 000000000000..c1789fcbc041
--- /dev/null
+++ b/nixos/doc/manual/configuration/adding-custom-packages.xml
@@ -0,0 +1,84 @@
+<section 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="sec-custom-packages">
+
+<title>Adding Custom Packages</title>
+
+<para>It’s possible that a package you need is not available in NixOS.
+In that case, you can do two things.  First, you can clone the Nixpkgs
+repository, add the package to your clone, and (optionally) submit a
+patch or pull request to have it accepted into the main Nixpkgs
+repository.  This is described in detail in the <link
+xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.
+In short, you clone Nixpkgs:
+
+<screen>
+$ git clone git://github.com/NixOS/nixpkgs.git
+$ cd nixpkgs
+</screen>
+
+Then you write and test the package as described in the Nixpkgs
+manual.  Finally, you add it to
+<literal>environment.systemPackages</literal>, e.g.
+
+<programlisting>
+environment.systemPackages = [ pkgs.my-package ];
+</programlisting>
+
+and you run <command>nixos-rebuild</command>, specifying your own
+Nixpkgs tree:
+
+<screen>
+$ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
+
+</para>
+
+<para>The second possibility is to add the package outside of the
+Nixpkgs tree.  For instance, here is how you specify a build of the
+<link xlink:href="http://www.gnu.org/software/hello/">GNU Hello</link>
+package directly in <filename>configuration.nix</filename>:
+
+<programlisting>
+environment.systemPackages =
+  let
+    my-hello = with pkgs; stdenv.mkDerivation rec {
+      name = "hello-2.8";
+      src = fetchurl {
+        url = "mirror://gnu/hello/${name}.tar.gz";
+        sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
+      };
+    };
+  in
+  [ my-hello ];
+</programlisting>
+
+Of course, you can also move the definition of
+<literal>my-hello</literal> into a separate Nix expression, e.g.
+<programlisting>
+environment.systemPackages = [ (import ./my-hello.nix) ];
+</programlisting>
+where <filename>my-hello.nix</filename> contains:
+<programlisting>
+with import &lt;nixpkgs> {}; # bring all of Nixpkgs into scope
+
+stdenv.mkDerivation rec {
+  name = "hello-2.8";
+  src = fetchurl {
+    url = "mirror://gnu/hello/${name}.tar.gz";
+    sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
+  };
+}
+</programlisting>
+
+This allows testing the package easily:
+<screen>
+$ nix-build my-hello.nix
+$ ./result/bin/hello
+Hello, world!
+</screen>
+
+</para>
+
+</section>