| blob | c9d1b1362193d4f2496b36b67626e78e35c9956d |
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 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:
7 <programlisting>
8 meta = with stdenv.lib; {
9 description = "A program that produces a familiar, friendly greeting";
10 longDescription = ''
11 GNU Hello is a program that prints "Hello, world!" when you run it.
12 It is fully customizable.
13 '';
14 homepage = "https://www.gnu.org/software/hello/manual/";
15 license = licenses.gpl3Plus;
16 maintainers = [ maintainers.eelco ];
17 platforms = platforms.all;
18 };
19 </programlisting>
20 </para>
21 <para>
22 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.
23 </para>
24 <para>
25 The meta-attributes of a package can be queried from the command-line using <command>nix-env</command>:
26 <screen>
27 <prompt>$ </prompt>nix-env -qa hello --json
28 {
29 "hello": {
30 "meta": {
31 "description": "A program that produces a familiar, friendly greeting",
32 "homepage": "https://www.gnu.org/software/hello/manual/",
33 "license": {
34 "fullName": "GNU General Public License version 3 or later",
35 "shortName": "GPLv3+",
36 "url": "http://www.fsf.org/licensing/licenses/gpl.html"
37 },
38 "longDescription": "GNU Hello is a program that prints \"Hello, world!\" when you run it.\nIt is fully customizable.\n",
39 "maintainers": [
40 "Ludovic Court\u00e8s <ludo@gnu.org>"
41 ],
42 "platforms": [
43 "i686-linux",
44 "x86_64-linux",
45 "armv5tel-linux",
46 "armv7l-linux",
47 "mips32-linux",
48 "x86_64-darwin",
49 "i686-cygwin",
50 "i686-freebsd",
51 "x86_64-freebsd",
52 "i686-openbsd",
53 "x86_64-openbsd"
54 ],
55 "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/default.nix:14"
56 },
57 "name": "hello-2.9",
58 "system": "x86_64-linux"
59 }
60 }
63 </screen>
64 <command>nix-env</command> knows about the <varname>description</varname> field specifically:
65 <screen>
66 <prompt>$ </prompt>nix-env -qa hello --description
67 hello-2.3 A program that produces a familiar, friendly greeting
68 </screen>
69 </para>
70 <section xml:id="sec-standard-meta-attributes">
71 <title>Standard meta-attributes</title>
73 <para>
74 It is expected that each meta-attribute is one of the following:
75 </para>
77 <variablelist>
78 <varlistentry>
79 <term>
80 <varname>description</varname>
81 </term>
82 <listitem>
83 <para>
84 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.
85 </para>
86 <para>
87 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.
88 </para>
89 <para>
90 Wrong: <literal>"libpng is a library that allows you to decode PNG images."</literal>
91 </para>
92 <para>
93 Right: <literal>"A library for decoding PNG images"</literal>
94 </para>
95 </listitem>
96 </varlistentry>
97 <varlistentry>
98 <term>
99 <varname>longDescription</varname>
100 </term>
101 <listitem>
102 <para>
103 An arbitrarily long description of the package.
104 </para>
105 </listitem>
106 </varlistentry>
107 <varlistentry>
108 <term>
109 <varname>branch</varname>
110 </term>
111 <listitem>
112 <para>
113 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.
114 </para>
115 </listitem>
116 </varlistentry>
117 <varlistentry>
118 <term>
119 <varname>homepage</varname>
120 </term>
121 <listitem>
122 <para>
123 The package’s homepage. Example: <literal>https://www.gnu.org/software/hello/manual/</literal>
124 </para>
125 </listitem>
126 </varlistentry>
127 <varlistentry>
128 <term>
129 <varname>downloadPage</varname>
130 </term>
131 <listitem>
132 <para>
133 The page where a link to the current version can be found. Example: <literal>https://ftp.gnu.org/gnu/hello/</literal>
134 </para>
135 </listitem>
136 </varlistentry>
137 <varlistentry>
138 <term>
139 <varname>changelog</varname>
140 </term>
141 <listitem>
142 <para>
143 A link or a list of links to the location of Changelog for a package. A link may use expansion to refer to the correct changelog version. Example: <literal>"https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}"</literal>
144 </para>
145 </listitem>
146 </varlistentry>
147 <varlistentry>
148 <term>
149 <varname>license</varname>
150 </term>
151 <listitem>
152 <para>
153 The license, or licenses, for the package. One from the attribute set defined in <link
154 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:
155 <itemizedlist>
156 <listitem>
157 <para>
158 Single license referenced by attribute (preferred) <literal>stdenv.lib.licenses.gpl3Only</literal>.
159 </para>
160 </listitem>
161 <listitem>
162 <para>
163 Single license referenced by its attribute shortName (frowned upon) <literal>"gpl3Only"</literal>.
164 </para>
165 </listitem>
166 <listitem>
167 <para>
168 Single license referenced by its attribute spdxId (frowned upon) <literal>"GPL-3.0-only"</literal>.
169 </para>
170 </listitem>
171 <listitem>
172 <para>
173 Multiple licenses referenced by attribute (preferred) <literal>with stdenv.lib.licenses; [ asl20 free ofl ]</literal>.
174 </para>
175 </listitem>
176 <listitem>
177 <para>
178 Multiple licenses referenced as a space delimited string of attribute shortNames (frowned upon) <literal>"asl20 free ofl"</literal>.
179 </para>
180 </listitem>
181 </itemizedlist>
182 For details, see <xref linkend='sec-meta-license'/>.
183 </para>
184 </listitem>
185 </varlistentry>
186 <varlistentry>
187 <term>
188 <varname>maintainers</varname>
189 </term>
190 <listitem>
191 <para>
192 A list of the maintainers of this Nix expression. Maintainers are defined in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix"><filename>nixpkgs/maintainers/maintainer-list.nix</filename></link>. There is no restriction to becoming a maintainer, just add yourself to that list in a separate commit titled 'maintainers: add alice', and reference maintainers with <literal>maintainers = with lib.maintainers; [ alice bob ]</literal>.
193 </para>
194 </listitem>
195 </varlistentry>
196 <varlistentry>
197 <term>
198 <varname>priority</varname>
199 </term>
200 <listitem>
201 <para>
202 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).
203 </para>
204 </listitem>
205 </varlistentry>
206 <varlistentry>
207 <term>
208 <varname>platforms</varname>
209 </term>
210 <listitem>
211 <para>
212 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:
213 <programlisting>
214 meta.platforms = stdenv.lib.platforms.linux;
215 </programlisting>
216 Attribute Set <varname>stdenv.lib.platforms</varname> defines <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix"> various common lists</link> of platforms types.
217 </para>
218 </listitem>
219 </varlistentry>
220 <varlistentry>
221 <term>
222 <varname>tests</varname>
223 </term>
224 <listitem>
225 <warning>
226 <para>
227 This attribute is special in that it is not actually under the <literal>meta</literal> attribute set but rather under the <literal>passthru</literal> attribute set. This is due to how <literal>meta</literal> attributes work, and the fact that they are supposed to contain only metadata, not derivations.
228 </para>
229 </warning>
230 <para>
231 An attribute set with as values tests. A test is a derivation, which builds successfully when the test passes, and fails to build otherwise. A derivation that is a test needs to have <literal>meta.timeout</literal> defined.
232 </para>
233 <para>
234 The NixOS tests are available as <literal>nixosTests</literal> in parameters of derivations. For instance, the OpenSMTPD derivation includes lines similar to:
235 <programlisting>
236 { /* ... */, nixosTests }:
237 {
238 # ...
239 passthru.tests = {
240 basic-functionality-and-dovecot-integration = nixosTests.opensmtpd;
241 };
242 }
243 </programlisting>
244 </para>
245 </listitem>
246 </varlistentry>
247 <varlistentry>
248 <term>
249 <varname>timeout</varname>
250 </term>
251 <listitem>
252 <para>
253 A timeout (in seconds) for building the derivation. If the derivation takes longer than this time to build, it can fail due to breaking the timeout. However, all computers do not have the same computing power, hence some builders may decide to apply a multiplicative factor to this value. When filling this value in, try to keep it approximately consistent with other values already present in <literal>nixpkgs</literal>.
254 </para>
255 </listitem>
256 </varlistentry>
257 <varlistentry>
258 <term>
259 <varname>hydraPlatforms</varname>
260 </term>
261 <listitem>
262 <para>
263 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.
264 <programlisting>
265 meta.platforms = stdenv.lib.platforms.linux;
266 meta.hydraPlatforms = [];
267 </programlisting>
268 </para>
269 </listitem>
270 </varlistentry>
271 <varlistentry>
272 <term>
273 <varname>broken</varname>
274 </term>
275 <listitem>
276 <para>
277 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.
278 </para>
279 </listitem>
280 </varlistentry>
281 <varlistentry>
282 <term>
283 <varname>updateWalker</varname>
284 </term>
285 <listitem>
286 <para>
287 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.
288 </para>
289 </listitem>
290 </varlistentry>
291 </variablelist>
292 </section>
293 <section xml:id="sec-meta-license">
294 <title>Licenses</title>
296 <para>
297 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.
298 </para>
300 <para>
301 Although it's typically better to indicate the specific license, a few generic options are available:
302 <variablelist>
303 <varlistentry>
304 <term>
305 <varname>stdenv.lib.licenses.free</varname>, <varname>"free"</varname>
306 </term>
307 <listitem>
308 <para>
309 Catch-all for free software licenses not listed above.
310 </para>
311 </listitem>
312 </varlistentry>
313 <varlistentry>
314 <term>
315 <varname>stdenv.lib.licenses.unfreeRedistributable</varname>, <varname>"unfree-redistributable"</varname>
316 </term>
317 <listitem>
318 <para>
319 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.
320 </para>
321 <para>
322 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.
323 </para>
324 </listitem>
325 </varlistentry>
326 <varlistentry>
327 <term>
328 <varname>stdenv.lib.licenses.unfree</varname>, <varname>"unfree"</varname>
329 </term>
330 <listitem>
331 <para>
332 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.
333 </para>
334 </listitem>
335 </varlistentry>
336 <varlistentry>
337 <term>
338 <varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, <varname>"unfree-redistributable-firmware"</varname>
339 </term>
340 <listitem>
341 <para>
342 This package supplies unfree, redistributable firmware. This is a separate value from <varname>unfree-redistributable</varname> because not everybody cares whether firmware is free.
343 </para>
344 </listitem>
345 </varlistentry>
346 </variablelist>
347 </para>
348 </section>
349 </chapter>