2009-02-10 23:29:42 +00:00
<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 doesn’
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
< ?xml version='1.0' encoding='utf-8'?>
< items>
< item attrPath="hello" name="hello-2.3" system="i686-linux">
< meta name="description" value="A program that produces a familiar, friendly greeting" />
< meta name="homepage" value="http://www.gnu.org/software/hello/manual/" />
< meta name="license" value="GPLv3+" />
< meta name="longDescription" value="GNU Hello is a program that prints & quot;Hello, world!& quot; when you run it.& #xA;It is fully customizable.& #xA;" />
< /item>
< /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.
2009-03-03 13:47:46 +00:00
This is shown by <command > nix-env -q --description</command> and
also on the Nixpkgs release pages.</para>
<para > Don’ ’
characters. Capitalise the first character. For brevity, don’
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>
2009-02-10 23:29:42 +00:00
</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 package’
<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 > 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>
</variablelist>
</section>
<section > <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 > 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 > unfree-redistributable</varname> </term>
<listitem > <para > Unfree package that can be redistributed in binary
form. That is, it’
<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’
original binaries; otherwise we’
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>
