summary refs log tree commit diff
path: root/doc/meta.xml
blob: b1ffd0502b2b50a732b7f839cc9ac8a48cb333e4 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
<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 be 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 --json
{
    "hello": {
        "meta": {
            "description": "A program that produces a familiar, friendly greeting",
            "homepage": "http://www.gnu.org/software/hello/manual/",
            "license": {
                "fullName": "GNU General Public License version 3 or later",
                "shortName": "GPLv3+",
                "url": "http://www.fsf.org/licensing/licenses/gpl.html"
            },
            "longDescription": "GNU Hello is a program that prints \"Hello, world!\" when you run it.\nIt is fully customizable.\n",
            "maintainers": [
                "Ludovic Court\u00e8s &lt;ludo@gnu.org>"
            ],
            "platforms": [
                "i686-linux",
                "x86_64-linux",
                "armv5tel-linux",
                "armv7l-linux",
                "mips64el-linux",
                "x86_64-darwin",
                "i686-cygwin",
                "i686-freebsd",
                "x86_64-freebsd",
                "i686-openbsd",
                "x86_64-openbsd"
            ],
            "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/default.nix:14"
        },
        "name": "hello-2.9",
        "system": "x86_64-linux"
    }
}


</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 xml:id="sec-standard-meta-attributes"><title>Standard
meta-attributes</title>

<para>It is expected that each meta-attribute is one of the following:</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>branch</varname></term>
    <listitem><para>Release branch. Used to specify that a package is not
    going to receive updates that are not in this branch; for example, Linux
    kernel 3.0 is supposed to be updated to 3.0.X, not 3.1.</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>downloadPage</varname></term>
    <listitem><para>The page where a link to the current version can be found.  Example:
    <literal>http://ftp.gnu.org/gnu/hello/</literal></para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>license</varname></term>
    <listitem>
      <para>
        The license, or licenses, for the package. One from the attribute set
        defined in <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
          <filename>nixpkgs/lib/licenses.nix</filename></link>. At this moment
        using both a list of licenses and a single license is valid. If the
        license field is in the form of a list representation, then it means
        that parts of the package are licensed differently.  Each license
        should preferably be referenced by their attribute. The non-list
        attribute value can also be a space delimited string representation of
        the contained attribute shortNames or spdxIds. The following are all valid
        examples:
        <itemizedlist>
          <listitem><para>Single license referenced by attribute (preferred)
              <literal>stdenv.lib.licenses.gpl3</literal>.
          </para></listitem>
          <listitem><para>Single license referenced by its attribute shortName (frowned upon)
              <literal>"gpl3"</literal>.
          </para></listitem>
          <listitem><para>Single license referenced by its attribute spdxId (frowned upon)
              <literal>"GPL-3.0"</literal>.
          </para></listitem>
          <listitem><para>Multiple licenses referenced by attribute (preferred)
              <literal>with stdenv.lib.licenses; [ asl20 free ofl ]</literal>.
          </para></listitem>
          <listitem><para>Multiple licenses referenced as a space delimited string of attribute shortNames (frowned upon)
              <literal>"asl20 free ofl"</literal>.
          </para></listitem>
        </itemizedlist>
        For details, see <xref linkend='sec-meta-license'/>.
      </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/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. Hydra builds packages according to the
    platform specified. If no platform is specified, the package does
    not have prebuilt binaries. 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/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>

  <varlistentry>
    <term><varname>updateWalker</varname></term>
    <listitem><para>If set to <literal>true</literal>, the package is
    tested to be updated correctly by the <literal>update-walker.sh</literal>
    script without additional settings. Such packages have
    <varname>meta.version</varname> set and their homepage (or
    the page specified by <varname>meta.downloadPage</varname>) contains
    a direct link to the package tarball.</para></listitem>
  </varlistentry>

</variablelist>


</section>


<section xml:id="sec-meta-license"><title>Licenses</title>

<para>The <varname>meta.license</varname> attribute should preferrably contain
a value from <varname>stdenv.lib.licenses</varname> defined in
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
<filename>nixpkgs/lib/licenses.nix</filename></link>,
or in-place license description of the same format if the license is
unlikely to be useful in another expression.</para>

<para>Although it's typically better to indicate the specific license,
a few generic options are available:

<variablelist>

  <varlistentry>
    <term><varname>stdenv.lib.licenses.free</varname>,
    <varname>"free"</varname></term>

    <listitem><para>Catch-all for free software licenses not listed
    above.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>stdenv.lib.licenses.unfreeRedistributable</varname>,
    <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>stdenv.lib.licenses.unfree</varname>,
    <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>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>,
    <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>