diff options
author | Graham Christensen <graham@grahamc.com> | 2018-05-01 19:54:21 -0400 |
---|---|---|
committer | Graham Christensen <graham@grahamc.com> | 2018-05-01 19:54:21 -0400 |
commit | 77161de4546697f9bf2da6d081eeba4c399b3313 (patch) | |
tree | 8f77aeeb5a17cbc0c76b4401a090f55addabf975 /doc/quick-start.xml | |
parent | fd2dce9708ff68e8a5474d9bf691a23c52c7273e (diff) |
nixpkgs docs: format =)
Diffstat (limited to 'doc/quick-start.xml')
-rw-r--r-- | doc/quick-start.xml | 372 |
1 files changed, 184 insertions, 188 deletions
diff --git a/doc/quick-start.xml b/doc/quick-start.xml index ca86e6c9519b6..0cba3a4769c44 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -1,223 +1,219 @@ <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-quick-start"> - -<title>Quick Start to Adding a Package</title> - -<para>To add a package to Nixpkgs: - -<orderedlist> - - <listitem> - <para>Checkout the Nixpkgs source tree: - + <title>Quick Start to Adding a Package</title> + <para> + To add a package to Nixpkgs: + <orderedlist> + <listitem> + <para> + Checkout the Nixpkgs source tree: <screen> $ git clone git://github.com/NixOS/nixpkgs.git $ 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 <xref linkend="sec-organisation" /> for some hints on the tree - organisation. Create a directory for your package, e.g. - + </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 <xref linkend="sec-organisation" /> for some hints on the tree + organisation. Create a directory for your package, e.g. <screen> $ 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>. - + </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 $ git 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 Hello: <link + <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 Hello: + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>. - Trivial package, which specifies some <varname>meta</varname> - attributes which is good practice.</para> - </listitem> - - <listitem> - <para>GNU cpio: <link + Trivial package, which specifies some <varname>meta</varname> + attributes which is good practice. + </para> + </listitem> + <listitem> + <para> + GNU cpio: + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>. - Also a simple 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 Multiple Precision arithmetic library (GMP): <link + Also a simple 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 Multiple Precision arithmetic library (GMP): + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix"><filename>pkgs/development/libraries/gmp/5.1.x.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 + 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://github.com/NixOS/nixpkgs/blob/master/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 + 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://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix"><filename>pkgs/servers/http/apache-httpd/2.4.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>Thunderbird: <link + A bunch of optional features, variable substitutions in the configure + flags, a post-install hook, and miscellaneous hackery. + </para> + </listitem> + <listitem> + <para> + Thunderbird: + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix"><filename>pkgs/applications/networking/mailreaders/thunderbird/default.nix</filename></link>. - Lots of dependencies.</para> - </listitem> - - <listitem> - <para>JDiskReport, a Java utility: <link + Lots of dependencies. + </para> + </listitem> + <listitem> + <para> + JDiskReport, a Java utility: + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link> - (and the <link + (and the + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/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 + 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://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link> - (search for the <varname>XMLSimple</varname> attribute). - Most Perl modules are so simple to build that they are - defined directly in <filename>perl-packages.nix</filename>; - no need to make a separate file for them.</para> - </listitem> - - <listitem> - <para>Adobe Reader: <link + (search for the <varname>XMLSimple</varname> attribute). Most Perl + modules are so simple to build that they are defined directly in + <filename>perl-packages.nix</filename>; no need to make a separate file + for them. + </para> + </listitem> + <listitem> + <para> + Adobe Reader: + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix"><filename>pkgs/applications/misc/adobe-reader/default.nix</filename></link>. - Shows how binary-only packages can be supported. In - particular the <link + Shows how binary-only packages can be supported. In particular the + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-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> - + 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 linkend="chap-meta">meta</varname> - attributes are optional, but it’s still a good idea to - provide at least the <varname>description</varname>, - <varname>homepage</varname> and <varname - linkend="sec-meta-license">license</varname>.</para> - </listitem> - - <listitem> - <para>You can use <command>nix-prefetch-url</command> (or similar nix-prefetch-git, etc) - <replaceable>url</replaceable> to get the SHA-256 hash of - source distributions. There are similar commands as <command>nix-prefetch-git</command> and - <command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package.</para> - </listitem> - - <listitem> - <para>A list of schemes for <literal>mirror://</literal> - URLs can be found in <link - xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.</para> - </listitem> - - </itemizedlist> - + <para> + Some notes: + <itemizedlist> + <listitem> + <para> + All <varname linkend="chap-meta">meta</varname> attributes are + optional, but it’s still a good idea to provide at least the + <varname>description</varname>, <varname>homepage</varname> and + <varname + linkend="sec-meta-license">license</varname>. + </para> + </listitem> + <listitem> + <para> + You can use <command>nix-prefetch-url</command> (or similar + nix-prefetch-git, etc) <replaceable>url</replaceable> to get the + SHA-256 hash of source distributions. There are similar commands as + <command>nix-prefetch-git</command> and + <command>nix-prefetch-hg</command> available in + <literal>nix-prefetch-scripts</literal> package. + </para> + </listitem> + <listitem> + <para> + A list of schemes for <literal>mirror://</literal> URLs can be found in + <link + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/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 + <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://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/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 + 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://github.com/NixOS/nixpkgs/blob/master/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> + 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>To test whether the package builds, run the following command - from the root of the nixpkgs source tree: - - <screen> + <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> + To test whether the package builds, run the following command from the + root of the nixpkgs source tree: +<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> + 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 and open a pull request, or send a patch to - <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.</para> - </listitem> - - -</orderedlist> - -</para> - + </listitem> + <listitem> + <para> + Optionally commit the new package and open a pull request, or send a patch + to <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>. + </para> + </listitem> + </orderedlist> + </para> </chapter> |