[PATCH 0/4] Harmonize @-commands used in doc/guix.texi

index 6671ba9305..4f9eeede8a 100644

@command{inetd} ``superdaemon'', and more. This section describes

those.

This type defines a service that runs a DHCP daemon. To create a

service of this type, you must supply a @code{<dhcpd-configuration>}.

For example:

(config-file (local-file "my-dhcpd.conf"))

(interfaces '("enp0s25"))))

@end lisp

@deftp {Data Type} dhcpd-configuration

@table @asis

@end deftp

@cindex OpenNTPD

Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented

by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system

clock synchronized with that of the given servers.

(constraints-from '("https://www.google.com/"))))

@end lisp

@defvar %openntpd-servers

This variable is a list of the server addresses defined in

base-commit: c0650cf5b749adb3b9bb9c6061ef4f1f9bdc370e

--

2.39.1

index 4f9eeede8a..bf294046db 100644

@code{httpd-config-file} and @code{httpd-virtualhost} record types are

given below.

This data type represents the configuration for the httpd service.

@table @asis

file outside of the store can also be specified through a string.

@end table

This data type represents a module for the httpd service.

@table @asis

"/modules/mod_wsgi.so")}.

@end table

@defvar %default-httpd-modules

A default list of @code{httpd-module} objects.

@end defvar

This data type represents a configuration file for the httpd service.

@table @asis

list.

@end table

This data type represents a virtualhost configuration block for the httpd service.

These should be added to the extra-config for the httpd-service.

of strings and G-expressions.

@end table

@anchor{NGINX}

@subsubheading NGINX

@file{/var/log/nginx/error.log}. The second location can be changed

with the @var{log-directory} configuration option.

This data type represents the configuration for NGinx. Some

configuration can be done through this and the other provided record

types, or alternatively, a config file can be provided.

valued G-expression.

@end table

@anchor{nginx-server-configuration}

@deftp {Data Type} nginx-server-configuration

--

2.39.1

index ed9994a41b..358be58205 100644

@end table

@end deftp

When used in the @emph{lexical scope} of a package field definition, this

identifier resolves to the package being defined.

@end lisp

It is an error to refer to @code{this-package} outside a package definition.

The following helper procedures are provided to help deal with package

inputs.

macro is a helper that can prove useful anytime you want to remove, add,

or replace package inputs.

Modify the given package inputs, as returned by @code{package-inputs} & co.,

according to the given clauses. Each clause must have one of the

following forms:

The last type of clause is @code{append}, to add inputs at the back of

the list.

In some cases, you may find it useful to write functions

(``procedures'', in Scheme parlance) that return a package based on some

@command{sed}. They complement Guile's extensive, but low-level, file

system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).

Run @var{body} with @var{directory} as the process's current directory.

Essentially, this macro changes the current directory to @var{directory}

directory when the dynamic extent of @var{body} is left, be it @i{via}

normal procedure return or @i{via} a non-local exit such as an

exception.

@defun mkdir-p dir

Create directory @var{dir} and all its ancestors.

is true. Report but ignore errors.

@end defun

Substitute @var{regexp} in @var{file} by the string returned by

@var{body}. @var{body} is evaluated with each @var{match-var} bound to

the corresponding positional regexp sub-expression. For example:

Be careful about using @code{$} to match the end of a line; by itself it

won't match the terminating newline of a line.

@subsection File Search

those with tools written with build phases in mind.

@cindex build phases, modifying

Modify @var{phases} sequentially as per each @var{clause}, which may

have one of the following forms:

Where every @var{phase-name} above is an expression evaluating to a

symbol, and @var{new-phase} an expression evaluating to a procedure.

The example below is taken from the definition of the @code{grep}

package. It adds a phase to run after the @code{install} phase, called

The main syntactic forms to deal with monads in general are provided by

the @code{(guix monads)} module and are described below.

Evaluate any @code{>>=} or @code{return} forms in @var{body} as being

in @var{monad}.

Return a monadic value that encapsulates @var{val}.

@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic

