diff options
author | Eelco Dolstra <eelco.dolstra@logicblox.com> | 2009-02-10 23:29:42 +0000 |
---|---|---|
committer | Eelco Dolstra <eelco.dolstra@logicblox.com> | 2009-02-10 23:29:42 +0000 |
commit | 79d3e0926d68bb760f1a9f28c862c38e6cd8cc45 (patch) | |
tree | a6a724123a6a8eb92629c272b5e1944773500344 /doc/meta.xml | |
parent | efa1bf9cb57c4fd52641403563324c0c9bf343b4 (diff) |
* Started documenting the meta attributes, including a first
(very incomplete) attempt at standardising the license attribute. svn path=/nixpkgs/trunk/; revision=14028
Diffstat (limited to 'doc/meta.xml')
-rw-r--r-- | doc/meta.xml | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/doc/meta.xml b/doc/meta.xml new file mode 100644 index 0000000000000..5e53609a2368c --- /dev/null +++ b/doc/meta.xml @@ -0,0 +1,200 @@ +<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. + Don’t include a period at the end. This is shown by + <command>nix-env -q --description</command> and also on the + Nixpkgs release pages. Example: <literal>"A program that produces + a familiar, friendly greeting"</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>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> + +</variablelist> + + +</section> + + +<section><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>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>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> |