nixpkgs/doc/meta.xml
Eelco Dolstra a2cbc77e4f Only show/build a package on the platforms listed in meta.platforms
The function ‘mkDerivation’ now checks whether the current platform
type is included in a package's meta.platform field.  If not, it
throws an exception:

  $ nix-build -A linux --argstr system x86_64-darwin
  error: user-thrown exception: the package ‘linux-3.10.15’ is not supported on ‘x86_64-darwin’

These packages also no longer show up in ‘nix-env -qa’ output.  This
means, for instance, that the number of packages shown on
x86_64-freebsd has dropped from 9268 to 4764.

Since meta.platforms was also used to prevent Hydra from building some
packages, there now is a new attribute meta.hydraPlatforms listing the
platforms on which Hydra should build the package (which defaults to
meta.platforms).
2013-11-05 00:06:10 +01:00

295 lines
9.9 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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:
<programlisting>
meta = {
description = "A program that produces a familiar, friendly greeting";
longDescription = ''
GNU Hello is a program that prints "Hello, world!" when you run it.
It is fully customizable.
'';
homepage = http://www.gnu.org/software/hello/manual/;
license = "GPLv3+";
};
</programlisting>
</para>
<para>Meta-attributes are not passed to the builder of the package.
Thus, a change to a meta-attribute doesnt trigger a recompilation of
the package. The value of a meta-attribute must 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 --meta --xml
&lt;?xml version='1.0' encoding='utf-8'?>
&lt;items>
&lt;item attrPath="hello" name="hello-2.3" system="i686-linux">
&lt;meta name="description" value="A program that produces a familiar, friendly greeting" />
&lt;meta name="homepage" value="http://www.gnu.org/software/hello/manual/" />
&lt;meta name="license" value="GPLv3+" />
&lt;meta name="longDescription" value="GNU Hello is a program that prints &amp;quot;Hello, world!&amp;quot; when you run it.&amp;#xA;It is fully customizable.&amp;#xA;" />
&lt;/item>
&lt;/items>
</screen>
<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><title>Standard meta-attributes</title>
<para>The following meta-attributes have a standard
interpretation:</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>Dont include a period at the end. Dont include newline
characters. Capitalise the first character. For brevity, dont
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>homepage</varname></term>
<listitem><para>The packages homepage. Example:
<literal>http://www.gnu.org/software/hello/manual/</literal></para></listitem>
</varlistentry>
<varlistentry>
<term><varname>license</varname></term>
<listitem><para>The license for the package. See below for the
allowed values.</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, e.g. <literal>["Alice
&lt;alice@example.org>" "Bob &lt;bob@example.com>"]</literal>. If
you are the maintainer of multiple packages, you may want to add
yourself to <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/maintainers.nix"><filename>pkgs/lib/maintainers.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. If this attribute is set, the package will
refuse to build, and wont show up in <literal>nix-env
-qa</literal> output, on any platform not listed
here. An example is:
<programlisting>
meta.platforms = [ "x86_64-linux" "i686-linux" "x86_64-darwin" ];
</programlisting>
The set <varname>lib.platforms</varname> defines various common
lists of platforms types, so its more typical to write:
<programlisting>
meta.platforms = stdenv.lib.platforms.linux ++ stdenv.lib.platforms.darwin;
</programlisting>
</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> should 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 wont show up in
<literal>nix-env -qa</literal>, and cannot be built or installed.
Sush packages should be removed from Nixpkgs eventually unless
they are fixed.</para></listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="sec-meta-license"><title>Licenses</title>
<note><para>This is just a first attempt at standardising the license
attribute.</para></note>
<para>The <varname>meta.license</varname> attribute must be one of the
following:
<variablelist>
<varlistentry>
<term><varname>GPL</varname></term>
<listitem><para>GNU General Public License; version not
specified.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>GPLv2</varname></term>
<listitem><para>GNU General Public License, version
2.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>GPLv2+</varname></term>
<listitem><para>GNU General Public License, version
2 or higher.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>GPLv3</varname></term>
<listitem><para>GNU General Public License, version
3.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>GPLv3+</varname></term>
<listitem><para>GNU General Public License, version
3 or higher.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>bsd</varname></term>
<listitem><para>Catch-all for licenses that are essentially
similar to <link
xlink:href="http://www.gnu.org/licenses/license-list.html#ModifiedBSD">the
original BSD license with the advertising clause removed</link>,
i.e. permissive non-copyleft free software licenses. This
includes the <link
xlink:href="http://www.gnu.org/licenses/license-list.html#X11License">X11
(“MIT”) License</link>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>perl5</varname></term>
<listitem><para>The Perl 5 license (Artistic License, version 1
and GPL, version 1 or later).</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>free</varname></term>
<listitem><para>Catch-all for free software licenses not listed
above.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>free-copyleft</varname></term>
<listitem><para>Catch-all for free, copyleft software licenses not
listed above.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>free-non-copyleft</varname></term>
<listitem><para>Catch-all for free, non-copyleft software licenses
not listed above.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>unfree-redistributable</varname></term>
<listitem><para>Unfree package that can be redistributed in binary
form. That is, its 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 doesnt actually modify the
original binaries; otherwise were 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>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>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>