doc: add section ids
This commit also use enforces consistent use of the prefixes "sec" for section and "ssec" for subsection.
This commit is contained in:
parent
d780e48b31
commit
53b5d946e1
|
@ -5,7 +5,7 @@
|
||||||
<title>Coding conventions</title>
|
<title>Coding conventions</title>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Syntax</title>
|
<section xml:id="sec-syntax"><title>Syntax</title>
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
|
||||||
|
@ -207,7 +207,7 @@ args.stdenv.mkDerivation (args // {
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Package naming</title>
|
<section xml:id="sec-package-naming"><title>Package naming</title>
|
||||||
|
|
||||||
<para>In Nixpkgs, there are generally three different names associated with a package:
|
<para>In Nixpkgs, there are generally three different names associated with a package:
|
||||||
|
|
||||||
|
@ -292,7 +292,7 @@ dashes between words — not in camel case. For instance, it should be
|
||||||
<filename>allPackages.nix</filename> or
|
<filename>allPackages.nix</filename> or
|
||||||
<filename>AllPackages.nix</filename>.</para>
|
<filename>AllPackages.nix</filename>.</para>
|
||||||
|
|
||||||
<section><title>Hierarchy</title>
|
<section xml:id="sec-hierarchy"><title>Hierarchy</title>
|
||||||
|
|
||||||
<para>Each package should be stored in its own directory somewhere in
|
<para>Each package should be stored in its own directory somewhere in
|
||||||
the <filename>pkgs/</filename> tree, i.e. in
|
the <filename>pkgs/</filename> tree, i.e. in
|
||||||
|
|
|
@ -13,7 +13,7 @@ in Nixpkgs to easily build packages for other programming languages,
|
||||||
such as Perl or Haskell. These are described in this chapter.</para>
|
such as Perl or Haskell. These are described in this chapter.</para>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="ssec-language-perl"><title>Perl</title>
|
<section xml:id="sec-language-perl"><title>Perl</title>
|
||||||
|
|
||||||
<para>Nixpkgs provides a function <varname>buildPerlPackage</varname>,
|
<para>Nixpkgs provides a function <varname>buildPerlPackage</varname>,
|
||||||
a generic package builder function for any Perl package that has a
|
a generic package builder function for any Perl package that has a
|
||||||
|
@ -151,7 +151,7 @@ ClassC3Componentised = buildPerlPackage rec {
|
||||||
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<section><title>Generation from CPAN</title>
|
<section xml:id="ssec-generation-from-CPAN"><title>Generation from CPAN</title>
|
||||||
|
|
||||||
<para>Nix expressions for Perl packages can be generated (almost)
|
<para>Nix expressions for Perl packages can be generated (almost)
|
||||||
automatically from CPAN. This is done by the program
|
automatically from CPAN. This is done by the program
|
||||||
|
@ -191,7 +191,7 @@ you need it.</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="python"><title>Python</title>
|
<section xml:id="sec-python"><title>Python</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Currently supported interpreters are <varname>python26</varname>, <varname>python27</varname>,
|
Currently supported interpreters are <varname>python26</varname>, <varname>python27</varname>,
|
||||||
|
@ -276,7 +276,7 @@ are provided with all modules included.</para>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
<section xml:id="build-python-package"><title><varname>buildPythonPackage</varname> function</title>
|
<section xml:id="ssec-build-python-package"><title><varname>buildPythonPackage</varname> function</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix">
|
The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix">
|
||||||
|
@ -438,7 +438,7 @@ twisted = buildPythonPackage {
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="python-build-env"><title><function>python.buildEnv</function> function</title>
|
<section xml:id="ssec-python-build-env"><title><function>python.buildEnv</function> function</title>
|
||||||
<para>
|
<para>
|
||||||
Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>:
|
Create Python environments using low-level <function>pkgs.buildEnv</function> function. Example <filename>default.nix</filename>:
|
||||||
|
|
||||||
|
@ -484,7 +484,7 @@ python.buildEnv.override {
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="python-tools"><title>Tools</title>
|
<section xml:id="ssec-python-tools"><title>Tools</title>
|
||||||
|
|
||||||
<para>Packages inside nixpkgs are written by hand. However many tools
|
<para>Packages inside nixpkgs are written by hand. However many tools
|
||||||
exist in community to help save time. No tool is preferred at the moment.
|
exist in community to help save time. No tool is preferred at the moment.
|
||||||
|
@ -511,7 +511,7 @@ exist in community to help save time. No tool is preferred at the moment.
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="python-development"><title>Development</title>
|
<section xml:id="ssec-python-development"><title>Development</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To develop Python packages <function>buildPythonPackage</function> has
|
To develop Python packages <function>buildPythonPackage</function> has
|
||||||
|
@ -555,7 +555,7 @@ buildPythonPackage {
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="python-faq"><title>FAQ</title>
|
<section xml:id="ssec-python-faq"><title>FAQ</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
|
|
||||||
|
@ -597,7 +597,7 @@ sed -i '/ = data_files/d' setup.py</programlisting>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="python-contrib"><title>Contributing guidelines</title>
|
<section xml:id="ssec-python-contrib"><title>Contributing guidelines</title>
|
||||||
<para>
|
<para>
|
||||||
Following rules are desired to be respected:
|
Following rules are desired to be respected:
|
||||||
</para>
|
</para>
|
||||||
|
@ -625,7 +625,7 @@ sed -i '/ = data_files/d' setup.py</programlisting>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="ssec-language-ruby"><title>Ruby</title>
|
<section xml:id="sec-language-ruby"><title>Ruby</title>
|
||||||
<para>There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert
|
<para>There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename>Gemfile</filename>, let bundler create a <filename>Gemfile.lock</filename>, and then convert
|
||||||
this into a nix expression that contains all Gem dependencies automatically.</para>
|
this into a nix expression that contains all Gem dependencies automatically.</para>
|
||||||
|
|
||||||
|
@ -666,7 +666,7 @@ and scalable.";
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="ssec-language-go"><title>Go</title>
|
<section xml:id="sec-language-go"><title>Go</title>
|
||||||
|
|
||||||
<para>The function <varname>buildGoPackage</varname> builds
|
<para>The function <varname>buildGoPackage</varname> builds
|
||||||
standard Go packages.
|
standard Go packages.
|
||||||
|
@ -787,7 +787,7 @@ done
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="ssec-language-java"><title>Java</title>
|
<section xml:id="sec-language-java"><title>Java</title>
|
||||||
|
|
||||||
<para>Ant-based Java packages are typically built from source as follows:
|
<para>Ant-based Java packages are typically built from source as follows:
|
||||||
|
|
||||||
|
@ -868,7 +868,7 @@ Runtime) instead of the OpenJRE.</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="ssec-language-lua"><title>Lua</title>
|
<section xml:id="sec-language-lua"><title>Lua</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Lua packages are built by the <varname>buildLuaPackage</varname> function. This function is
|
Lua packages are built by the <varname>buildLuaPackage</varname> function. This function is
|
||||||
|
@ -915,7 +915,7 @@ fileSystem = buildLuaPackage {
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="ssec-language-coq"><title>Coq</title>
|
<section xml:id="sec-language-coq"><title>Coq</title>
|
||||||
<para>
|
<para>
|
||||||
Coq libraries should be installed in
|
Coq libraries should be installed in
|
||||||
<literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>.
|
<literal>$(out)/lib/coq/${coq.coq-version}/user-contrib/</literal>.
|
||||||
|
|
|
@ -82,7 +82,8 @@ hello-2.3 A program that produces a familiar, friendly greeting
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Standard meta-attributes</title>
|
<section xml:id="sec-standard-meta-attributes"><title>Standard
|
||||||
|
meta-attributes</title>
|
||||||
|
|
||||||
<para>It is expected that each meta-attribute is one of the following:</para>
|
<para>It is expected that each meta-attribute is one of the following:</para>
|
||||||
|
|
||||||
|
|
|
@ -141,7 +141,7 @@ $ make menuconfig ARCH=<replaceable>arch</replaceable></screen>
|
||||||
|
|
||||||
<!--============================================================-->
|
<!--============================================================-->
|
||||||
|
|
||||||
<section>
|
<section xml:id="sec-xorg">
|
||||||
|
|
||||||
<title>X.org</title>
|
<title>X.org</title>
|
||||||
|
|
||||||
|
|
|
@ -67,7 +67,8 @@
|
||||||
<filename>lib/licenses.nix</filename> of the nix package tree.
|
<filename>lib/licenses.nix</filename> of the nix package tree.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<section><title>Modify packages via <literal>packageOverrides</literal></title>
|
<section xml:id="sec-modify-via-packageOverrides"><title>Modify
|
||||||
|
packages via <literal>packageOverrides</literal></title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
|
||||||
|
|
|
@ -15,7 +15,8 @@ environment does everything automatically. If
|
||||||
can easily customise or override the various build phases.</para>
|
can easily customise or override the various build phases.</para>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Using <literal>stdenv</literal></title>
|
<section xml:id="sec-using-stdenv"><title>Using
|
||||||
|
<literal>stdenv</literal></title>
|
||||||
|
|
||||||
<para>To build a package with the standard environment, you use the
|
<para>To build a package with the standard environment, you use the
|
||||||
function <varname>stdenv.mkDerivation</varname>, instead of the
|
function <varname>stdenv.mkDerivation</varname>, instead of the
|
||||||
|
@ -124,7 +125,8 @@ genericBuild
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Tools provided by <literal>stdenv</literal></title>
|
<section xml:id="sec-tools-of-stdenv"><title>Tools provided by
|
||||||
|
<literal>stdenv</literal></title>
|
||||||
|
|
||||||
<para>The standard environment provides the following packages:
|
<para>The standard environment provides the following packages:
|
||||||
|
|
||||||
|
@ -225,7 +227,7 @@ genericBuild
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section xml:id="ssec-stdenv-phases"><title>Phases</title>
|
<section xml:id="sec-stdenv-phases"><title>Phases</title>
|
||||||
|
|
||||||
<para>The generic builder has a number of <emphasis>phases</emphasis>.
|
<para>The generic builder has a number of <emphasis>phases</emphasis>.
|
||||||
Package builds are split into phases to make it easier to override
|
Package builds are split into phases to make it easier to override
|
||||||
|
@ -243,7 +245,8 @@ is convenient to override a phase from the derivation, while the
|
||||||
latter is convenient from a build script.</para>
|
latter is convenient from a build script.</para>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Controlling phases</title>
|
<section xml:id="ssec-controlling-phases"><title>Controlling
|
||||||
|
phases</title>
|
||||||
|
|
||||||
<para>There are a number of variables that control what phases are
|
<para>There are a number of variables that control what phases are
|
||||||
executed and in what order:
|
executed and in what order:
|
||||||
|
@ -327,7 +330,7 @@ executed and in what order:
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The unpack phase</title>
|
<section xml:id="ssec-unpack-phase"><title>The unpack phase</title>
|
||||||
|
|
||||||
<para>The unpack phase is responsible for unpacking the source code of
|
<para>The unpack phase is responsible for unpacking the source code of
|
||||||
the package. The default implementation of
|
the package. The default implementation of
|
||||||
|
@ -434,7 +437,7 @@ Additional file types can be supported by setting the
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The patch phase</title>
|
<section xml:id="ssec-patch-phase"><title>The patch phase</title>
|
||||||
|
|
||||||
<para>The patch phase applies the list of patches defined in the
|
<para>The patch phase applies the list of patches defined in the
|
||||||
<varname>patches</varname> variable.</para>
|
<varname>patches</varname> variable.</para>
|
||||||
|
@ -477,7 +480,7 @@ Additional file types can be supported by setting the
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The configure phase</title>
|
<section xml:id="ssec-configure-phase"><title>The configure phase</title>
|
||||||
|
|
||||||
<para>The configure phase prepares the source tree for building. The
|
<para>The configure phase prepares the source tree for building. The
|
||||||
default <function>configurePhase</function> runs
|
default <function>configurePhase</function> runs
|
||||||
|
@ -573,7 +576,7 @@ script) if it exists.</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The build phase</title>
|
<section xml:id="build-phase"><title>The build phase</title>
|
||||||
|
|
||||||
<para>The build phase is responsible for actually building the package
|
<para>The build phase is responsible for actually building the package
|
||||||
(e.g. compiling it). The default <function>buildPhase</function>
|
(e.g. compiling it). The default <function>buildPhase</function>
|
||||||
|
@ -657,7 +660,7 @@ called, respectively.</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The check phase</title>
|
<section xml:id="ssec-check-phase"><title>The check phase</title>
|
||||||
|
|
||||||
<para>The check phase checks whether the package was built correctly
|
<para>The check phase checks whether the package was built correctly
|
||||||
by running its test suite. The default
|
by running its test suite. The default
|
||||||
|
@ -717,7 +720,7 @@ doCheck = true;</programlisting>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The install phase</title>
|
<section xml:id="ssec-install-phase"><title>The install phase</title>
|
||||||
|
|
||||||
<para>The install phase is responsible for installing the package in
|
<para>The install phase is responsible for installing the package in
|
||||||
the Nix store under <envar>out</envar>. The default
|
the Nix store under <envar>out</envar>. The default
|
||||||
|
@ -772,7 +775,7 @@ installTargets = "install-bin install-doc";</programlisting>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The fixup phase</title>
|
<section xml:id="ssec-fixup-phase"><title>The fixup phase</title>
|
||||||
|
|
||||||
<para>The fixup phase performs some (Nix-specific) post-processing
|
<para>The fixup phase performs some (Nix-specific) post-processing
|
||||||
actions on the files installed under <filename>$out</filename> by the
|
actions on the files installed under <filename>$out</filename> by the
|
||||||
|
@ -895,7 +898,8 @@ following:
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>The distribution phase</title>
|
<section xml:id="ssec-distribution-phase"><title>The distribution
|
||||||
|
phase</title>
|
||||||
|
|
||||||
<para>The distribution phase is intended to produce a source
|
<para>The distribution phase is intended to produce a source
|
||||||
distribution of the package. The default
|
distribution of the package. The default
|
||||||
|
@ -1199,7 +1203,7 @@ echo @foo@
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<section><title>Purity in Nixpkgs</title>
|
<section xml:id="sec-purity-in-nixpkgs"><title>Purity in Nixpkgs</title>
|
||||||
|
|
||||||
<para>[measures taken to prevent dependencies on packages outside the
|
<para>[measures taken to prevent dependencies on packages outside the
|
||||||
store, and what you can do to prevent them]</para>
|
store, and what you can do to prevent them]</para>
|
||||||
|
|
Loading…
Reference in a new issue