You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

meta.xml 12KB

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