[PATCH] doc: Use the term "Procedure" for definitions.

index f692872c04..958fc44cbd 100644

)))

@end lisp

Return the version string for packages using @code{git-fetch}.

@lisp

@end lisp

@end deffn

Return the version string for packages using @code{hg-fetch}. It works

in the same way as @code{git-version}.

@end deffn

The module @code{(guix build-system elm)} provides the following utilities for

working with names and related conventions:

@var{hash}

Returns a Git origin using the repository naming and tagging regime required

for a published Elm package with the upstream name @var{elm-name} at version

@end lisp

@end deffn

Returns the Guix-style package name for an Elm package with upstream name

@var{elm-name}.

@code{elm->package-name} will produce a given result.

@end deffn

Given an Elm @var{package}, returns the possibly-inferred upstream name, or

@code{#f} the upstream name is not specified via the @code{'upstream-name}

property and can not be inferred by @code{infer-elm-package-name}.

@end deffn

Given the @var{guix-name} of an Elm package, returns the inferred upstream

name, or @code{#f} if the upstream name can't be inferred. If the result is

not @code{#f}, supplying it to @code{elm->package-name} would produce

diff --git a/doc/guix.texi b/doc/guix.texi

index 7f8d8d66e9..b194d4128a 100644

The @code{(guix inferior)} module provides the following procedures to open an

inferior:

Return an inferior for @var{channels}, a list of channels. Use the cache at

@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.

This procedure opens a new connection to the build daemon.

As a side effect, this procedure may build or substitute binaries for

@var{channels}, which can take time.

Open the inferior Guix in @var{directory}, running

@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if

the inferior could not be launched.

@cindex inferior packages

The procedures listed below allow you to obtain and manipulate inferior

packages.

Return the list of packages known to @var{inferior}.

Return the sorted list of inferior packages matching @var{name} in

@var{inferior}, with highest version numbers first. If @var{version} is true,

return only packages with a version number prefixed by @var{version}.

Return true if @var{obj} is an inferior package.

These procedures are the counterpart of package record accessors

(@pxref{package Reference}). Most of them work by querying the inferior

@var{package} comes from, so the inferior must still be live when you call

these procedures.

Inferior packages can be used transparently like any other package or

file-like object in G-expressions (@pxref{G-Expressions}). They are also

The build actions it prescribes may then be realized by using the

@code{build-derivations} procedure (@pxref{The Store}).

Return the @code{<derivation>} object of @var{package} for @var{system}

(@pxref{Derivations}).

@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}

must be a connection to the daemon, which operates on the store

(@pxref{The Store}).

@noindent

@cindex cross-compilation

Similarly, it is possible to compute a derivation that cross-builds a

package for some other system:

Return the @code{<derivation>} object of @var{package} cross-built from

@var{system} to @var{target}.

@var{target} must be a valid GNU triplet denoting the target hardware

and operating system, such as @code{"aarch64-linux-gnu"}

(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).

Once you have package definitions, you can easily define @emph{variants}

of those packages. @xref{Defining Package Variants}, for more on that.

The following helper procedures are provided to help deal with package

inputs.

Look up @var{name} among @var{package}'s inputs (or native, propagated,

or direct inputs). Return it if found, @code{#f} otherwise.

In this example we obtain the @code{gmp} package that is among the

direct inputs of @code{coreutils}.

@cindex development inputs, of a package

@cindex implicit inputs, of a package

package is compiled. This is what the @code{package-development-inputs}

procedure returns.

Return the list of inputs required by @var{package} for development

purposes on @var{system}. When @var{target} is true, return the inputs

needed to cross-compile @var{package} from @var{system} to

gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph

hello} would show you explicit inputs, whereas @command{guix graph -t

bag hello} would include implicit inputs (@pxref{Invoking guix graph}).

Because packages are regular Scheme objects that capture a complete

dependency graph and associated build procedures, it is often useful to

thereof according to some parameters. Below are a few examples.

@cindex tool chain, choosing a package's tool chain

Return a variant of @var{package} that uses @var{toolchain} instead of

the default GNU C/C++ toolchain. @var{toolchain} must be a list of

inputs (label/package tuples) providing equivalent functionality, such

procedure works by changing the build system of @var{package} so that it

pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},

for more on build systems.

@node origin Reference

@subsection @code{origin} Reference

download)} module provides the most common method, @code{url-fetch},

described below.

Return a fixed-output derivation that fetches data from @var{url} (a

string, or a list of strings denoting alternate URLs), which is expected

