<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’t 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 <?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. 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>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>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 <alice@example.org>" "Bob <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 won’t 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 it’s 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 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> </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, 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>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>