diff options
Diffstat (limited to 'doc/quick-start.xml')
-rw-r--r-- | doc/quick-start.xml | 144 |
1 files changed, 36 insertions, 108 deletions
diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 39e3e7396bd..80514cba490 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -15,120 +15,75 @@ </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. + 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> <prompt>$ </prompt>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>. + 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> <prompt>$ </prompt>emacs pkgs/development/libraries/libfoo/default.nix <prompt>$ </prompt>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: + 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. + 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 - 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>. + 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 - 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>. + 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 - 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>. + 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 - 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. + 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 - 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. + 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 - 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 - 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. + 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 + 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 - 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. + 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 - 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 - 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. + 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 + 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> @@ -138,67 +93,45 @@ <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 + 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> - <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. + You can use <command>nix-prefetch-url</command> <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 + 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 - 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>. + 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 - 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>. + 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> <prompt>$ </prompt>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. + 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: + To test whether the package builds, run the following command from the root of the nixpkgs source tree: <screen> <prompt>$ </prompt>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. + 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> @@ -210,14 +143,9 @@ </listitem> <listitem> <para> - Optionally commit the new package and open a pull request - <link - xlink:href="https://github.com/NixOS/nixpkgs/pulls">to - nixpkgs</link>, or use - <link - xlink:href="https://discourse.nixos.org/t/about-the-patches-category/477"> - the Patches category</link> on Discourse for sending a patch without a - GitHub account. + Optionally commit the new package and open a pull request <link + xlink:href="https://github.com/NixOS/nixpkgs/pulls">to nixpkgs</link>, or use <link + xlink:href="https://discourse.nixos.org/t/about-the-patches-category/477"> the Patches category</link> on Discourse for sending a patch without a GitHub account. </para> </listitem> </orderedlist> |