diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/contributing.xml | 21 | ||||
-rw-r--r-- | doc/manual.xml | 1 | ||||
-rw-r--r-- | doc/meta.xml | 155 | ||||
-rw-r--r-- | doc/quick-start.xml | 14 |
4 files changed, 85 insertions, 106 deletions
diff --git a/doc/contributing.xml b/doc/contributing.xml new file mode 100644 index 000000000000..bcea404baee0 --- /dev/null +++ b/doc/contributing.xml @@ -0,0 +1,21 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="chap-contributing"> + +<title>Contributing</title> + +<para>If you make modifications to the manual, it's important to build the manual before contributing:</para> + +<orderedlist> + + <listitem><para><command>$ git clone git://github.com/NixOS/nixpkgs.git</command></para></listitem> + + <listitem><para><command>$ cd nixpkgs/pkgs/top-level</command></para></listitem> + + <listitem><para><command>$ nix-build -A tarball release.nix</command></para></listitem> + + <listitem><para>Inside the built derivation you shall see <literal>manual/index.html</literal> file.</para></listitem> + +</orderedlist> + +</chapter> diff --git a/doc/manual.xml b/doc/manual.xml index d2c07859b281..145e3e12dd92 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -32,6 +32,7 @@ <xi:include href="language-support.xml" /> <xi:include href="package-notes.xml" /> <xi:include href="coding-conventions.xml" /> + <xi:include href="contributing.xml" /> </book> diff --git a/doc/meta.xml b/doc/meta.xml index 6c8e458509a7..272e812a03bb 100644 --- a/doc/meta.xml +++ b/doc/meta.xml @@ -17,7 +17,9 @@ meta = { It is fully customizable. ''; homepage = http://www.gnu.org/software/hello/manual/; - license = "GPLv3+"; + license = stdenv.lib.licenses.gpl3Plus; + maintainers = [ stdenv.lib.maintainers.eelco ]; + platforms = stdenv.lib.platforms.all; }; </programlisting> @@ -31,16 +33,42 @@ the package. The value of a meta-attribute must a string.</para> 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> +$ nix-env -qa hello --meta --json +{ + "hello": { + "meta": { + "description": "A program that produces a familiar, friendly greeting", + "homepage": "http://www.gnu.org/software/hello/manual/", + "license": { + "fullName": "GNU General Public License version 3 or later", + "shortName": "GPLv3+", + "url": "http://www.fsf.org/licensing/licenses/gpl.html" + }, + "longDescription": "GNU Hello is a program that prints \"Hello, world!\" when you run it.\nIt is fully customizable.\n", + "maintainers": [ + "Ludovic Court\u00e8s <ludo@gnu.org>" + ], + "platforms": [ + "i686-linux", + "x86_64-linux", + "armv5tel-linux", + "armv7l-linux", + "mips64el-linux", + "x86_64-darwin", + "i686-cygwin", + "i686-freebsd", + "x86_64-freebsd", + "i686-openbsd", + "x86_64-openbsd" + ], + "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/ex-2/default.nix:14" + }, + "name": "hello-2.9", + "system": "x86_64-linux" + } +} + + </screen> <command>nix-env</command> knows about the @@ -92,20 +120,22 @@ interpretation:</para> <varlistentry> <term><varname>license</varname></term> - <listitem><para>The license for the package. See below for the - allowed values.</para></listitem> + <listitem><para>The license for the package. One from attribute set defined in + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/licenses.nix"> + <filename>nixpkgs/lib/licenses.nix</filename></link>. + Example: + <literal>stdenv.lib.licenses.gpl3</literal>.</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 + maintainers of this Nix expression. If + you would like to be a maintainer of a package, 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> + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/maintainers.nix"><filename>nixpkgs/lib/maintainers.nix</filename></link> + and write something like <literal>[ stdenv.lib.maintainers.alice + stdenv.lib.maintainers.bob ]</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -121,29 +151,25 @@ interpretation:</para> <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: + package is supported. Hydra builds packages according to the + platform specified. If no platform is specified, the package does + not have prebuilt binaries. 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; +meta.platforms = stdenv.lib.platforms.linux; </programlisting> + Attribute Set <varname>stdenv.lib.platforms</varname> in + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/lib/platforms.nix"> + <filename>nixpkgs/lib/platforms.nix</filename></link> defines various common + lists of platforms types. </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 + instance at <literal>hydra.nixos.org</literal> will 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 @@ -176,81 +202,18 @@ meta.hydraPlatforms = []; <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 +<para>The <varname>meta.license</varname> attribute could 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 diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 49c674052b95..0f11a906d771 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -155,9 +155,10 @@ $ git add pkgs/development/libraries/libfoo/default.nix</screen> </listitem> <listitem> - <para>You can use <command>nix-prefetch-url</command> + <para>You can use <command>nix-prefetch-url</command> (or similar nix-prefetch-git, etc) <replaceable>url</replaceable> to get the SHA-256 hash of - source distributions.</para> + source distributions. There are similar commands as <command>nix-prefetch-git</command> and + <command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package.</para> </listitem> <listitem> @@ -221,17 +222,10 @@ $ nix-env -f . -iA libfoo</screen> </listitem> <listitem> - <para>Optionally commit the new package, or send a patch to + <para>Optionally commit the new package and open a pull request, or send a patch to <literal>nix-dev@cs.uu.nl</literal>.</para> </listitem> - <listitem> - <para>If you want the TU Delft build farm to build binaries of the - package and make them available in the <link - xlink:href="http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable/"><literal>nixpkgs</literal> - channel</link>, add it to <link - xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/release.nix"><filename>pkgs/top-level/release.nix</filename></link>.</para> - </listitem> </orderedlist> |