doc/meta.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook"
   2          xmlns:xlink="http://www.w3.org/1999/xlink"
   3          xml:id="chap-meta">
   4
   5 <title>Meta-attributes</title>
   6
   7 <para>Nix packages can declare <emphasis>meta-attributes</emphasis>
   8 that contain information about a package such as a description, its
   9 homepage, its license, and so on.  For instance, the GNU Hello package
  10 has a <varname>meta</varname> declaration like this:
  11
  12 <programlisting>
  13 meta = {
  14   description = "A program that produces a familiar, friendly greeting";
  15   longDescription = ''
  16     GNU Hello is a program that prints "Hello, world!" when you run it.
  17     It is fully customizable.
  18   '';
  19   homepage = http://www.gnu.org/software/hello/manual/;
  20   license = "GPLv3+";
  21 };
  22 </programlisting>
  23
  24 </para>
  25
  26 <para>Meta-attributes are not passed to the builder of the package.
  27 Thus, a change to a meta-attribute doesn’t trigger a recompilation of
  28 the package.  The value of a meta-attribute must a string.</para>
  29
  30 <para>The meta-attributes of a package can be queried from the
  31 command-line using <command>nix-env</command>:
  32
  33 <screen>
  34 $ nix-env -qa hello --meta --xml
  35 &lt;?xml version='1.0' encoding='utf-8'?>
  36 &lt;items>
  37   &lt;item attrPath="hello" name="hello-2.3" system="i686-linux">
  38     &lt;meta name="description" value="A program that produces a familiar, friendly greeting" />
  39     &lt;meta name="homepage" value="http://www.gnu.org/software/hello/manual/" />
  40     &lt;meta name="license" value="GPLv3+" />
  41     &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;" />
  42   &lt;/item>
  43 &lt;/items>
  44 </screen>
  45
  46 <command>nix-env</command> knows about the
  47 <varname>description</varname> field specifically:
  48
  49 <screen>
  50 $ nix-env -qa hello --description
  51 hello-2.3  A program that produces a familiar, friendly greeting
  52 </screen>
  53
  54 </para>
  55
  56
  57 <section><title>Standard meta-attributes</title>
  58
  59 <para>The following meta-attributes have a standard
  60 interpretation:</para>
  61
  62 <variablelist>
  63
  64   <varlistentry>
  65     <term><varname>description</varname></term>
  66     <listitem><para>A short (one-line) description of the package.
  67     This is shown by <command>nix-env -q --description</command> and
  68     also on the Nixpkgs release pages.</para>
  69
  70     <para>Don’t include a period at the end.  Don’t include newline
  71     characters.  Capitalise the first character.  For brevity, don’t
  72     repeat the name of package — just describe what it does.</para>
  73
  74     <para>Wrong: <literal>"libpng is a library that allows you to decode PNG images."</literal></para>
  75
  76     <para>Right: <literal>"A library for decoding PNG images"</literal></para>
  77
  78     </listitem>
  79   </varlistentry>
  80
  81   <varlistentry>
  82     <term><varname>longDescription</varname></term>
  83     <listitem><para>An arbitrarily long description of the
  84     package.</para></listitem>
  85   </varlistentry>
  86
  87   <varlistentry>
  88     <term><varname>homepage</varname></term>
  89     <listitem><para>The package’s homepage.  Example:
  90     <literal>http://www.gnu.org/software/hello/manual/</literal></para></listitem>
  91   </varlistentry>
  92
  93   <varlistentry>
  94     <term><varname>license</varname></term>
  95     <listitem><para>The license for the package.  See below for the
  96     allowed values.</para></listitem>
  97   </varlistentry>
  98
  99   <varlistentry>
 100     <term><varname>maintainers</varname></term>
 101     <listitem><para>A list of names and e-mail addresses of the
 102     maintainers of this Nix expression, e.g. <literal>["Alice
 103     &lt;alice@example.org>" "Bob &lt;bob@example.com>"]</literal>.  If
 104     you are the maintainer of multiple packages, you may want to add
 105     yourself to <link
 106     xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/lib/maintainers.nix"><filename>pkgs/lib/maintainers.nix</filename></link>
 107     and write something like <literal>[stdenv.lib.maintainers.alice
 108     stdenv.lib.maintainers.bob]</literal>.</para></listitem>
 109   </varlistentry>
 110
 111   <varlistentry>
 112     <term><varname>priority</varname></term>
 113     <listitem><para>The <emphasis>priority</emphasis> of the package,
 114     used by <command>nix-env</command> to resolve file name conflicts
 115     between packages.  See the Nix manual page for
 116     <command>nix-env</command> for details.  Example:
 117     <literal>"10"</literal> (a low-priority
 118     package).</para></listitem>
 119   </varlistentry>
 120
 121 </variablelist>
 122
 123
 124 </section>
 125
 126
 127 <section xml:id="sec-meta-license"><title>Licenses</title>
 128
 129 <note><para>This is just a first attempt at standardising the license
 130 attribute.</para></note>
 131
 132 <para>The <varname>meta.license</varname> attribute must be one of the
 133 following:
 134
 135 <variablelist>
 136
 137   <varlistentry>
 138     <term><varname>GPL</varname></term>
 139     <listitem><para>GNU General Public License; version not
 140     specified.</para></listitem>
 141   </varlistentry>
 142
 143   <varlistentry>
 144     <term><varname>GPLv2</varname></term>
 145     <listitem><para>GNU General Public License, version
 146     2.</para></listitem>
 147   </varlistentry>
 148
 149   <varlistentry>
 150     <term><varname>GPLv2+</varname></term>
 151     <listitem><para>GNU General Public License, version
 152     2 or higher.</para></listitem>
 153   </varlistentry>
 154
 155   <varlistentry>
 156     <term><varname>GPLv3</varname></term>
 157     <listitem><para>GNU General Public License, version
 158     3.</para></listitem>
 159   </varlistentry>
 160
 161   <varlistentry>
 162     <term><varname>GPLv3+</varname></term>
 163     <listitem><para>GNU General Public License, version
 164     3 or higher.</para></listitem>
 165   </varlistentry>
 166
 167   <varlistentry>
 168     <term><varname>bsd</varname></term>
 169     <listitem><para>Catch-all for licenses that are essentially
 170     similar to <link
 171     xlink:href="http://www.gnu.org/licenses/license-list.html#ModifiedBSD">the
 172     original BSD license with the advertising clause removed</link>,
 173     i.e. permissive non-copyleft free software licenses.  This
 174     includes the <link
 175     xlink:href="http://www.gnu.org/licenses/license-list.html#X11License">X11
 176     (“MIT”) License</link>.</para></listitem>
 177   </varlistentry>
 178
 179   <varlistentry>
 180     <term><varname>free</varname></term>
 181     <listitem><para>Catch-all for free software licenses not listed
 182     above.</para></listitem>
 183   </varlistentry>
 184
 185   <varlistentry>
 186     <term><varname>free-copyleft</varname></term>
 187     <listitem><para>Catch-all for free, copyleft software licenses not
 188     listed above.</para></listitem>
 189   </varlistentry>
 190
 191   <varlistentry>
 192     <term><varname>free-non-copyleft</varname></term>
 193     <listitem><para>Catch-all for free, non-copyleft software licenses
 194     not listed above.</para></listitem>
 195   </varlistentry>
 196
 197   <varlistentry>
 198     <term><varname>unfree-redistributable</varname></term>
 199     <listitem><para>Unfree package that can be redistributed in binary
 200     form.  That is, it’s legal to redistribute the
 201     <emphasis>output</emphasis> of the derivation.  This means that
 202     the package can be included in the Nixpkgs
 203     channel.</para>
 204
 205     <para>Sometimes proprietary software can only be redistributed
 206     unmodified.  Make sure the builder doesn’t actually modify the
 207     original binaries; otherwise we’re breaking the license.  For
 208     instance, the NVIDIA X11 drivers can be redistributed unmodified,
 209     but our builder applies <command>patchelf</command> to make them
 210     work.  Thus, its license is <varname>unfree</varname> and it
 211     cannot be included in the Nixpkgs channel.</para></listitem>
 212   </varlistentry>
 213
 214   <varlistentry>
 215     <term><varname>unfree</varname></term>
 216     <listitem><para>Unfree package that cannot be redistributed.  You
 217     can build it yourself, but you cannot redistribute the output of
 218     the derivation.  Thus it cannot be included in the Nixpkgs
 219     channel.</para></listitem>
 220   </varlistentry>
 221
 222   <varlistentry>
 223     <term><varname>unfree-redistributable-firmware</varname></term>
 224     <listitem><para>This package supplies unfree, redistributable
 225     firmware.  This is a separate value from
 226     <varname>unfree-redistributable</varname> because not everybody
 227     cares whether firmware is free.</para></listitem>
 228   </varlistentry>
 229
 230 </variablelist>
 231
 232 </para>
 233
 234
 235 </section>
 236
 237
 238 </chapter>