From mboxrd@z Thu Jan 1 00:00:00 1970 From: taylanbayirli@gmail.com (Taylan Ulrich =?utf-8?Q?Bay=C4=B1rl=C4=B1?= =?utf-8?Q?=2FKammer?=) Subject: Re: [PATCH] doc: Document native-inputs and propagated-inputs. Date: Fri, 15 May 2015 21:57:39 +0200 Message-ID: <87pp61pqa4.fsf@T420.taylan> References: <87oalmhoxy.fsf@gmail.com> <87d2222kss.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:48217) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YtLjs-0008Tf-AJ for guix-devel@gnu.org; Fri, 15 May 2015 15:57:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YtLjq-0007b6-Q4 for guix-devel@gnu.org; Fri, 15 May 2015 15:57:44 -0400 In-Reply-To: <87d2222kss.fsf@gnu.org> ("Ludovic \=\?utf-8\?Q\?Court\=C3\=A8s\=22'\?\= \=\?utf-8\?Q\?s\?\= message of "Fri, 15 May 2015 12:32:19 +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: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: guix-devel@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable ludo@gnu.org (Ludovic Court=C3=A8s) writes: > More importantly, I think we should have a =E2=80=9Cpackage Reference=E2= =80=9D section > (akin to the existing =E2=80=9Coperating-system Reference=E2=80=9D sectio= n) right after > =E2=80=9CDefining Packages.=E2=80=9D That way, we could keep =E2=80=9CDe= fining Packages=E2=80=9D simple > and concise, and simply cross-ref to the reference section for details. > > That=E2=80=99s more work, but that=E2=80=99d be real cool. WDYT? :-) I had a go at it but could not immediately figure out the meanings of some package and origin fields. Help much appreciated. :-) Patch so far: --=-=-= Content-Type: text/x-diff; charset=utf-8 Content-Disposition: inline; filename=0001-doc-Add-package-Reference-and-origin-Reference-secti.patch Content-Transfer-Encoding: quoted-printable >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" sectio= ns. * doc/guix.texi (Defining Packages): Link to "package Reference". Add menu. (package Reference, origin Reference): New subsections. --- doc/guix.texi | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 161 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index 049292d..c91c910 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1793,6 +1793,8 @@ However, any other dependencies need to be specified = in the unavailable to the build process, possibly leading to a build failure. @end itemize =20 +See @pxref{package Reference} for a full description of possible fields. + Once a package definition is in place, the package may actually be built using the @code{guix build} command-line tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for @@ -1837,6 +1839,165 @@ and operating system, such as @code{"mips64el-linux= -gnu"} Configure and Build System}). @end deffn =20 +@menu +* package Reference :: The package data type. +* origin Reference:: The origin data type. +@end menu + + +@node package Reference +@subsection package Reference + +This section summarizes all the options available in =E2=80=98package=E2= =80=99 +declarations (@pxref{Defining Packages}). + +@deftp {Data Type} package +This is the data type representing a package recipe. + +@table @asis +@item @code{name} +The name of the package, as a string. + +@item @code{version} +The version of the package, as a string. + +@item @code{source} +An origin object (@pxref{origin Reference}) telling how the source +code for the package should be acquired. + +@item @code{build-system} +The build system (@pxref{Build Systems}) that should be used to +build the package. + +@item @code{arguments} (default: @code{'()}) +The arguments that should be passed to the build system. This is a +list, typically containing sequential keyword-value pairs. + +@item @code{inputs} (default: @code{'()}) +Package or derivation inputs to the build. This is a list of lists, +where each list has the name of the input (a string) as its first +element, a package or derivation object as its second element, and +optionally the name of the output of the package or derivation that +should be used, which defaults to @code{"out"}. + +@item @code{propagated-inputs} (default: @code{'()}) +This field is like @code{inputs}, but the specified packages will be +force-installed alongside the package they belong to. For example this +is necessary when a library needs headers of another library to compile, +or needs another shared library to be linked alongside itself when a +program wants to link to it. + +@item @code{native-inputs} (default: @code{'()}) +This field is like @code{inputs}, but in case of a cross-compilation it +will be ensured that packages for the architecture of the build machine +are present, such that executables from them can be used during the +build. For example, this is necessary for build tools such as Autoconf, +Libtool, pkg-config, or Gettext. + +@item @code{self-native-input?} (default: @code{#f}) +This is a Boolean field telling whether the package should use itself as +a native input when cross-compiling. + +@item @code{outputs} (default: @code{'("out")}) +The list of output names of the package. + +@item @code{native-search-paths} (default: @code{'()}) +FIXME + +@item @code{search-paths} (default: @code{'()}) +FIXME + +@item @code{replacement} (default: @code{'()}) +FIXME + +@item @code{synopsis} +A one-line description of the package. + +@item @code{description} +A more elaborate description of the package. + +@item @code{license} +The license of the package; a value from @code{(guix licenses)}. + +@item @code{home-page} +The URL to the home-page of the package, as a string. + +@item @code{supported-systems} (default: @var{%supported-systems}) +The list of systems supported by the package, as strings of the form +@code{architecture-kernel}, for example @code{"x86_64-linux"}. + +@item @code{maintainers} (default: @code{'()}) +The list of maintainers of the package. FIXME: upstream, or package +recipe? + +@item @code{properties} (default: @code{'()}) +An alist of arbitrary properties of the package. + +@item @code{location} (default: source location of the @code{package} form) +The source location of the package. It's useful to override this when +inheriting from another package, in which case this field is not +automatically corrected. +@end table +@end deftp + + +@node origin Reference +@subsection origin Reference + +This section summarizes all the options available in @code{origin} +declarations (@pxref{Defining Packages}). + +@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. + +@item @code{method} +A procedure that will handle the URI, such as @code{url-fetch}. + +@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 +base-32 string. + +@item @code{file-name} (default: @code{#f}) +The file name under which the source code should be saved. When this is +@code{#f}, a sensible default value will be used in most cases. In case +the source is fetched from a URL, the file name from the URL will be +used. For version control checkouts, it's recommended to provide the +file name explicitly because the default is not very descriptive. + +@item @code{patches} (default: @code{'()}) +A list of file names containing patches to be applied to the source. + +@item @code{snippet} (default: @code{#f}) +A quoted piece of code that will be run in the source directory to make +any modifications, which is sometimes more convenient than a patch. + +@item @code{patch-flags} (default: @code{'("-p1")}) +A list of command-line flags that should be passed to the @code{patch} +command. + +@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. + +@item @code{modules} (default: @code{'()}) +A list of Guile modules that should be loaded during the patching +process and while running the code in the @code{snippet} field. + +@item @code{imported-modules} (default: @code{'()}) +FIXME + +@item @code{patch-guile} (default: @code{#f}) +The Guile package that should be used in the patching process. When +this is @code{#f}, a sensible default is used. +@end table +@end deftp + =20 @node Build Systems @section Build Systems --=20 2.2.1 --=-=-=--