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>priority</varname></term>
 101     <listitem><para>The <emphasis>priority</emphasis> of the package,
 102     used by <command>nix-env</command> to resolve file name conflicts
 103     between packages.  See the Nix manual page for
 104     <command>nix-env</command> for details.  Example:
 105     <literal>"10"</literal> (a low-priority
 106     package).</para></listitem>
 107   </varlistentry>
 108
 109 </variablelist>
 110
 111
 112 </section>
 113
 114
 115 <section><title>Licenses</title>
 116
 117 <note><para>This is just a first attempt at standardising the license
 118 attribute.</para></note>
 119
 120 <para>The <varname>meta.license</varname> attribute must be one of the
 121 following:
 122
 123 <variablelist>
 124
 125   <varlistentry>
 126     <term><varname>GPL</varname></term>
 127     <listitem><para>GNU General Public License; version not
 128     specified.</para></listitem>
 129   </varlistentry>
 130
 131   <varlistentry>
 132     <term><varname>GPLv2</varname></term>
 133     <listitem><para>GNU General Public License, version
 134     2.</para></listitem>
 135   </varlistentry>
 136
 137   <varlistentry>
 138     <term><varname>GPLv2+</varname></term>
 139     <listitem><para>GNU General Public License, version
 140     2 or higher.</para></listitem>
 141   </varlistentry>
 142
 143   <varlistentry>
 144     <term><varname>GPLv3</varname></term>
 145     <listitem><para>GNU General Public License, version
 146     3.</para></listitem>
 147   </varlistentry>
 148
 149   <varlistentry>
 150     <term><varname>GPLv3+</varname></term>
 151     <listitem><para>GNU General Public License, version
 152     3 or higher.</para></listitem>
 153   </varlistentry>
 154
 155   <varlistentry>
 156     <term><varname>free</varname></term>
 157     <listitem><para>Catch-all for free software licenses not listed
 158     above.</para></listitem>
 159   </varlistentry>
 160
 161   <varlistentry>
 162     <term><varname>free-copyleft</varname></term>
 163     <listitem><para>Catch-all for free, copyleft software licenses not
 164     listed above.</para></listitem>
 165   </varlistentry>
 166
 167   <varlistentry>
 168     <term><varname>unfree-redistributable</varname></term>
 169     <listitem><para>Unfree package that can be redistributed in binary
 170     form.  That is, it’s legal to redistribute the
 171     <emphasis>output</emphasis> of the derivation.  This means that
 172     the package can be included in the Nixpkgs
 173     channel.</para>
 174
 175     <para>Sometimes proprietary software can only be redistributed
 176     unmodified.  Make sure the builder doesn’t actually modify the
 177     original binaries; otherwise we’re breaking the license.  For
 178     instance, the NVIDIA X11 drivers can be redistributed unmodified,
 179     but our builder applies <command>patchelf</command> to make them
 180     work.  Thus, its license is <varname>unfree</varname> and it
 181     cannot be included in the Nixpkgs channel.</para></listitem>
 182   </varlistentry>
 183
 184   <varlistentry>
 185     <term><varname>unfree</varname></term>
 186     <listitem><para>Unfree package that cannot be redistributed.  You
 187     can build it yourself, but you cannot redistribute the output of
 188     the derivation.  Thus it cannot be included in the Nixpkgs
 189     channel.</para></listitem>
 190   </varlistentry>
 191
 192   <varlistentry>
 193     <term><varname>unfree-redistributable-firmware</varname></term>
 194     <listitem><para>This package supplies unfree, redistributable
 195     firmware.  This is a separate value from
 196     <varname>unfree-redistributable</varname> because not everybody
 197     cares whether firmware is free.</para></listitem>
 198   </varlistentry>
 199
 200 </variablelist>
 201
 202 </para>
 203
 204
 205 </section>
 206
 207
 208 </chapter>