diff options
Diffstat (limited to 'doc/meta.xml')
| -rw-r--r-- | doc/meta.xml | 544 |
1 files changed, 294 insertions, 250 deletions
diff --git a/doc/meta.xml b/doc/meta.xml index 5dbe810810d1..ad16e7683f58 100644 --- a/doc/meta.xml +++ b/doc/meta.xml @@ -1,14 +1,12 @@ <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-meta"> - -<title>Meta-attributes</title> - -<para>Nix packages can declare <emphasis>meta-attributes</emphasis> -that contain information about a package such as a description, its -homepage, its license, and so on. For instance, the GNU Hello package -has a <varname>meta</varname> declaration like this: - + <title>Meta-attributes</title> + <para> + Nix packages can declare <emphasis>meta-attributes</emphasis> that contain + information about a package such as a description, its homepage, its license, + and so on. For instance, the GNU Hello package has a <varname>meta</varname> + declaration like this: <programlisting> meta = { description = "A program that produces a familiar, friendly greeting"; @@ -22,16 +20,15 @@ meta = { platforms = stdenv.lib.platforms.all; }; </programlisting> - -</para> - -<para>Meta-attributes are not passed to the builder of the package. -Thus, a change to a meta-attribute doesn’t trigger a recompilation of -the package. The value of a meta-attribute must be a string.</para> - -<para>The meta-attributes of a package can be queried from the -command-line using <command>nix-env</command>: - + </para> + <para> + Meta-attributes are not passed to the builder of the package. Thus, a change + to a meta-attribute doesn’t trigger a recompilation of the package. The + value of a meta-attribute must be a string. + </para> + <para> + The meta-attributes of a package can be queried from the command-line using + <command>nix-env</command>: <screen> $ nix-env -qa hello --json { @@ -70,252 +67,299 @@ $ nix-env -qa hello --json </screen> - -<command>nix-env</command> knows about the -<varname>description</varname> field specifically: - + <command>nix-env</command> knows about the <varname>description</varname> + field specifically: <screen> $ nix-env -qa hello --description hello-2.3 A program that produces a familiar, friendly greeting </screen> - -</para> - - -<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> - -<variablelist> - - <varlistentry> - <term><varname>description</varname></term> - <listitem><para>A short (one-line) description of the package. - This is shown by <command>nix-env -q --description</command> and - also on the Nixpkgs release pages.</para> - - <para>Don’t include a period at the end. Don’t include newline - characters. Capitalise the first character. For brevity, don’t - repeat the name of package — just describe what it does.</para> - - <para>Wrong: <literal>"libpng is a library that allows you to decode PNG images."</literal></para> - - <para>Right: <literal>"A library for decoding PNG images"</literal></para> - + </para> + <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> + + <variablelist> + <varlistentry> + <term><varname>description</varname> + </term> + <listitem> + <para> + A short (one-line) description of the package. This is shown by + <command>nix-env -q --description</command> and also on the Nixpkgs + release pages. + </para> + <para> + Don’t include a period at the end. Don’t include newline characters. + Capitalise the first character. For brevity, don’t repeat the name of + package — just describe what it does. + </para> + <para> + Wrong: <literal>"libpng is a library that allows you to decode PNG + images."</literal> + </para> + <para> + Right: <literal>"A library for decoding PNG images"</literal> + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>longDescription</varname></term> - <listitem><para>An arbitrarily long description of the - package.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>branch</varname></term> - <listitem><para>Release branch. Used to specify that a package is not - going to receive updates that are not in this branch; for example, Linux - kernel 3.0 is supposed to be updated to 3.0.X, not 3.1.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>homepage</varname></term> - <listitem><para>The package’s homepage. Example: - <literal>http://www.gnu.org/software/hello/manual/</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>downloadPage</varname></term> - <listitem><para>The page where a link to the current version can be found. Example: - <literal>http://ftp.gnu.org/gnu/hello/</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>license</varname></term> + </varlistentry> + <varlistentry> + <term><varname>longDescription</varname> + </term> <listitem> - <para> - The license, or licenses, for the package. One from the attribute set - defined in <link + <para> + An arbitrarily long description of the package. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>branch</varname> + </term> + <listitem> + <para> + Release branch. Used to specify that a package is not going to receive + updates that are not in this branch; for example, Linux kernel 3.0 is + supposed to be updated to 3.0.X, not 3.1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>homepage</varname> + </term> + <listitem> + <para> + The package’s homepage. Example: + <literal>http://www.gnu.org/software/hello/manual/</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>downloadPage</varname> + </term> + <listitem> + <para> + The page where a link to the current version can be found. Example: + <literal>http://ftp.gnu.org/gnu/hello/</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>license</varname> + </term> + <listitem> + <para> + The license, or licenses, for the package. One from the attribute set + defined in + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix"> - <filename>nixpkgs/lib/licenses.nix</filename></link>. At this moment - using both a list of licenses and a single license is valid. If the - license field is in the form of a list representation, then it means - that parts of the package are licensed differently. Each license - should preferably be referenced by their attribute. The non-list - attribute value can also be a space delimited string representation of - the contained attribute shortNames or spdxIds. The following are all valid - examples: - <itemizedlist> - <listitem><para>Single license referenced by attribute (preferred) - <literal>stdenv.lib.licenses.gpl3</literal>. - </para></listitem> - <listitem><para>Single license referenced by its attribute shortName (frowned upon) - <literal>"gpl3"</literal>. - </para></listitem> - <listitem><para>Single license referenced by its attribute spdxId (frowned upon) - <literal>"GPL-3.0"</literal>. - </para></listitem> - <listitem><para>Multiple licenses referenced by attribute (preferred) - <literal>with stdenv.lib.licenses; [ asl20 free ofl ]</literal>. - </para></listitem> - <listitem><para>Multiple licenses referenced as a space delimited string of attribute shortNames (frowned upon) - <literal>"asl20 free ofl"</literal>. - </para></listitem> - </itemizedlist> - For details, see <xref linkend='sec-meta-license'/>. - </para> + <filename>nixpkgs/lib/licenses.nix</filename></link>. At this moment + using both a list of licenses and a single license is valid. If the + license field is in the form of a list representation, then it means that + parts of the package are licensed differently. Each license should + preferably be referenced by their attribute. The non-list attribute value + can also be a space delimited string representation of the contained + attribute shortNames or spdxIds. The following are all valid examples: + <itemizedlist> + <listitem> + <para> + Single license referenced by attribute (preferred) + <literal>stdenv.lib.licenses.gpl3</literal>. + </para> + </listitem> + <listitem> + <para> + Single license referenced by its attribute shortName (frowned upon) + <literal>"gpl3"</literal>. + </para> + </listitem> + <listitem> + <para> + Single license referenced by its attribute spdxId (frowned upon) + <literal>"GPL-3.0"</literal>. + </para> + </listitem> + <listitem> + <para> + Multiple licenses referenced by attribute (preferred) <literal>with + stdenv.lib.licenses; [ asl20 free ofl ]</literal>. + </para> + </listitem> + <listitem> + <para> + Multiple licenses referenced as a space delimited string of attribute + shortNames (frowned upon) <literal>"asl20 free ofl"</literal>. + </para> + </listitem> + </itemizedlist> + For details, see <xref linkend='sec-meta-license'/>. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>maintainers</varname></term> - <listitem><para>A list of names and e-mail addresses of the - maintainers of this Nix expression. If - you would like to be a maintainer of a package, you may want to add - yourself to <link + </varlistentry> + <varlistentry> + <term><varname>maintainers</varname> + </term> + <listitem> + <para> + A list of names and e-mail addresses of the maintainers of this Nix + expression. If you would like to be a maintainer of a package, you may + want to add yourself to + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix"><filename>nixpkgs/maintainers/maintainer-list.nix</filename></link> - and write something like <literal>[ stdenv.lib.maintainers.alice - stdenv.lib.maintainers.bob ]</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>priority</varname></term> - <listitem><para>The <emphasis>priority</emphasis> of the package, - used by <command>nix-env</command> to resolve file name conflicts - between packages. See the Nix manual page for - <command>nix-env</command> for details. Example: - <literal>"10"</literal> (a low-priority - package).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>platforms</varname></term> - <listitem><para>The list of Nix platform types on which the - package is supported. Hydra builds packages according to the - platform specified. If no platform is specified, the package does - not have prebuilt binaries. An example is: - + and write something like <literal>[ stdenv.lib.maintainers.alice + stdenv.lib.maintainers.bob ]</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>priority</varname> + </term> + <listitem> + <para> + The <emphasis>priority</emphasis> of the package, used by + <command>nix-env</command> to resolve file name conflicts between + packages. See the Nix manual page for <command>nix-env</command> for + details. Example: <literal>"10"</literal> (a low-priority package). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>platforms</varname> + </term> + <listitem> + <para> + The list of Nix platform types on which the package is supported. Hydra + builds packages according to the platform specified. If no platform is + specified, the package does not have prebuilt binaries. An example is: <programlisting> meta.platforms = stdenv.lib.platforms.linux; </programlisting> - - Attribute Set <varname>stdenv.lib.platforms</varname> defines - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix"> - various common lists</link> of platforms types.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>hydraPlatforms</varname></term> - <listitem><para>The list of Nix platform types for which the Hydra - instance at <literal>hydra.nixos.org</literal> will build the - package. (Hydra is the Nix-based continuous build system.) It - defaults to the value of <varname>meta.platforms</varname>. Thus, - the only reason to set <varname>meta.hydraPlatforms</varname> is - if you want <literal>hydra.nixos.org</literal> to build the - package on a subset of <varname>meta.platforms</varname>, or not - at all, e.g. - + Attribute Set <varname>stdenv.lib.platforms</varname> defines + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix"> + various common lists</link> of platforms types. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>hydraPlatforms</varname> + </term> + <listitem> + <para> + The list of Nix platform types for which the Hydra instance at + <literal>hydra.nixos.org</literal> will build the package. (Hydra is the + Nix-based continuous build system.) It defaults to the value of + <varname>meta.platforms</varname>. Thus, the only reason to set + <varname>meta.hydraPlatforms</varname> is if you want + <literal>hydra.nixos.org</literal> to build the package on a subset of + <varname>meta.platforms</varname>, or not at all, e.g. <programlisting> meta.platforms = stdenv.lib.platforms.linux; meta.hydraPlatforms = []; </programlisting> - - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>broken</varname></term> - <listitem><para>If set to <literal>true</literal>, the package is - marked as “broken”, meaning that it won’t show up in - <literal>nix-env -qa</literal>, and cannot be built or installed. - Such packages should be removed from Nixpkgs eventually unless - they are fixed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>updateWalker</varname></term> - <listitem><para>If set to <literal>true</literal>, the package is - tested to be updated correctly by the <literal>update-walker.sh</literal> - script without additional settings. Such packages have - <varname>meta.version</varname> set and their homepage (or - the page specified by <varname>meta.downloadPage</varname>) contains - a direct link to the package tarball.</para></listitem> - </varlistentry> - -</variablelist> - - -</section> - - -<section xml:id="sec-meta-license"><title>Licenses</title> - -<para>The <varname>meta.license</varname> attribute should preferrably contain -a value from <varname>stdenv.lib.licenses</varname> defined in -<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix"> -<filename>nixpkgs/lib/licenses.nix</filename></link>, -or in-place license description of the same format if the license is -unlikely to be useful in another expression.</para> - -<para>Although it's typically better to indicate the specific license, -a few generic options are available: - -<variablelist> - - <varlistentry> - <term><varname>stdenv.lib.licenses.free</varname>, - <varname>"free"</varname></term> - - <listitem><para>Catch-all for free software licenses not listed - above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>stdenv.lib.licenses.unfreeRedistributable</varname>, - <varname>"unfree-redistributable"</varname></term> - - <listitem><para>Unfree package that can be redistributed in binary - form. That is, it’s legal to redistribute the - <emphasis>output</emphasis> of the derivation. This means that - the package can be included in the Nixpkgs - channel.</para> - - <para>Sometimes proprietary software can only be redistributed - unmodified. Make sure the builder doesn’t actually modify the - original binaries; otherwise we’re breaking the license. For - instance, the NVIDIA X11 drivers can be redistributed unmodified, - but our builder applies <command>patchelf</command> to make them - work. Thus, its license is <varname>"unfree"</varname> and it - cannot be included in the Nixpkgs channel.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>stdenv.lib.licenses.unfree</varname>, - <varname>"unfree"</varname></term> - - <listitem><para>Unfree package that cannot be redistributed. You - can build it yourself, but you cannot redistribute the output of - the derivation. Thus it cannot be included in the Nixpkgs - channel.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, - <varname>"unfree-redistributable-firmware"</varname></term> - - <listitem><para>This package supplies unfree, redistributable - firmware. This is a separate value from - <varname>unfree-redistributable</varname> because not everybody - cares whether firmware is free.</para></listitem> - </varlistentry> - -</variablelist> - -</para> - - -</section> - - + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>broken</varname> + </term> + <listitem> + <para> + If set to <literal>true</literal>, the package is marked as “broken”, + meaning that it won’t show up in <literal>nix-env -qa</literal>, and + cannot be built or installed. Such packages should be removed from + Nixpkgs eventually unless they are fixed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>updateWalker</varname> + </term> + <listitem> + <para> + If set to <literal>true</literal>, the package is tested to be updated + correctly by the <literal>update-walker.sh</literal> script without + additional settings. Such packages have <varname>meta.version</varname> + set and their homepage (or the page specified by + <varname>meta.downloadPage</varname>) contains a direct link to the + package tarball. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section xml:id="sec-meta-license"> + <title>Licenses</title> + + <para> + The <varname>meta.license</varname> attribute should preferrably contain a + value from <varname>stdenv.lib.licenses</varname> defined in + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix"> + <filename>nixpkgs/lib/licenses.nix</filename></link>, or in-place license + description of the same format if the license is unlikely to be useful in + another expression. + </para> + + <para> + Although it's typically better to indicate the specific license, a few + generic options are available: + <variablelist> + <varlistentry> + <term><varname>stdenv.lib.licenses.free</varname>, + <varname>"free"</varname> + </term> + <listitem> + <para> + Catch-all for free software licenses not listed above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>stdenv.lib.licenses.unfreeRedistributable</varname>, + <varname>"unfree-redistributable"</varname> + </term> + <listitem> + <para> + Unfree package that can be redistributed in binary form. That is, it’s + legal to redistribute the <emphasis>output</emphasis> of the derivation. + This means that the package can be included in the Nixpkgs channel. + </para> + <para> + Sometimes proprietary software can only be redistributed unmodified. + Make sure the builder doesn’t actually modify the original binaries; + otherwise we’re breaking the license. For instance, the NVIDIA X11 + drivers can be redistributed unmodified, but our builder applies + <command>patchelf</command> to make them work. Thus, its license is + <varname>"unfree"</varname> and it cannot be included in the Nixpkgs + channel. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>stdenv.lib.licenses.unfree</varname>, + <varname>"unfree"</varname> + </term> + <listitem> + <para> + Unfree package that cannot be redistributed. You can build it yourself, + but you cannot redistribute the output of the derivation. Thus it cannot + be included in the Nixpkgs channel. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, + <varname>"unfree-redistributable-firmware"</varname> + </term> + <listitem> + <para> + This package supplies unfree, redistributable firmware. This is a + separate value from <varname>unfree-redistributable</varname> because + not everybody cares whether firmware is free. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> </chapter> |