procedures @var{mproc}@dots{}@footnote{This operation is commonly

referred to as ``bind'', but that name denotes an unrelated procedure in

@result{} 4

@result{} some-state

@end lisp

Bind the variables @var{var} to the monadic values @var{mval} in

@var{body}, which is a sequence of expressions. As with the bind

operator, this can be thought of as ``unpacking'' the raw, non-monadic

@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}

(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).

Bind @var{mexp} and the following monadic expressions in sequence,

returning the result of the last expression. Every expression in the

sequence must be a monadic expression.

This is akin to @code{mlet}, except that the return values of the

monadic expressions are ignored. In that sense, it is analogous to

@code{begin}, but applied to monadic expressions.

When @var{condition} is true, evaluate the sequence of monadic

expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When

@var{condition} is false, return @code{*unspecified*} in the current

monad. Every expression in the sequence must be a monadic expression.

When @var{condition} is false, evaluate the sequence of monadic

expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When

@var{condition} is true, return @code{*unspecified*} in the current

monad. Every expression in the sequence must be a monadic expression.

@cindex state monad

The @code{(guix monads)} module provides the @dfn{state monad}, which

The syntactic form to construct gexps is summarized below.

Return a G-expression containing @var{exp}. @var{exp} may contain one

or more of the following forms:

G-expressions created by @code{gexp} or @code{#~} are run-time objects

of the @code{gexp?} type (see below).

Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}

in their execution environment.

This form has @emph{lexical} scope: it has an effect on the gexps

directly defined in @var{body}@dots{}, but not on those defined, say, in

procedures called from @var{body}@dots{}.

Mark the gexps defined in @var{body}@dots{} as requiring

@var{extensions} in their build and execution environment.

@var{extensions} is typically a list of package objects such as those

load path while compiling imported modules in @var{body}@dots{}; they

are also added to the load path of the gexp returned by

@var{body}@dots{}.

@defun gexp? obj

Return @code{#t} if @var{obj} is a G-expression.

@dots{})} expression to construct the file name @emph{at run time}.

@end defun

Bind @var{system} to the currently targeted system---e.g.,

@code{"x86_64-linux"}---within @var{body}.

(error "dunno!"))))

"-net" "user" #$image)

@end lisp

This macro is similar to the @code{parameterize} form for

dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU

Guile Reference Manual}). The key difference is that it takes effect

The example above returns an object that corresponds to the i686 build

of Coreutils, regardless of the current value of @code{%current-system}.

Of course, in addition to gexps embedded in ``host'' code, there are

@end table

When used in the @emph{lexical scope} of an operating system field definition,

this identifier resolves to the operating system being defined.

It is an error to refer to @code{this-operating-system} outside an operating

system definition.

@end deftp

@code{modify-services} simply provides a more concise form for this

common pattern.

Modify the services listed in @var{services} according to the given

clauses. Each clause has the form:

@xref{Using the Configuration System}, for example usage.

Next comes the programming interface for service types. This is

something you want to know when writing new service definitions, but not

G-expression (@pxref{G-Expressions}), which should, once serialized to

the disk, return a string. More details are listed below.

Create a record type named @code{@var{name}} that contains the

fields found in the clauses.

(string "test")

"Some documentation."))

@end lisp

Sometimes a field should not be serialized if the user doesn’t specify a

value. To achieve this, you can use the @code{define-maybe} macro to

define a ``maybe type''; if the value of a maybe type is left unset, or

maybe-symbol

"Docstring."))

@end lisp

@defun maybe-value-set? value

Predicate to check whether a user explicitly specified the value of a

--

2.39.1

index bf294046db..ed9994a41b 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. @var{replacements} is a list of

spec/procedures pair; each spec is a package specification such as

@code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching

package and returns a replacement for that package.

The example above could be rewritten this way:

@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 embedded timestamp (as with

@command{gzip --no-name}) and return true. Otherwise return @code{#f}.

When @var{keep-mtime?} is true, preserve @var{file}'s modification time.

@subsection File Manipulation

exception.

@end deffn

Create directory @var{dir} and all its ancestors.

Create @var{directory} if it does not exist and copy @var{file} in there

under the same name.

Make @var{file} writable for its owner.

[#:log (current-output-port)] [#:follow-symlinks? #f] @

[#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]

Copy @var{source} directory to @var{desti