From 79d3e0926d68bb760f1a9f28c862c38e6cd8cc45 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 10 Feb 2009 23:29:42 +0000 Subject: * Started documenting the meta attributes, including a first (very incomplete) attempt at standardising the license attribute. svn path=/nixpkgs/trunk/; revision=14028 --- doc/meta.xml | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 doc/meta.xml (limited to 'doc/meta.xml') 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 @@ + + +Meta-attributes + +Nix packages can declare meta-attributes +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 meta declaration like this: + + +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+"; +}; + + + + +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. + +The meta-attributes of a package can be queried from the +command-line using nix-env: + + +$ 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> + + +nix-env knows about the +description field specifically: + + +$ nix-env -qa hello --description +hello-2.3 A program that produces a familiar, friendly greeting + + + + + +
Standard meta-attributes + +The following meta-attributes have a standard +interpretation: + + + + + description + A short (one-line) description of the package. + Don’t include a period at the end. This is shown by + nix-env -q --description and also on the + Nixpkgs release pages. Example: "A program that produces + a familiar, friendly greeting" + + + + longDescription + An arbitrarily long description of the + package. + + + + homepage + The package’s homepage. Example: + http://www.gnu.org/software/hello/manual/ + + + + license + The license for the package. See below for the + allowed values. + + + + priority + The priority of the package, + used by nix-env to resolve file name conflicts + between packages. See the Nix manual page for + nix-env for details. Example: + "10" (a low-priority + package). + + + + + +
+ + +
Licenses + +This is just a first attempt at standardising the license +attribute. + +The meta.license attribute must be one of the +following: + + + + + GPL + GNU General Public License; version not + specified. + + + + GPLv2 + GNU General Public License, version + 2. + + + + GPLv2+ + GNU General Public License, version + 2 or higher. + + + + GPLv3 + GNU General Public License, version + 3. + + + + GPLv3+ + GNU General Public License, version + 3 or higher. + + + + free + Catch-all for free software licenses not listed + above. + + + + free-copyleft + Catch-all for free, copyleft software licenses not + listed above. + + + + unfree-redistributable + Unfree package that can be redistributed in binary + form. That is, it’s legal to redistribute the + output of the derivation. This means that + the package can be included in the Nixpkgs + channel. + + 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 patchelf to make them + work. Thus, its license is unfree and it + cannot be included in the Nixpkgs channel. + + + + unfree + 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. + + + + unfree-redistributable-firmware + This package supplies unfree, redistributable + firmware. This is a separate value from + unfree-redistributable because not everybody + cares whether firmware is free. + + + + + + + +
+ + + -- cgit 1.4.1