pyrox.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 = http://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": "http://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>http://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>http://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>hydraPlatforms</varname>
256 </term>
257 <listitem>
258 <para>
259 The list of Nix platform types for which the Hydra instance at
260 <literal>hydra.nixos.org</literal> will build the package. (Hydra is the
261 Nix-based continuous build system.) It defaults to the value of
262 <varname>meta.platforms</varname>. Thus, the only reason to set
263 <varname>meta.hydraPlatforms</varname> is if you want
264 <literal>hydra.nixos.org</literal> to build the package on a subset of
265 <varname>meta.platforms</varname>, or not at all, e.g.
266<programlisting>
267meta.platforms = stdenv.lib.platforms.linux;
268meta.hydraPlatforms = [];
269</programlisting>
270 </para>
271 </listitem>
272 </varlistentry>
273 <varlistentry>
274 <term>
275 <varname>broken</varname>
276 </term>
277 <listitem>
278 <para>
279 If set to <literal>true</literal>, the package is marked as “broken”,
280 meaning that it won’t show up in <literal>nix-env -qa</literal>, and
281 cannot be built or installed. Such packages should be removed from
282 Nixpkgs eventually unless they are fixed.
283 </para>
284 </listitem>
285 </varlistentry>
286 <varlistentry>
287 <term>
288 <varname>updateWalker</varname>
289 </term>
290 <listitem>
291 <para>
292 If set to <literal>true</literal>, the package is tested to be updated
293 correctly by the <literal>update-walker.sh</literal> script without
294 additional settings. Such packages have <varname>meta.version</varname>
295 set and their homepage (or the page specified by
296 <varname>meta.downloadPage</varname>) contains a direct link to the
297 package tarball.
298 </para>
299 </listitem>
300 </varlistentry>
301 </variablelist>
302 </section>
303 <section xml:id="sec-meta-license">
304 <title>Licenses</title>
305
306 <para>
307 The <varname>meta.license</varname> attribute should preferrably contain a
308 value from <varname>stdenv.lib.licenses</varname> defined in
309 <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
310 <filename>nixpkgs/lib/licenses.nix</filename></link>, or in-place license
311 description of the same format if the license is unlikely to be useful in
312 another expression.
313 </para>
314
315 <para>
316 Although it's typically better to indicate the specific license, a few
317 generic options are available:
318 <variablelist>
319 <varlistentry>
320 <term>
321 <varname>stdenv.lib.licenses.free</varname>, <varname>"free"</varname>
322 </term>
323 <listitem>
324 <para>
325 Catch-all for free software licenses not listed above.
326 </para>
327 </listitem>
328 </varlistentry>
329 <varlistentry>
330 <term>
331 <varname>stdenv.lib.licenses.unfreeRedistributable</varname>, <varname>"unfree-redistributable"</varname>
332 </term>
333 <listitem>
334 <para>
335 Unfree package that can be redistributed in binary form. That is, it’s
336 legal to redistribute the <emphasis>output</emphasis> of the derivation.
337 This means that the package can be included in the Nixpkgs channel.
338 </para>
339 <para>
340 Sometimes proprietary software can only be redistributed unmodified.
341 Make sure the builder doesn’t actually modify the original binaries;
342 otherwise we’re breaking the license. For instance, the NVIDIA X11
343 drivers can be redistributed unmodified, but our builder applies
344 <command>patchelf</command> to make them work. Thus, its license is
345 <varname>"unfree"</varname> and it cannot be included in the Nixpkgs
346 channel.
347 </para>
348 </listitem>
349 </varlistentry>
350 <varlistentry>
351 <term>
352 <varname>stdenv.lib.licenses.unfree</varname>, <varname>"unfree"</varname>
353 </term>
354 <listitem>
355 <para>
356 Unfree package that cannot be redistributed. You can build it yourself,
357 but you cannot redistribute the output of the derivation. Thus it cannot
358 be included in the Nixpkgs channel.
359 </para>
360 </listitem>
361 </varlistentry>
362 <varlistentry>
363 <term>
364 <varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, <varname>"unfree-redistributable-firmware"</varname>
365 </term>
366 <listitem>
367 <para>
368 This package supplies unfree, redistributable firmware. This is a
369 separate value from <varname>unfree-redistributable</varname> because
370 not everybody cares whether firmware is free.
371 </para>
372 </listitem>
373 </varlistentry>
374 </variablelist>
375 </para>
376 </section>
377</chapter>