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
5<title>Meta-attributes</title>
6
7<para>Nix packages can declare <emphasis>meta-attributes</emphasis>
8that contain information about a package such as a description, its
9homepage, its license, and so on. For instance, the GNU Hello package
10has a <varname>meta</varname> declaration like this:
11
12<programlisting>
13meta = {
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 = stdenv.lib.licenses.gpl3Plus;
21 maintainers = [ stdenv.lib.maintainers.eelco ];
22 platforms = stdenv.lib.platforms.all;
23};
24</programlisting>
25
26</para>
27
28<para>Meta-attributes are not passed to the builder of the package.
29Thus, a change to a meta-attribute doesn’t trigger a recompilation of
30the package. The value of a meta-attribute must be a string.</para>
31
32<para>The meta-attributes of a package can be queried from the
33command-line using <command>nix-env</command>:
34
35<screen>
36$ nix-env -qa hello --json
37{
38 "hello": {
39 "meta": {
40 "description": "A program that produces a familiar, friendly greeting",
41 "homepage": "http://www.gnu.org/software/hello/manual/",
42 "license": {
43 "fullName": "GNU General Public License version 3 or later",
44 "shortName": "GPLv3+",
45 "url": "http://www.fsf.org/licensing/licenses/gpl.html"
46 },
47 "longDescription": "GNU Hello is a program that prints \"Hello, world!\" when you run it.\nIt is fully customizable.\n",
48 "maintainers": [
49 "Ludovic Court\u00e8s <ludo@gnu.org>"
50 ],
51 "platforms": [
52 "i686-linux",
53 "x86_64-linux",
54 "armv5tel-linux",
55 "armv7l-linux",
56 "mips64el-linux",
57 "x86_64-darwin",
58 "i686-cygwin",
59 "i686-freebsd",
60 "x86_64-freebsd",
61 "i686-openbsd",
62 "x86_64-openbsd"
63 ],
64 "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/default.nix:14"
65 },
66 "name": "hello-2.9",
67 "system": "x86_64-linux"
68 }
69}
70
71
72</screen>
73
74<command>nix-env</command> knows about the
75<varname>description</varname> field specifically:
76
77<screen>
78$ nix-env -qa hello --description
79hello-2.3 A program that produces a familiar, friendly greeting
80</screen>
81
82</para>
83
84
85<section xml:id="sec-standard-meta-attributes"><title>Standard
86meta-attributes</title>
87
88<para>It is expected that each meta-attribute is one of the following:</para>
89
90<variablelist>
91
92 <varlistentry>
93 <term><varname>description</varname></term>
94 <listitem><para>A short (one-line) description of the package.
95 This is shown by <command>nix-env -q --description</command> and
96 also on the Nixpkgs release pages.</para>
97
98 <para>Don’t include a period at the end. Don’t include newline
99 characters. Capitalise the first character. For brevity, don’t
100 repeat the name of package — just describe what it does.</para>
101
102 <para>Wrong: <literal>"libpng is a library that allows you to decode PNG images."</literal></para>
103
104 <para>Right: <literal>"A library for decoding PNG images"</literal></para>
105
106 </listitem>
107 </varlistentry>
108
109 <varlistentry>
110 <term><varname>longDescription</varname></term>
111 <listitem><para>An arbitrarily long description of the
112 package.</para></listitem>
113 </varlistentry>
114
115 <varlistentry>
116 <term><varname>branch</varname></term>
117 <listitem><para>Release branch. Used to specify that a package is not
118 going to receive updates that are not in this branch; for example, Linux
119 kernel 3.0 is supposed to be updated to 3.0.X, not 3.1.</para></listitem>
120 </varlistentry>
121
122 <varlistentry>
123 <term><varname>homepage</varname></term>
124 <listitem><para>The package’s homepage. Example:
125 <literal>http://www.gnu.org/software/hello/manual/</literal></para></listitem>
126 </varlistentry>
127
128 <varlistentry>
129 <term><varname>downloadPage</varname></term>
130 <listitem><para>The page where a link to the current version can be found. Example:
131 <literal>http://ftp.gnu.org/gnu/hello/</literal></para></listitem>
132 </varlistentry>
133
134 <varlistentry>
135 <term><varname>license</varname></term>
136 <listitem>
137 <para>
138 The license, or licenses, for the package. One from the attribute set
139 defined in <link
140 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
141 <filename>nixpkgs/lib/licenses.nix</filename></link>. At this moment
142 using both a list of licenses and a single license is valid. If the
143 license field is in the form of a list representation, then it means
144 that parts of the package are licensed differently. Each license
145 should preferably be referenced by their attribute. The non-list
146 attribute value can also be a space delimited string representation of
147 the contained attribute shortNames or spdxIds. The following are all valid
148 examples:
149 <itemizedlist>
150 <listitem><para>Single license referenced by attribute (preferred)
151 <literal>stdenv.lib.licenses.gpl3</literal>.
152 </para></listitem>
153 <listitem><para>Single license referenced by its attribute shortName (frowned upon)
154 <literal>"gpl3"</literal>.
155 </para></listitem>
156 <listitem><para>Single license referenced by its attribute spdxId (frowned upon)
157 <literal>"GPL-3.0"</literal>.
158 </para></listitem>
159 <listitem><para>Multiple licenses referenced by attribute (preferred)
160 <literal>with stdenv.lib.licenses; [ asl20 free ofl ]</literal>.
161 </para></listitem>
162 <listitem><para>Multiple licenses referenced as a space delimited string of attribute shortNames (frowned upon)
163 <literal>"asl20 free ofl"</literal>.
164 </para></listitem>
165 </itemizedlist>
166 For details, see <xref linkend='sec-meta-license'/>.
167 </para>
168 </listitem>
169 </varlistentry>
170
171 <varlistentry>
172 <term><varname>maintainers</varname></term>
173 <listitem><para>A list of names and e-mail addresses of the
174 maintainers of this Nix expression. If
175 you would like to be a maintainer of a package, you may want to add
176 yourself to <link
177 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/maintainers.nix"><filename>nixpkgs/lib/maintainers.nix</filename></link>
178 and write something like <literal>[ stdenv.lib.maintainers.alice
179 stdenv.lib.maintainers.bob ]</literal>.</para></listitem>
180 </varlistentry>
181
182 <varlistentry>
183 <term><varname>priority</varname></term>
184 <listitem><para>The <emphasis>priority</emphasis> of the package,
185 used by <command>nix-env</command> to resolve file name conflicts
186 between packages. See the Nix manual page for
187 <command>nix-env</command> for details. Example:
188 <literal>"10"</literal> (a low-priority
189 package).</para></listitem>
190 </varlistentry>
191
192 <varlistentry>
193 <term><varname>platforms</varname></term>
194 <listitem><para>The list of Nix platform types on which the
195 package is supported. Hydra builds packages according to the
196 platform specified. If no platform is specified, the package does
197 not have prebuilt binaries. An example is:
198
199<programlisting>
200meta.platforms = stdenv.lib.platforms.linux;
201</programlisting>
202
203 Attribute Set <varname>stdenv.lib.platforms</varname> in
204 <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/platforms.nix">
205 <filename>nixpkgs/lib/platforms.nix</filename></link> defines various common
206 lists of platforms types.
207 </para></listitem>
208 </varlistentry>
209
210 <varlistentry>
211 <term><varname>hydraPlatforms</varname></term>
212 <listitem><para>The list of Nix platform types for which the Hydra
213 instance at <literal>hydra.nixos.org</literal> will build the
214 package. (Hydra is the Nix-based continuous build system.) It
215 defaults to the value of <varname>meta.platforms</varname>. Thus,
216 the only reason to set <varname>meta.hydraPlatforms</varname> is
217 if you want <literal>hydra.nixos.org</literal> to build the
218 package on a subset of <varname>meta.platforms</varname>, or not
219 at all, e.g.
220
221<programlisting>
222meta.platforms = stdenv.lib.platforms.linux;
223meta.hydraPlatforms = [];
224</programlisting>
225
226 </para></listitem>
227 </varlistentry>
228
229 <varlistentry>
230 <term><varname>broken</varname></term>
231 <listitem><para>If set to <literal>true</literal>, the package is
232 marked as “broken”, meaning that it won’t show up in
233 <literal>nix-env -qa</literal>, and cannot be built or installed.
234 Such packages should be removed from Nixpkgs eventually unless
235 they are fixed.</para></listitem>
236 </varlistentry>
237
238 <varlistentry>
239 <term><varname>updateWalker</varname></term>
240 <listitem><para>If set to <literal>true</literal>, the package is
241 tested to be updated correctly by the <literal>update-walker.sh</literal>
242 script without additional settings. Such packages have
243 <varname>meta.version</varname> set and their homepage (or
244 the page specified by <varname>meta.downloadPage</varname>) contains
245 a direct link to the package tarball.</para></listitem>
246 </varlistentry>
247
248</variablelist>
249
250
251</section>
252
253
254<section xml:id="sec-meta-license"><title>Licenses</title>
255
256<para>The <varname>meta.license</varname> attribute should preferrably contain
257a value from <varname>stdenv.lib.licenses</varname> defined in
258<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
259<filename>nixpkgs/lib/licenses.nix</filename></link>,
260or in-place license description of the same format if the license is
261unlikely to be useful in another expression.</para>
262
263<para>Although it's typically better to indicate the specific license,
264a few generic options are available:
265
266<variablelist>
267
268 <varlistentry>
269 <term><varname>stdenv.lib.licenses.free</varname>,
270 <varname>"free"</varname></term>
271
272 <listitem><para>Catch-all for free software licenses not listed
273 above.</para></listitem>
274 </varlistentry>
275
276 <varlistentry>
277 <term><varname>stdenv.lib.licenses.unfreeRedistributable</varname>,
278 <varname>"unfree-redistributable"</varname></term>
279
280 <listitem><para>Unfree package that can be redistributed in binary
281 form. That is, it’s legal to redistribute the
282 <emphasis>output</emphasis> of the derivation. This means that
283 the package can be included in the Nixpkgs
284 channel.</para>
285
286 <para>Sometimes proprietary software can only be redistributed
287 unmodified. Make sure the builder doesn’t actually modify the
288 original binaries; otherwise we’re breaking the license. For
289 instance, the NVIDIA X11 drivers can be redistributed unmodified,
290 but our builder applies <command>patchelf</command> to make them
291 work. Thus, its license is <varname>"unfree"</varname> and it
292 cannot be included in the Nixpkgs channel.</para></listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><varname>stdenv.lib.licenses.unfree</varname>,
297 <varname>"unfree"</varname></term>
298
299 <listitem><para>Unfree package that cannot be redistributed. You
300 can build it yourself, but you cannot redistribute the output of
301 the derivation. Thus it cannot be included in the Nixpkgs
302 channel.</para></listitem>
303 </varlistentry>
304
305 <varlistentry>
306 <term><varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>,
307 <varname>"unfree-redistributable-firmware"</varname></term>
308
309 <listitem><para>This package supplies unfree, redistributable
310 firmware. This is a separate value from
311 <varname>unfree-redistributable</varname> because not everybody
312 cares whether firmware is free.</para></listitem>
313 </varlistentry>
314
315</variablelist>
316
317</para>
318
319
320</section>
321
322
323</chapter>