to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,

Alternatively, when URL starts with @code{file://}, return the

corresponding file name in the store.

Likewise, the @code{(guix git-download)} module defines the

@code{git-fetch} origin method, which fetches data from a Git version

control repository, and the @code{git-reference} data type to describe

the repository and revision to fetch.

Return a fixed-output derivation that fetches @var{ref}, a

@code{<git-reference>} object. The output is expected to have recursive

hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as

the file name, or a generic name if @code{#f}.

@deftp {Data Type} git-reference

This data type represents a Git reference for @code{git-fetch} to

the @code{hg-fetch} origin method and @code{hg-reference} data type for

support of the Mercurial version control system.

Return a fixed-output derivation that fetches @var{ref}, a

@code{<hg-reference>} object. The output is expected to have recursive

hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as

the file name, or a generic name if @code{#false}.

@node Defining Package Variants

@section Defining Package Variants

that directly maps to the more sophisticated package transformation

options (@pxref{Package Transformation Options}):

Return a procedure that, when passed an object to build (package,

derivation, etc.), applies the transformations specified by @var{opts} and returns

the resulting objects. @var{opts} must be a list of symbol/string pairs such as:

Each symbol names a transformation and the corresponding string is an argument

to that transformation.

For instance, a manifest equivalent to this command:

graph, is what the @code{package-input-rewriting} procedure in

@code{(guix packages)} implements.

Return a procedure that, when passed a package, replaces its direct and

indirect dependencies, including implicit inputs when @var{deep?} is

true, according to @var{replacements}. @var{replacements} is a list of

Optionally, @var{rewrite-name} is a one-argument procedure that takes

the name of a package and returns its new name after rewrite.

@noindent

Consider this example:

The following variant of @code{package-input-rewriting} can match packages to

be replaced by name rather than by identity.

Return a procedure that, given a package, applies the given

@var{replacements} to all the package graph, including implicit inputs

unless @var{deep?} is false.

@code{package-mapping}: it supports arbitrary changes to nodes in the

graph.

Return a procedure that, given a package, applies @var{proc} to all the packages

depended on and returns the resulting package. The procedure stops recursion

when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is

applied to implicit inputs as well.

@node Writing Manifests

@section Writing Manifests

@end table

@end deftp

Concatenate the manifests listed in @var{lst} and return the resulting

manifest.

@c TODO: <manifest-pattern>, manifest-lookup, manifest-remove, etc.

Return a manifest entry for the @var{output} of package @var{package},

where @var{output} defaults to @code{"out"}, and with the given

@var{properties}. By default @var{properties} is the empty list or, if

(manifest (list (package->manifest-entry git)

(package->manifest-entry git "send-email")))

@end lisp

Return a list of manifest entries, one for each item listed in

@var{packages}. Elements of @var{packages} can be either package

objects or package/string tuples denoting a specific output of a

(packages->manifest (list git `(,git "send-email")))

@end lisp

@anchor{package-development-manifest}

Return a manifest for the @dfn{development inputs} of @var{package} for

@var{system}, optionally when cross-compiling to @var{target}.

Development inputs include both explicit and implicit inputs of

(GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a

couple of additional development tools---these are the dependencies

@command{guix show inkscape} lists.

@c TODO: Move (gnu packages) interface to a section of its own.

to build manifests. In particular, it lets you look up packages by

name---see below.

Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"}

or @code{"guile:debug"}, return a manifest. Specs have the format that

command-line tools such as @command{guix install} and @command{guix

the right set of modules, and referring to the right variables.

Instead, we directly refer to packages in the same way as on the command

line, which can often be more convenient.

@c TODO: specifications->package, etc.

This section documents procedures that deal with store file names.

Return the directory name of the store.

Return true if @var{file} is in the store.

Strip the @file{/gnu/store} and hash from @var{file}, a store file name.

The result is typically a @code{"@var{package}-@var{version}"} string.

Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two

values: @code{"foo"} and @code{"0.9.1b"}. When the version part is

unavailable, @var{name} and @code{#f} are returned. The first hyphen

followed by a digit is considered to introduce the version part.

@subsection File Types

The procedures below deal with files and file types.

Return @code{#t} if @var{dir} exists and is a directory.

Return @code{#t} if @var{file} exists and is executable.

Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').

Return @code{#t} if @var{file} is, respectively, an ELF file, an

@code{ar} archive (such as a @file{.a} static library), or a gzip file.

If @var{file} is a gzip file, reset its