From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: [PATCH] doc: Document native-inputs and propagated-inputs. Date: Sat, 16 May 2015 21:36:09 +0200 Message-ID: <87y4konwly.fsf@gnu.org> References: <87oalmhoxy.fsf@gmail.com> <87d2222kss.fsf@gnu.org> <87pp61pqa4.fsf@T420.taylan> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40280) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ythsm-00085X-C9 for guix-devel@gnu.org; Sat, 16 May 2015 15:36:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Ythsi-0004Zh-VU for guix-devel@gnu.org; Sat, 16 May 2015 15:36:24 -0400 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:57100) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ythsi-0004Zd-S2 for guix-devel@gnu.org; Sat, 16 May 2015 15:36:20 -0400 In-Reply-To: <87pp61pqa4.fsf@T420.taylan> ("Taylan Ulrich \=\?utf-8\?Q\?\=5C\=22Bay\=C4\=B1rl\=C4\=B1\=2FKammer\=5C\=22\=22's\?\= message of "Fri, 15 May 2015 21:57:39 +0200") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Taylan Ulrich =?utf-8?Q?=22Bay=C4=B1rl=C4=B1?= =?utf-8?Q?=2FKammer=22?= Cc: guix-devel@gnu.org taylanbayirli@gmail.com (Taylan Ulrich "Bay=C4=B1rl=C4=B1/Kammer") skribis: > From 948fcdbb0cea1b8fcd7907554c61633db2f54dd8 Mon Sep 17 00:00:00 2001 > From: =3D?UTF-8?q?Taylan=3D20Ulrich=3D20Bay=3DC4=3DB1rl=3DC4=3DB1/Kammer?= =3D > > Date: Fri, 15 May 2015 21:54:11 +0200 > Subject: [PATCH] doc: Add "package Reference" and "origin Reference" sect= ions. > > * doc/guix.texi (Defining Packages): Link to "package Reference". Add me= nu. > (package Reference, origin Reference): New subsections. This looks great! > +See @pxref{package Reference} for a full description of possible fields. Should be: @xref{package Reference}, for a full description... (@xref generates =E2=80=9CSee=E2=80=9D and must be followed by a comma.) > +@node package Reference > +@subsection package Reference @subsection @code{package} Reference (Same for the second subsection.) > +This section summarizes all the options available in =E2=80=98package=E2= =80=99 @code{package} > +@item @code{build-system} > +The build system (@pxref{Build Systems}) that should be used to > +build the package. In general try to put parentheses at the end of the sentence so that it=E2=80=99s easier to read. > +@item @code{outputs} (default: @code{'("out")}) > +The list of output names of the package. + @xref{Packages with Multiple Outputs}, for typical uses of additional outputs. > +@item @code{native-search-paths} (default: @code{'()}) > +FIXME > + > +@item @code{search-paths} (default: @code{'()}) > +FIXME You can group both with @itemx. For now, let=E2=80=99s just say that it=E2= =80=99s a list of @code{search-path-specification} objects describing search-path environment variables honored by the package. We can write the =E2=80=98search-path-specification=E2=80=99 reference another day. ;-) > +@item @code{replacement} (default: @code{'()}) > +FIXME Default is @code{#f}. Something like: This must either @code{#f} or a package object that will be used as a @dfn{replacement} for this package. @xref{Security Updates, grafts}, for details. > +@item @code{maintainers} (default: @code{'()}) > +The list of maintainers of the package. FIXME: upstream, or package > +recipe? It=E2=80=99s still unused, but it=E2=80=99s meant to be the list of downstr= eam package maintainers, represented as a list of objects (imagine a (guix maintainers) module akin to (guix licenses) where we would all live.) Probably now would be a good time to start discussing it. > +@item @code{properties} (default: @code{'()}) > +An alist of arbitrary properties of the package. Leave that one undocumented (it=E2=80=99s currently unused and I=E2=80=99m = not sure it=E2=80=99s useful.) [...] > +@deftp {Data Type} origin > +This is the data type representing a source code origin. > + > +@table @asis > +@item @code{uri} > +A string containing the URI of the source. s/A string/An object/ You can add: The object type depends on the @code{method} (see below.) For example, when using the @var{url-fetch} method of @code{(guix download)}, the valid @code{uri} values are: a URL represented as a string, or a list thereof. > +@item @code{method} > +A procedure that will handle the URI, such as @code{url-fetch}. s/,.*// Add a paragraph: Examples include: @table @asis @item @var{url-fetch} from @code{(guix download)} download a file the HTTP, HTTPS, or FTP URL specified in the @code{uri} field; @item @var{git-fetch} from @code{(guix git-download)} clone the Git version control repository, and check out the revision specified in the @code{uri} field as a @code{git-reference} object; a @code{git-reference} looks like this: @example (git-reference (url "git://git.debian.org/git/pkg-shadow/shadow") (commit "v4.1.5.1")) @end example @end @table > +@item @code{sha256} > +A bytevector containing the SHA-256 hash of the source. Typically the > +@code{base32} procedure is used here to generate the bytevector from a s/procedure/form/ > +@item @code{patch-inputs} (default: @code{#f}) > +Input packages or derivations to the patching process. When this is > +@code{#f}, the usual set of inputs necessary for patching are provided, > +such as GNU Patch. GNU@tie{}Patch > +@item @code{imported-modules} (default: @code{'()}) The list of Guile modules to import in the patch derivation, for use by the @code{snippet}. Could you send an updated patch? Excellent work, thank you! Ludo=E2=80=99.