nixpkgs/doc/meta.xml

<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 = stdenv.lib.licenses.gpl3Plus;
  maintainers = [ stdenv.lib.maintainers.eelco ];
  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 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=&apos;1.0&apos; encoding=&apos;utf-8&apos;?&gt;
&lt;items&gt;
  &lt;item attrPath=&quot;nixos.pkgs.hello&quot; name=&quot;hello-2.9&quot; system=&quot;x86_64-linux&quot;&gt;
    &lt;meta name=&quot;description&quot; type=&quot;string&quot; value=&quot;A program that produces a familiar, friendly greeting&quot; /&gt;
    &lt;meta name=&quot;homepage&quot; type=&quot;string&quot; value=&quot;http://www.gnu.org/software/hello/manual/&quot; /&gt;
    &lt;meta name=&quot;license&quot; type=&quot;string&quot; value=&quot;GPLv3+&quot; /&gt;
    &lt;meta name=&quot;longDescription&quot; type=&quot;string&quot; value=&quot;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;&quot; /&gt;
    &lt;meta name=&quot;maintainers&quot; type=&quot;strings&quot;&gt;
      &lt;string value=&quot;Ludovic Courtès &amp;lt;ludo@gnu.org&amp;gt;&quot; /&gt;
    &lt;/meta&gt;
    &lt;meta name=&quot;platforms&quot; type=&quot;strings&quot;&gt;
      &lt;string value=&quot;i686-linux&quot; /&gt;
      &lt;string value=&quot;x86_64-linux&quot; /&gt;
      &lt;string value=&quot;armv5tel-linux&quot; /&gt;
      &lt;string value=&quot;armv7l-linux&quot; /&gt;
      &lt;string value=&quot;mips64el-linux&quot; /&gt;
      &lt;string value=&quot;x86_64-darwin&quot; /&gt;
      &lt;string value=&quot;i686-cygwin&quot; /&gt;
      &lt;string value=&quot;i686-freebsd&quot; /&gt;
      &lt;string value=&quot;x86_64-freebsd&quot; /&gt;
      &lt;string value=&quot;i686-openbsd&quot; /&gt;
      &lt;string value=&quot;x86_64-openbsd&quot; /&gt;
    &lt;/meta&gt;
    &lt;meta name=&quot;position&quot; type=&quot;string&quot; value=&quot;/nix/store/cn8zjjdd9kvmp1p5d21h7ya0cr1jhkk3-nixos-14.10pre44264.12f06b3/nixos/nixpkgs/pkgs/applications/misc/hello/ex-2/default.nix:14&quot; /&gt;
  &lt;/item&gt;
&lt;/items&gt;

</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. One from attribute set defined in
      <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/licenses.nix">
      <filename>nixpkgs/lib/licenses.nix</filename></link>.
      Example:
      <literal>stdenv.lib.licenses.gpl3</literal>.</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
    xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/maintainers.nix"><filename>nixpkgs/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. An example is:

<programlisting>
meta.platforms = stdenv.lib.platforms.linux;
</programlisting>

    Attribute Set <varname>stdenv.lib.platforms</varname> in 
    <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/platforms.nix">
    <filename>nixpkgs/lib/platforms.nix</filename></link> defines various common
    lists 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>

</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>