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 --meta --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/ex-2/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>version</varname></term>
117 <listitem><para>Package version.</para></listitem>
118 </varlistentry>
119
120 <varlistentry>
121 <term><varname>branch</varname></term>
122 <listitem><para>Release branch. Used to specify that a package is not
123 going to receive updates that are not in this branch; for example, Linux
124 kernel 3.0 is supposed to be updated to 3.0.X, not 3.1.</para></listitem>
125 </varlistentry>
126
127 <varlistentry>
128 <term><varname>homepage</varname></term>
129 <listitem><para>The package’s homepage. Example:
130 <literal>http://www.gnu.org/software/hello/manual/</literal></para></listitem>
131 </varlistentry>
132
133 <varlistentry>
134 <term><varname>downloadPage</varname></term>
135 <listitem><para>The page where a link to the current version can be found. Example:
136 <literal>http://ftp.gnu.org/gnu/hello/</literal></para></listitem>
137 </varlistentry>
138
139 <varlistentry>
140 <term><varname>license</varname></term>
141 <listitem>
142 <para>
143 The license, or licenses, for the package. One from the attribute set
144 defined in <link
145 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
146 <filename>nixpkgs/lib/licenses.nix</filename></link>. At this moment
147 using both a list of licenses and a single license is valid. If the
148 license field is in the form of a list representation, then it means
149 that parts of the package are licensed differently. Each license
150 should preferably be referenced by their attribute. The non-list
151 attribute value can also be a space delimited string representation of
152 the contained attribute shortNames or spdxIds. The following are all valid
153 examples:
154 <itemizedlist>
155 <listitem><para>Single license referenced by attribute (preferred)
156 <literal>stdenv.lib.licenses.gpl3</literal>.
157 </para></listitem>
158 <listitem><para>Single license referenced by its attribute shortName (frowned upon)
159 <literal>"gpl3"</literal>.
160 </para></listitem>
161 <listitem><para>Single license referenced by its attribute spdxId (frowned upon)
162 <literal>"GPL-3.0"</literal>.
163 </para></listitem>
164 <listitem><para>Multiple licenses referenced by attribute (preferred)
165 <literal>with stdenv.lib.licenses; [ asl20 free ofl ]</literal>.
166 </para></listitem>
167 <listitem><para>Multiple licenses referenced as a space delimited string of attribute shortNames (frowned upon)
168 <literal>"asl20 free ofl"</literal>.
169 </para></listitem>
170 </itemizedlist>
171 For details, see <xref linkend='sec-meta-license'/>.
172 </para>
173 </listitem>
174 </varlistentry>
175
176 <varlistentry>
177 <term><varname>maintainers</varname></term>
178 <listitem><para>A list of names and e-mail addresses of the
179 maintainers of this Nix expression. If
180 you would like to be a maintainer of a package, you may want to add
181 yourself to <link
182 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/maintainers.nix"><filename>nixpkgs/lib/maintainers.nix</filename></link>
183 and write something like <literal>[ stdenv.lib.maintainers.alice
184 stdenv.lib.maintainers.bob ]</literal>.</para></listitem>
185 </varlistentry>
186
187 <varlistentry>
188 <term><varname>priority</varname></term>
189 <listitem><para>The <emphasis>priority</emphasis> of the package,
190 used by <command>nix-env</command> to resolve file name conflicts
191 between packages. See the Nix manual page for
192 <command>nix-env</command> for details. Example:
193 <literal>"10"</literal> (a low-priority
194 package).</para></listitem>
195 </varlistentry>
196
197 <varlistentry>
198 <term><varname>platforms</varname></term>
199 <listitem><para>The list of Nix platform types on which the
200 package is supported. Hydra builds packages according to the
201 platform specified. If no platform is specified, the package does
202 not have prebuilt binaries. An example is:
203
204<programlisting>
205meta.platforms = stdenv.lib.platforms.linux;
206</programlisting>
207
208 Attribute Set <varname>stdenv.lib.platforms</varname> in
209 <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/platforms.nix">
210 <filename>nixpkgs/lib/platforms.nix</filename></link> defines various common
211 lists of platforms types.
212 </para></listitem>
213 </varlistentry>
214
215 <varlistentry>
216 <term><varname>hydraPlatforms</varname></term>
217 <listitem><para>The list of Nix platform types for which the Hydra
218 instance at <literal>hydra.nixos.org</literal> will build the
219 package. (Hydra is the Nix-based continuous build system.) It
220 defaults to the value of <varname>meta.platforms</varname>. Thus,
221 the only reason to set <varname>meta.hydraPlatforms</varname> is
222 if you want <literal>hydra.nixos.org</literal> to build the
223 package on a subset of <varname>meta.platforms</varname>, or not
224 at all, e.g.
225
226<programlisting>
227meta.platforms = stdenv.lib.platforms.linux;
228meta.hydraPlatforms = [];
229</programlisting>
230
231 </para></listitem>
232 </varlistentry>
233
234 <varlistentry>
235 <term><varname>broken</varname></term>
236 <listitem><para>If set to <literal>true</literal>, the package is
237 marked as “broken”, meaning that it won’t show up in
238 <literal>nix-env -qa</literal>, and cannot be built or installed.
239 Such packages should be removed from Nixpkgs eventually unless
240 they are fixed.</para></listitem>
241 </varlistentry>
242
243 <varlistentry>
244 <term><varname>updateWalker</varname></term>
245 <listitem><para>If set to <literal>true</literal>, the package is
246 tested to be updated correctly by the <literal>update-walker.sh</literal>
247 script without additional settings. Such packages have
248 <varname>meta.version</varname> set and their homepage (or
249 the page specified by <varname>meta.downloadPage</varname>) contains
250 a direct link to the package tarball.</para></listitem>
251 </varlistentry>
252
253</variablelist>
254
255
256</section>
257
258
259<section xml:id="sec-meta-license"><title>Licenses</title>
260
261<para>The <varname>meta.license</varname> attribute should preferrably contain
262a value from <varname>stdenv.lib.licenses</varname> defined in
263<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix">
264<filename>nixpkgs/lib/licenses.nix</filename></link>,
265or in-place license description of the same format if the license is
266unlikely to be useful in another expression.
267
268A few generic options are available, although it's typically better
269to indicate the specific license:
270<variablelist>
271
272 <varlistentry>
273 <term><varname>free</varname></term>
274 <listitem><para>Catch-all for free software licenses not listed
275 above.</para></listitem>
276 </varlistentry>
277
278 <varlistentry>
279 <term><varname>unfree-redistributable</varname></term>
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>unfree</varname></term>
297 <listitem><para>Unfree package that cannot be redistributed. You
298 can build it yourself, but you cannot redistribute the output of
299 the derivation. Thus it cannot be included in the Nixpkgs
300 channel.</para></listitem>
301 </varlistentry>
302
303 <varlistentry>
304 <term><varname>unfree-redistributable-firmware</varname></term>
305 <listitem><para>This package supplies unfree, redistributable
306 firmware. This is a separate value from
307 <varname>unfree-redistributable</varname> because not everybody
308 cares whether firmware is free.</para></listitem>
309 </varlistentry>
310
311</variablelist>
312
313</para>
314
315
316</section>
317
318
319</chapter>