[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] doc: Document native-inputs and propagated-inputs.
From: |
Taylan Ulrich Bayırlı/Kammer |
Subject: |
Re: [PATCH] doc: Document native-inputs and propagated-inputs. |
Date: |
Fri, 15 May 2015 21:57:39 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
address@hidden (Ludovic Courtès) writes:
> More importantly, I think we should have a “package Reference” section
> (akin to the existing “operating-system Reference” section) right after
> “Defining Packages.” That way, we could keep “Defining Packages” simple
> and concise, and simply cross-ref to the reference section for details.
>
> That’s more work, but that’d 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:
>From 948fcdbb0cea1b8fcd7907554c61633db2f54dd8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Taylan=20Ulrich=20Bay=C4=B1rl=C4=B1/Kammer?=
<address@hidden>
Date: Fri, 15 May 2015 21:54:11 +0200
Subject: [PATCH] doc: Add "package Reference" and "origin Reference" sections.
* 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
+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
address@hidden
+* package Reference :: The package data type.
+* origin Reference:: The origin data type.
address@hidden menu
+
+
address@hidden package Reference
address@hidden package Reference
+
+This section summarizes all the options available in ‘package’
+declarations (@pxref{Defining Packages}).
+
address@hidden {Data Type} package
+This is the data type representing a package recipe.
+
address@hidden @asis
address@hidden @code{name}
+The name of the package, as a string.
+
address@hidden @code{version}
+The version of the package, as a string.
+
address@hidden @code{source}
+An origin object (@pxref{origin Reference}) telling how the source
+code for the package should be acquired.
+
address@hidden @code{build-system}
+The build system (@pxref{Build Systems}) that should be used to
+build the package.
+
address@hidden @code{arguments} (default: @code{'()})
+The arguments that should be passed to the build system. This is a
+list, typically containing sequential keyword-value pairs.
+
address@hidden @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"}.
+
address@hidden @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.
+
address@hidden @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.
+
address@hidden @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.
+
address@hidden @code{outputs} (default: @code{'("out")})
+The list of output names of the package.
+
address@hidden @code{native-search-paths} (default: @code{'()})
+FIXME
+
address@hidden @code{search-paths} (default: @code{'()})
+FIXME
+
address@hidden @code{replacement} (default: @code{'()})
+FIXME
+
address@hidden @code{synopsis}
+A one-line description of the package.
+
address@hidden @code{description}
+A more elaborate description of the package.
+
address@hidden @code{license}
+The license of the package; a value from @code{(guix licenses)}.
+
address@hidden @code{home-page}
+The URL to the home-page of the package, as a string.
+
address@hidden @code{supported-systems} (default: @var{%supported-systems})
+The list of systems supported by the package, as strings of the form
address@hidden, for example @code{"x86_64-linux"}.
+
address@hidden @code{maintainers} (default: @code{'()})
+The list of maintainers of the package. FIXME: upstream, or package
+recipe?
+
address@hidden @code{properties} (default: @code{'()})
+An alist of arbitrary properties of the package.
+
address@hidden @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.
address@hidden table
address@hidden deftp
+
+
address@hidden origin Reference
address@hidden origin Reference
+
+This section summarizes all the options available in @code{origin}
+declarations (@pxref{Defining Packages}).
+
address@hidden {Data Type} origin
+This is the data type representing a source code origin.
+
address@hidden @asis
address@hidden @code{uri}
+A string containing the URI of the source.
+
address@hidden @code{method}
+A procedure that will handle the URI, such as @code{url-fetch}.
+
address@hidden @code{sha256}
+A bytevector containing the SHA-256 hash of the source. Typically the
address@hidden procedure is used here to generate the bytevector from a
+base-32 string.
+
address@hidden @code{file-name} (default: @code{#f})
+The file name under which the source code should be saved. When this is
address@hidden, 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.
+
address@hidden @code{patches} (default: @code{'()})
+A list of file names containing patches to be applied to the source.
+
address@hidden @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.
+
address@hidden @code{patch-flags} (default: @code{'("-p1")})
+A list of command-line flags that should be passed to the @code{patch}
+command.
+
address@hidden @code{patch-inputs} (default: @code{#f})
+Input packages or derivations to the patching process. When this is
address@hidden, the usual set of inputs necessary for patching are provided,
+such as GNU Patch.
+
address@hidden @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.
+
address@hidden @code{imported-modules} (default: @code{'()})
+FIXME
+
address@hidden @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.
address@hidden table
address@hidden deftp
+
@node Build Systems
@section Build Systems
--
2.2.1