mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-12-25 03:17:13 +00:00
a2cbc77e4f
The function ‘mkDerivation’ now checks whether the current platform type is included in a package's meta.platform field. If not, it throws an exception: $ nix-build -A linux --argstr system x86_64-darwin error: user-thrown exception: the package ‘linux-3.10.15’ is not supported on ‘x86_64-darwin’ These packages also no longer show up in ‘nix-env -qa’ output. This means, for instance, that the number of packages shown on x86_64-freebsd has dropped from 9268 to 4764. Since meta.platforms was also used to prevent Hydra from building some packages, there now is a new attribute meta.hydraPlatforms listing the platforms on which Hydra should build the package (which defaults to meta.platforms).
295 lines
9.9 KiB
XML
295 lines
9.9 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xml:id="chap-meta">
|
||
|
||
<title>Meta-attributes</title>
|
||
|
||
<para>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:
|
||
|
||
<programlisting>
|
||
meta = {
|
||
description = "A program that produces a familiar, friendly greeting";
|
||
longDescription = ''
|
||
GNU Hello is a program that prints "Hello, world!" when you run it.
|
||
It is fully customizable.
|
||
'';
|
||
homepage = http://www.gnu.org/software/hello/manual/;
|
||
license = "GPLv3+";
|
||
};
|
||
</programlisting>
|
||
|
||
</para>
|
||
|
||
<para>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 a string.</para>
|
||
|
||
<para>The meta-attributes of a package can be queried from the
|
||
command-line using <command>nix-env</command>:
|
||
|
||
<screen>
|
||
$ nix-env -qa hello --meta --xml
|
||
<?xml version='1.0' encoding='utf-8'?>
|
||
<items>
|
||
<item attrPath="hello" name="hello-2.3" system="i686-linux">
|
||
<meta name="description" value="A program that produces a familiar, friendly greeting" />
|
||
<meta name="homepage" value="http://www.gnu.org/software/hello/manual/" />
|
||
<meta name="license" value="GPLv3+" />
|
||
<meta name="longDescription" value="GNU Hello is a program that prints &quot;Hello, world!&quot; when you run it.&#xA;It is fully customizable.&#xA;" />
|
||
</item>
|
||
</items>
|
||
</screen>
|
||
|
||
<command>nix-env</command> knows about the
|
||
<varname>description</varname> field specifically:
|
||
|
||
<screen>
|
||
$ nix-env -qa hello --description
|
||
hello-2.3 A program that produces a familiar, friendly greeting
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
|
||
<section><title>Standard meta-attributes</title>
|
||
|
||
<para>The following meta-attributes have a standard
|
||
interpretation:</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry>
|
||
<term><varname>description</varname></term>
|
||
<listitem><para>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.</para>
|
||
|
||
<para>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.</para>
|
||
|
||
<para>Wrong: <literal>"libpng is a library that allows you to decode PNG images."</literal></para>
|
||
|
||
<para>Right: <literal>"A library for decoding PNG images"</literal></para>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>longDescription</varname></term>
|
||
<listitem><para>An arbitrarily long description of the
|
||
package.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>homepage</varname></term>
|
||
<listitem><para>The package’s homepage. Example:
|
||
<literal>http://www.gnu.org/software/hello/manual/</literal></para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>license</varname></term>
|
||
<listitem><para>The license for the package. See below for the
|
||
allowed values.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>maintainers</varname></term>
|
||
<listitem><para>A list of names and e-mail addresses of the
|
||
maintainers of this Nix expression, e.g. <literal>["Alice
|
||
<alice@example.org>" "Bob <bob@example.com>"]</literal>. If
|
||
you are the maintainer of multiple packages, you may want to add
|
||
yourself to <link
|
||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/maintainers.nix"><filename>pkgs/lib/maintainers.nix</filename></link>
|
||
and write something like <literal>[stdenv.lib.maintainers.alice
|
||
stdenv.lib.maintainers.bob]</literal>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>priority</varname></term>
|
||
<listitem><para>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).</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>platforms</varname></term>
|
||
<listitem><para>The list of Nix platform types on which the
|
||
package is supported. If this attribute is set, the package will
|
||
refuse to build, and won’t show up in <literal>nix-env
|
||
-qa</literal> output, on any platform not listed
|
||
here. An example is:
|
||
|
||
<programlisting>
|
||
meta.platforms = [ "x86_64-linux" "i686-linux" "x86_64-darwin" ];
|
||
</programlisting>
|
||
|
||
The set <varname>lib.platforms</varname> defines various common
|
||
lists of platforms types, so it’s more typical to write:
|
||
|
||
<programlisting>
|
||
meta.platforms = stdenv.lib.platforms.linux ++ stdenv.lib.platforms.darwin;
|
||
</programlisting>
|
||
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>hydraPlatforms</varname></term>
|
||
<listitem><para>The list of Nix platform types for which the Hydra
|
||
instance at <literal>hydra.nixos.org</literal> should 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.
|
||
|
||
<programlisting>
|
||
meta.platforms = stdenv.lib.platforms.linux;
|
||
meta.hydraPlatforms = [];
|
||
</programlisting>
|
||
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>broken</varname></term>
|
||
<listitem><para>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.
|
||
Sush packages should be removed from Nixpkgs eventually unless
|
||
they are fixed.</para></listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
|
||
</section>
|
||
|
||
|
||
<section xml:id="sec-meta-license"><title>Licenses</title>
|
||
|
||
<note><para>This is just a first attempt at standardising the license
|
||
attribute.</para></note>
|
||
|
||
<para>The <varname>meta.license</varname> attribute must be one of the
|
||
following:
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry>
|
||
<term><varname>GPL</varname></term>
|
||
<listitem><para>GNU General Public License; version not
|
||
specified.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>GPLv2</varname></term>
|
||
<listitem><para>GNU General Public License, version
|
||
2.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>GPLv2+</varname></term>
|
||
<listitem><para>GNU General Public License, version
|
||
2 or higher.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>GPLv3</varname></term>
|
||
<listitem><para>GNU General Public License, version
|
||
3.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>GPLv3+</varname></term>
|
||
<listitem><para>GNU General Public License, version
|
||
3 or higher.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>bsd</varname></term>
|
||
<listitem><para>Catch-all for licenses that are essentially
|
||
similar to <link
|
||
xlink:href="http://www.gnu.org/licenses/license-list.html#ModifiedBSD">the
|
||
original BSD license with the advertising clause removed</link>,
|
||
i.e. permissive non-copyleft free software licenses. This
|
||
includes the <link
|
||
xlink:href="http://www.gnu.org/licenses/license-list.html#X11License">X11
|
||
(“MIT”) License</link>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>perl5</varname></term>
|
||
<listitem><para>The Perl 5 license (Artistic License, version 1
|
||
and GPL, version 1 or later).</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>free</varname></term>
|
||
<listitem><para>Catch-all for free software licenses not listed
|
||
above.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>free-copyleft</varname></term>
|
||
<listitem><para>Catch-all for free, copyleft software licenses not
|
||
listed above.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>free-non-copyleft</varname></term>
|
||
<listitem><para>Catch-all for free, non-copyleft software licenses
|
||
not listed above.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>unfree-redistributable</varname></term>
|
||
<listitem><para>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.</para>
|
||
|
||
<para>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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>unfree</varname></term>
|
||
<listitem><para>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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>unfree-redistributable-firmware</varname></term>
|
||
<listitem><para>This package supplies unfree, redistributable
|
||
firmware. This is a separate value from
|
||
<varname>unfree-redistributable</varname> because not everybody
|
||
cares whether firmware is free.</para></listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</para>
|
||
|
||
|
||
</section>
|
||
|
||
|
||
</chapter>
|