tjh.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-meta">
4 <title>Meta-attributes</title>
5 <para>
6 Nix packages can declare <emphasis>meta-attributes</emphasis> that contain
7 information about a package such as a description, its homepage, its license,
8 and so on. For instance, the GNU Hello package has a <varname>meta</varname>
9 declaration like this:
10<programlisting>
11meta = with stdenv.lib; {
12 description = "A program that produces a familiar, friendly greeting";
13 longDescription = ''
14 GNU Hello is a program that prints "Hello, world!" when you run it.
15 It is fully customizable.
16 '';
17 homepage = https://www.gnu.org/software/hello/manual/;
18 license = licenses.gpl3Plus;
19 maintainers = [ maintainers.eelco ];
20 platforms = platforms.all;
21};
22</programlisting>
23 </para>
24 <para>
25 Meta-attributes are not passed to the builder of the package. Thus, a change
26 to a meta-attribute doesn’t trigger a recompilation of the package. The
27 value of a meta-attribute must be a string.
28 </para>
29 <para>
30 The meta-attributes of a package can be queried from the command-line using
31 <command>nix-env</command>:
32<screen>
33$ nix-env -qa hello --json
34{
35 "hello": {
36 "meta": {
37 "description": "A program that produces a familiar, friendly greeting",
38 "homepage": "https://www.gnu.org/software/hello/manual/",
39 "license": {
40 "fullName": "GNU General Public License version 3 or later",
41 "shortName": "GPLv3+",
42 "url": "http://www.fsf.org/licensing/licenses/gpl.html"
43 },
44 "longDescription": "GNU Hello is a program that prints \"Hello, world!\" when you run it.\nIt is fully customizable.\n",
45 "maintainers": [
46 "Ludovic Court\u00e8s <ludo@gnu.org>"
47 ],
48 "platforms": [
49 "i686-linux",
50 "x86_64-linux",
51 "armv5tel-linux",
52 "armv7l-linux",
53 "mips32-linux",
54 "x86_64-darwin",
55 "i686-cygwin",
56 "i686-freebsd",
57 "x86_64-freebsd",
58 "i686-openbsd",
59 "x86_64-openbsd"
60 ],
61 "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/default.nix:14"
62 },
63 "name": "hello-2.9",
64 "system": "x86_64-linux"
65 }
66}
67
68
69</screen>
70 <command>nix-env</command> knows about the <varname>description</varname>
71 field specifically:
72<screen>
73$ nix-env -qa hello --description
74hello-2.3 A program that produces a familiar, friendly greeting
75</screen>
76 </para>
77 <section xml:id="sec-standard-meta-attributes">
78 <title>Standard meta-attributes</title>
79
80 <para>
81 It is expected that each meta-attribute is one of the following:
82 </para>
83
84 <variablelist>
85 <varlistentry>
86 <term>
87 <varname>description</varname>
88 </term>
89 <listitem>
90 <para>
91 A short (one-line) description of the package. This is shown by
92 <command>nix-env -q --description</command> and also on the Nixpkgs
93 release pages.
94 </para>
95 <para>
96 Don’t include a period at the end. Don’t include newline characters.
97 Capitalise the first character. For brevity, don’t repeat the name of
98 package — just describe what it does.
99 </para>
100 <para>
101 Wrong: <literal>"libpng is a library that allows you to decode PNG
102 images."</literal>
103 </para>
104 <para>
105 Right: <literal>"A library for decoding PNG images"</literal>
106 </para>
107 </listitem>
108 </varlistentry>
109 <varlistentry>
110 <term>
111 <varname>longDescription</varname>
112 </term>
113 <listitem>
114 <para>
115 An arbitrarily long description of the package.
116 </para>
117 </listitem>
118 </varlistentry>
119 <varlistentry>
120 <term>
121 <varname>branch</varname>
122 </term>
123 <listitem>
124 <para>
125 Release branch. Used to specify that a package is not going to receive
126 updates that are not in this branch; for example, Linux kernel 3.0 is
127 supposed to be updated to 3.0.X, not 3.1.
128 </para>
129 </listitem>
130 </varlistentry>
131 <varlistentry>
132 <term>
133 <varname>homepage</varname>
134 </term>
135 <listitem>
136 <para>
137 The package’s homepage. Example:
138 <literal>https://www.gnu.org/software/hello/manual/</literal>
139 </para>
140 </listitem>
141 </varlistentry>
142 <varlistentry>
143 <term>
144 <varname>downloadPage</varname>
145 </term>
146 <listitem>
147 <para>
148 The page where a link to the current version can be found. Example:
149 <literal>https://ftp.gnu.org/gnu/hello/</literal>
150 </para>
151 </listitem>
152 </varlistentry>
153 <varlistentry>
154 <term>
155 <varname>license</varname>
156 </term>
157 <listitem>
158 <para>
159 The license, or licenses, for the package. One from the attribute set
160 defined in
161 <link
162 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
163 <filename>nixpkgs/lib/licenses.nix</filename></link>. At this moment
164 using both a list of licenses and a single license is valid. If the
165 license field is in the form of a list representation, then it means that
166 parts of the package are licensed differently. Each license should
167 preferably be referenced by their attribute. The non-list attribute value
168 can also be a space delimited string representation of the contained
169 attribute shortNames or spdxIds. The following are all valid examples:
170 <itemizedlist>
171 <listitem>
172 <para>
173 Single license referenced by attribute (preferred)
174 <literal>stdenv.lib.licenses.gpl3</literal>.
175 </para>
176 </listitem>
177 <listitem>
178 <para>
179 Single license referenced by its attribute shortName (frowned upon)
180 <literal>"gpl3"</literal>.
181 </para>
182 </listitem>
183 <listitem>
184 <para>
185 Single license referenced by its attribute spdxId (frowned upon)
186 <literal>"GPL-3.0"</literal>.
187 </para>
188 </listitem>
189 <listitem>
190 <para>
191 Multiple licenses referenced by attribute (preferred) <literal>with
192 stdenv.lib.licenses; [ asl20 free ofl ]</literal>.
193 </para>
194 </listitem>
195 <listitem>
196 <para>
197 Multiple licenses referenced as a space delimited string of attribute
198 shortNames (frowned upon) <literal>"asl20 free ofl"</literal>.
199 </para>
200 </listitem>
201 </itemizedlist>
202 For details, see <xref linkend='sec-meta-license'/>.
203 </para>
204 </listitem>
205 </varlistentry>
206 <varlistentry>
207 <term>
208 <varname>maintainers</varname>
209 </term>
210 <listitem>
211 <para>
212 A list of names and e-mail addresses of the maintainers of this Nix
213 expression. If you would like to be a maintainer of a package, you may
214 want to add yourself to
215 <link
216 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix"><filename>nixpkgs/maintainers/maintainer-list.nix</filename></link>
217 and write something like <literal>[ stdenv.lib.maintainers.alice
218 stdenv.lib.maintainers.bob ]</literal>.
219 </para>
220 </listitem>
221 </varlistentry>
222 <varlistentry>
223 <term>
224 <varname>priority</varname>
225 </term>
226 <listitem>
227 <para>
228 The <emphasis>priority</emphasis> of the package, used by
229 <command>nix-env</command> to resolve file name conflicts between
230 packages. See the Nix manual page for <command>nix-env</command> for
231 details. Example: <literal>"10"</literal> (a low-priority package).
232 </para>
233 </listitem>
234 </varlistentry>
235 <varlistentry>
236 <term>
237 <varname>platforms</varname>
238 </term>
239 <listitem>
240 <para>
241 The list of Nix platform types on which the package is supported. Hydra
242 builds packages according to the platform specified. If no platform is
243 specified, the package does not have prebuilt binaries. An example is:
244<programlisting>
245meta.platforms = stdenv.lib.platforms.linux;
246</programlisting>
247 Attribute Set <varname>stdenv.lib.platforms</varname> defines
248 <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix">
249 various common lists</link> of platforms types.
250 </para>
251 </listitem>
252 </varlistentry>
253 <varlistentry>
254 <term>
255 <varname>tests</varname>
256 </term>
257 <listitem>
258 <warning>
259 <para>
260 This attribute is special in that it is not actually under the
261 <literal>meta</literal> attribute set but rather under the
262 <literal>passthru</literal> attribute set. This is due to a current
263 limitation of Nix, and will change as soon as Nixpkgs will be able to
264 depend on a new enough version of Nix. See
265 <link xlink:href="https://github.com/NixOS/nix/issues/2532">the relevant
266 issue</link> for more details.
267 </para>
268 </warning>
269 <para>
270 An attribute set with as values tests. A test is a derivation, which
271 builds successfully when the test passes, and fails to build otherwise. A
272 derivation that is a test needs to have <literal>meta.timeout</literal>
273 defined.
274 </para>
275 <para>
276 The NixOS tests are available as <literal>nixosTests</literal> in
277 parameters of derivations. For instance, the OpenSMTPD derivation
278 includes lines similar to:
279<programlisting>
280{ /* ... */, nixosTests }:
281{
282 # ...
283 passthru.tests = {
284 basic-functionality-and-dovecot-integration = nixosTests.opensmtpd;
285 };
286}
287</programlisting>
288 </para>
289 </listitem>
290 </varlistentry>
291 <varlistentry>
292 <term>
293 <varname>timeout</varname>
294 </term>
295 <listitem>
296 <para>
297 A timeout (in seconds) for building the derivation. If the derivation
298 takes longer than this time to build, it can fail due to breaking the
299 timeout. However, all computers do not have the same computing power,
300 hence some builders may decide to apply a multiplicative factor to this
301 value. When filling this value in, try to keep it approximately
302 consistent with other values already present in
303 <literal>nixpkgs</literal>.
304 </para>
305 </listitem>
306 </varlistentry>
307 <varlistentry>
308 <term>
309 <varname>hydraPlatforms</varname>
310 </term>
311 <listitem>
312 <para>
313 The list of Nix platform types for which the Hydra instance at
314 <literal>hydra.nixos.org</literal> will build the package. (Hydra is the
315 Nix-based continuous build system.) It defaults to the value of
316 <varname>meta.platforms</varname>. Thus, the only reason to set
317 <varname>meta.hydraPlatforms</varname> is if you want
318 <literal>hydra.nixos.org</literal> to build the package on a subset of
319 <varname>meta.platforms</varname>, or not at all, e.g.
320<programlisting>
321meta.platforms = stdenv.lib.platforms.linux;
322meta.hydraPlatforms = [];
323</programlisting>
324 </para>
325 </listitem>
326 </varlistentry>
327 <varlistentry>
328 <term>
329 <varname>broken</varname>
330 </term>
331 <listitem>
332 <para>
333 If set to <literal>true</literal>, the package is marked as “broken”,
334 meaning that it won’t show up in <literal>nix-env -qa</literal>, and
335 cannot be built or installed. Such packages should be removed from
336 Nixpkgs eventually unless they are fixed.
337 </para>
338 </listitem>
339 </varlistentry>
340 <varlistentry>
341 <term>
342 <varname>updateWalker</varname>
343 </term>
344 <listitem>
345 <para>
346 If set to <literal>true</literal>, the package is tested to be updated
347 correctly by the <literal>update-walker.sh</literal> script without
348 additional settings. Such packages have <varname>meta.version</varname>
349 set and their homepage (or the page specified by
350 <varname>meta.downloadPage</varname>) contains a direct link to the
351 package tarball.
352 </para>
353 </listitem>
354 </varlistentry>
355 </variablelist>
356 </section>
357 <section xml:id="sec-meta-license">
358 <title>Licenses</title>
359
360 <para>
361 The <varname>meta.license</varname> attribute should preferrably contain a
362 value from <varname>stdenv.lib.licenses</varname> defined in
363 <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
364 <filename>nixpkgs/lib/licenses.nix</filename></link>, or in-place license
365 description of the same format if the license is unlikely to be useful in
366 another expression.
367 </para>
368
369 <para>
370 Although it's typically better to indicate the specific license, a few
371 generic options are available:
372 <variablelist>
373 <varlistentry>
374 <term>
375 <varname>stdenv.lib.licenses.free</varname>, <varname>"free"</varname>
376 </term>
377 <listitem>
378 <para>
379 Catch-all for free software licenses not listed above.
380 </para>
381 </listitem>
382 </varlistentry>
383 <varlistentry>
384 <term>
385 <varname>stdenv.lib.licenses.unfreeRedistributable</varname>, <varname>"unfree-redistributable"</varname>
386 </term>
387 <listitem>
388 <para>
389 Unfree package that can be redistributed in binary form. That is, it’s
390 legal to redistribute the <emphasis>output</emphasis> of the derivation.
391 This means that the package can be included in the Nixpkgs channel.
392 </para>
393 <para>
394 Sometimes proprietary software can only be redistributed unmodified.
395 Make sure the builder doesn’t actually modify the original binaries;
396 otherwise we’re breaking the license. For instance, the NVIDIA X11
397 drivers can be redistributed unmodified, but our builder applies
398 <command>patchelf</command> to make them work. Thus, its license is
399 <varname>"unfree"</varname> and it cannot be included in the Nixpkgs
400 channel.
401 </para>
402 </listitem>
403 </varlistentry>
404 <varlistentry>
405 <term>
406 <varname>stdenv.lib.licenses.unfree</varname>, <varname>"unfree"</varname>
407 </term>
408 <listitem>
409 <para>
410 Unfree package that cannot be redistributed. You can build it yourself,
411 but you cannot redistribute the output of the derivation. Thus it cannot
412 be included in the Nixpkgs channel.
413 </para>
414 </listitem>
415 </varlistentry>
416 <varlistentry>
417 <term>
418 <varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, <varname>"unfree-redistributable-firmware"</varname>
419 </term>
420 <listitem>
421 <para>
422 This package supplies unfree, redistributable firmware. This is a
423 separate value from <varname>unfree-redistributable</varname> because
424 not everybody cares whether firmware is free.
425 </para>
426 </listitem>
427 </varlistentry>
428 </variablelist>
429 </para>
430 </section>
431</chapter>