From patchwork Fri Jun 2 15:55:29 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Ludovic_Court=C3=A8s?= X-Patchwork-Id: 50549 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 87D5A27BBE9; Fri, 2 Jun 2023 16:57:40 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 2235427BBEB for ; Fri, 2 Jun 2023 16:57:31 +0100 (BST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1q579F-0001J3-63; Fri, 02 Jun 2023 11:57:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q579D-0001Ir-DJ for guix-patches@gnu.org; Fri, 02 Jun 2023 11:57:03 -0400 Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1q579D-0005oG-49 for guix-patches@gnu.org; Fri, 02 Jun 2023 11:57:03 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1q579C-0004zh-DD; Fri, 02 Jun 2023 11:57:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#63851] [PATCH] doc: Use the term "Procedure" for definitions. Resent-From: Ludovic =?utf-8?q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: mirai@makinata.eu, guix-patches@gnu.org Resent-Date: Fri, 02 Jun 2023 15:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 63851 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 63851@debbugs.gnu.org Cc: Ludovic =?utf-8?q?Court=C3=A8s?= , Bruno Victal X-Debbugs-Original-To: guix-patches@gnu.org X-Debbugs-Original-Xcc: Bruno Victal Received: via spool by submit@debbugs.gnu.org id=B.168572136819123 (code B ref -1); Fri, 02 Jun 2023 15:57:02 +0000 Received: (at submit) by debbugs.gnu.org; 2 Jun 2023 15:56:08 +0000 Received: from localhost ([127.0.0.1]:40725 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1q578H-0004yI-Tr for submit@debbugs.gnu.org; Fri, 02 Jun 2023 11:56:08 -0400 Received: from lists.gnu.org ([209.51.188.17]:45086) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1q578D-0004xm-Po for submit@debbugs.gnu.org; Fri, 02 Jun 2023 11:56:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q5787-0006Cg-Bk for guix-patches@gnu.org; Fri, 02 Jun 2023 11:55:55 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q5786-0005Qg-Qk; Fri, 02 Jun 2023 11:55:54 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:Subject:To:From:in-reply-to: references; bh=1gBJHmGlYK5HP2EsOVI2dTev5kY3C/CvtHQ+bEEfkPQ=; b=b+cTGzIKGldfzy 8XFubZ5Kn6RHs9w4lyIuncc1JzBOclo4tHEIlY2Uv3TFmaS2MRgJdRmaoiYODaa67nO731qg8vc7j fyjHjiQYkKR4YZEgpyT1WbRnLSAIQOgCQixt8EL3aN6/+085EiFaQRb949ZHBd3d3xu3E8KmMV+UD dOe3RUNBQ95nD2nCaLrd7Ef7y/zp4/D/2eXK8ASPUxMy/UIdslHq4km0mvj241ZUeMxK2rWvkuP4q AjmXurNGgg9IdW6E79Z2YjLSSSBQWWCE2raHuT9iKlzdkBoWbIygS5jarLewMCzYHFyVEGsHEGu56 37ly/mDxEj5C+VTLWQAA==; Received: from [193.50.110.155] (helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q577n-0004rf-JL; Fri, 02 Jun 2023 11:55:48 -0400 From: Ludovic =?utf-8?q?Court=C3=A8s?= Date: Fri, 2 Jun 2023 17:55:29 +0200 Message-Id: X-Mailer: git-send-email 2.40.1 MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches In an effort to homogenize things, commit 3c40dfe2851dd4ef48d2711f9f3531c06afbe1f2 replaced: @deffn {Scheme Procedure} with: @defun However, the latter prints "Function" when all existing material about Scheme uses the term "procedure". Thus, for consistency, this commit switches to: @deffn {Procedure} * doc/guix.texi, doc/contributing.texi: Use "@deffn {Procedure}" consistently rather than "@defun" or similar. --- doc/contributing.texi | 12 +- doc/guix.texi | 492 +++++++++++++++++++++--------------------- 2 files changed, 252 insertions(+), 252 deletions(-) base-commit: 69dfdb7bd190a1562eb11555da6f556b222245d3 diff --git a/doc/contributing.texi b/doc/contributing.texi index f692872c04..958fc44cbd 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -617,7 +617,7 @@ Version Numbers ))) @end lisp -@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT} +@deffn {Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT} Return the version string for packages using @code{git-fetch}. @lisp @@ -626,7 +626,7 @@ Version Numbers @end lisp @end deffn -@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET} +@deffn {Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET} Return the version string for packages using @code{hg-fetch}. It works in the same way as @code{git-version}. @end deffn @@ -970,7 +970,7 @@ Elm Packages The module @code{(guix build-system elm)} provides the following utilities for working with names and related conventions: -@deffn {Scheme procedure} elm-package-origin @var{elm-name} @var{version} @ +@deffn {Procedure} elm-package-origin @var{elm-name} @var{version} @ @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 @@ -990,7 +990,7 @@ Elm Packages @end lisp @end deffn -@deffn {Scheme procedure} elm->package-name @var{elm-name} +@deffn {Procedure} elm->package-name @var{elm-name} Returns the Guix-style package name for an Elm package with upstream name @var{elm-name}. @@ -998,13 +998,13 @@ Elm Packages @code{elm->package-name} will produce a given result. @end deffn -@deffn {Scheme procedure} guix-package->elm-name @var{package} +@deffn {Procedure} guix-package->elm-name @var{package} 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 -@deffn {Scheme procedure} infer-elm-package-name @var{guix-name} +@deffn {Procedure} infer-elm-package-name @var{guix-name} 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 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5038,57 +5038,57 @@ Inferiors The @code{(guix inferior)} module provides the following procedures to open an inferior: -@defun inferior-for-channels channels [#:cache-directory] [#:ttl] +@deffn {Procedure} inferior-for-channels channels [#:cache-directory] [#:ttl] 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. -@end defun +@end deffn -@defun open-inferior directory [#:command "bin/guix"] +@deffn {Procedure} open-inferior directory [#:command "bin/guix"] 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. -@end defun +@end deffn @cindex inferior packages The procedures listed below allow you to obtain and manipulate inferior packages. -@defun inferior-packages inferior +@deffn {Procedure} inferior-packages inferior Return the list of packages known to @var{inferior}. -@end defun +@end deffn -@defun lookup-inferior-packages inferior name [version] +@deffn {Procedure} lookup-inferior-packages inferior name [version] 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}. -@end defun +@end deffn -@defun inferior-package? obj +@deffn {Procedure} inferior-package? obj Return true if @var{obj} is an inferior package. -@end defun +@end deffn -@defun inferior-package-name package -@defunx inferior-package-version package -@defunx inferior-package-synopsis package -@defunx inferior-package-description package -@defunx inferior-package-home-page package -@defunx inferior-package-location package -@defunx inferior-package-inputs package -@defunx inferior-package-native-inputs package -@defunx inferior-package-propagated-inputs package -@defunx inferior-package-transitive-propagated-inputs package -@defunx inferior-package-native-search-paths package -@defunx inferior-package-transitive-native-search-paths package -@defunx inferior-package-search-paths package +@deffn {Procedure} inferior-package-name package +@deffnx {Procedure} inferior-package-version package +@deffnx {Procedure} inferior-package-synopsis package +@deffnx {Procedure} inferior-package-description package +@deffnx {Procedure} inferior-package-home-page package +@deffnx {Procedure} inferior-package-location package +@deffnx {Procedure} inferior-package-inputs package +@deffnx {Procedure} inferior-package-native-inputs package +@deffnx {Procedure} inferior-package-propagated-inputs package +@deffnx {Procedure} inferior-package-transitive-propagated-inputs package +@deffnx {Procedure} inferior-package-native-search-paths package +@deffnx {Procedure} inferior-package-transitive-native-search-paths package +@deffnx {Procedure} inferior-package-search-paths 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. -@end defun +@end deffn Inferior packages can be used transparently like any other package or file-like object in G-expressions (@pxref{G-Expressions}). They are also @@ -7719,7 +7719,7 @@ Defining Packages The build actions it prescribes may then be realized by using the @code{build-derivations} procedure (@pxref{The Store}). -@defun package-derivation store package [system] +@deffn {Procedure} package-derivation store package [system] Return the @code{} object of @var{package} for @var{system} (@pxref{Derivations}). @@ -7728,21 +7728,21 @@ Defining Packages @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}). -@end defun +@end deffn @noindent @cindex cross-compilation Similarly, it is possible to compute a derivation that cross-builds a package for some other system: -@defun package-cross-derivation store package target [system] +@deffn {Procedure} package-cross-derivation store package target [system] Return the @code{} 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}). -@end defun +@end deffn Once you have package definitions, you can easily define @emph{variants} of those packages. @xref{Defining Package Variants}, for more on that. @@ -7971,10 +7971,10 @@ package Reference The following helper procedures are provided to help deal with package inputs. -@defun lookup-package-input package name -@defunx lookup-package-native-input package name -@defunx lookup-package-propagated-input package name -@defunx lookup-package-direct-input package name +@deffn {Procedure} lookup-package-input package name +@deffnx {Procedure} lookup-package-native-input package name +@deffnx {Procedure} lookup-package-propagated-input package name +@deffnx {Procedure} lookup-package-direct-input package name Look up @var{name} among @var{package}'s inputs (or native, propagated, or direct inputs). Return it if found, @code{#f} otherwise. @@ -7990,7 +7990,7 @@ package Reference In this example we obtain the @code{gmp} package that is among the direct inputs of @code{coreutils}. -@end defun +@end deffn @cindex development inputs, of a package @cindex implicit inputs, of a package @@ -7999,7 +7999,7 @@ package Reference package is compiled. This is what the @code{package-development-inputs} procedure returns. -@defun package-development-inputs package [system] [#:target #f] +@deffn {Procedure} package-development-inputs package [system] [#:target #f] 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 @@ -8030,7 +8030,7 @@ package Reference 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}). -@end defun +@end deffn Because packages are regular Scheme objects that capture a complete dependency graph and associated build procedures, it is often useful to @@ -8038,7 +8038,7 @@ package Reference thereof according to some parameters. Below are a few examples. @cindex tool chain, choosing a package's tool chain -@defun package-with-c-toolchain package toolchain +@deffn {Procedure} package-with-c-toolchain package toolchain 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 @@ -8059,7 +8059,7 @@ package Reference 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. -@end defun +@end deffn @node origin Reference @subsection @code{origin} Reference @@ -8176,7 +8176,7 @@ origin Reference download)} module provides the most common method, @code{url-fetch}, described below. -@defun url-fetch url hash-algo hash [name] [#:executable? #f] +@deffn {Procedure} url-fetch url hash-algo hash [name] [#:executable? #f] 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, @@ -8189,19 +8189,19 @@ origin Reference Alternatively, when URL starts with @code{file://}, return the corresponding file name in the store. -@end defun +@end deffn 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. -@defun git-fetch ref hash-algo hash +@deffn {Procedure} git-fetch ref hash-algo hash Return a fixed-output derivation that fetches @var{ref}, a @code{} 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}. -@end defun +@end deffn @deftp {Data Type} git-reference This data type represents a Git reference for @code{git-fetch} to @@ -8244,12 +8244,12 @@ origin Reference the @code{hg-fetch} origin method and @code{hg-reference} data type for support of the Mercurial version control system. -@defun hg-fetch ref hash-algo hash [name] +@deffn {Procedure} hg-fetch ref hash-algo hash [name] Return a fixed-output derivation that fetches @var{ref}, a @code{} 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}. -@end defun +@end deffn @node Defining Package Variants @section Defining Package Variants @@ -8403,7 +8403,7 @@ Defining Package Variants that directly maps to the more sophisticated package transformation options (@pxref{Package Transformation Options}): -@defun options->transformation opts +@deffn {Procedure} options->transformation opts 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: @@ -8415,7 +8415,7 @@ Defining Package Variants Each symbol names a transformation and the corresponding string is an argument to that transformation. -@end defun +@end deffn For instance, a manifest equivalent to this command: @@ -8454,7 +8454,7 @@ Defining Package Variants graph, is what the @code{package-input-rewriting} procedure in @code{(guix packages)} implements. -@defun package-input-rewriting replacements [rewrite-name] [#:deep? #t] +@deffn {Procedure} package-input-rewriting replacements [rewrite-name] [#:deep? #t] 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 @@ -8463,7 +8463,7 @@ Defining Package Variants Optionally, @var{rewrite-name} is a one-argument procedure that takes the name of a package and returns its new name after rewrite. -@end defun +@end deffn @noindent Consider this example: @@ -8488,7 +8488,7 @@ Defining Package Variants The following variant of @code{package-input-rewriting} can match packages to be replaced by name rather than by identity. -@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t] +@deffn {Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t] 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. @@ -8516,12 +8516,12 @@ Defining Package Variants @code{package-mapping}: it supports arbitrary changes to nodes in the graph. -@defun package-mapping proc [cut?] [#:deep? #f] +@deffn {Procedure} package-mapping proc [cut?] [#:deep? #f] 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. -@end defun +@end deffn @node Writing Manifests @section Writing Manifests @@ -8726,14 +8726,14 @@ Writing Manifests @end table @end deftp -@defun concatenate-manifests lst +@deffn {Procedure} concatenate-manifests lst Concatenate the manifests listed in @var{lst} and return the resulting manifest. -@end defun +@end deffn @c TODO: , manifest-lookup, manifest-remove, etc. -@defun package->manifest-entry package [output] [#:properties] +@deffn {Procedure} package->manifest-entry package [output] [#:properties] 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 @@ -8751,9 +8751,9 @@ Writing Manifests (manifest (list (package->manifest-entry git) (package->manifest-entry git "send-email"))) @end lisp -@end defun +@end deffn -@defun packages->manifest packages +@deffn {Procedure} packages->manifest packages 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 @@ -8767,10 +8767,10 @@ Writing Manifests (packages->manifest (list git `(,git "send-email"))) @end lisp -@end defun +@end deffn @anchor{package-development-manifest} -@defun package->development-manifest package [system] [#:target] +@deffn {Procedure} package->development-manifest package [system] [#:target] 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 @@ -8798,7 +8798,7 @@ Writing Manifests (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. -@end defun +@end deffn @c TODO: Move (gnu packages) interface to a section of its own. @@ -8806,7 +8806,7 @@ Writing Manifests to build manifests. In particular, it lets you look up packages by name---see below. -@defun specifications->manifest specs +@deffn {Procedure} specifications->manifest specs 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 @@ -8823,7 +8823,7 @@ Writing Manifests 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. -@end defun +@end deffn @c TODO: specifications->package, etc. @@ -10292,54 +10292,54 @@ Build Utilities This section documents procedures that deal with store file names. -@defun %store-directory +@deffn {Procedure} %store-directory Return the directory name of the store. -@end defun +@end deffn -@defun store-file-name? file +@deffn {Procedure} store-file-name? file Return true if @var{file} is in the store. -@end defun +@end deffn -@defun strip-store-file-name file +@deffn {Procedure} strip-store-file-name file 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. -@end defun +@end deffn -@defun package-name->name+version name +@deffn {Procedure} package-name->name+version name 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. -@end defun +@end deffn @subsection File Types The procedures below deal with files and file types. -@defun directory-exists? dir +@deffn {Procedure} directory-exists? dir Return @code{#t} if @var{dir} exists and is a directory. -@end defun +@end deffn -@defun executable-file? file +@deffn {Procedure} executable-file? file Return @code{#t} if @var{file} exists and is executable. -@end defun +@end deffn -@defun symbolic-link? file +@deffn {Procedure} symbolic-link? file Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink''). -@end defun +@end deffn -@defun elf-file? file -@defunx ar-file? file -@defunx gzip-file? file +@deffn {Procedure} elf-file? file +@deffnx {Procedure} ar-file? file +@deffnx {Procedure} gzip-file? file 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. -@end defun +@end deffn -@defun reset-gzip-timestamp file [#:keep-mtime? #t] +@deffn {Procedure} reset-gzip-timestamp file [#:keep-mtime? #t] 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. -@end defun +@end deffn @subsection File Manipulation @@ -10360,20 +10360,20 @@ Build Utilities exception. @end defmac -@defun mkdir-p dir +@deffn {Procedure} mkdir-p dir Create directory @var{dir} and all its ancestors. -@end defun +@end deffn -@defun install-file file directory +@deffn {Procedure} install-file file directory Create @var{directory} if it does not exist and copy @var{file} in there under the same name. -@end defun +@end deffn -@defun make-file-writable file +@deffn {Procedure} make-file-writable file Make @var{file} writable for its owner. -@end defun +@end deffn -@defun copy-recursively source destination @ +@deffn {Procedure} copy-recursively source destination @ [#:log (current-output-port)] [#:follow-symlinks? #f] @ [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t] Copy @var{source} directory to @var{destination}. Follow symlinks if @@ -10382,13 +10382,13 @@ Build Utilities keep the modification time of the files in @var{source} on those of @var{destination}. When @var{keep-permissions?} is true, preserve file permissions. Write verbose output to the @var{log} port. -@end defun +@end deffn -@defun delete-file-recursively dir [#:follow-mounts? #f] +@deffn {Procedure} delete-file-recursively dir [#:follow-mounts? #f] Delete @var{dir} recursively, like @command{rm -rf}, without following symlinks. Don't follow mount points either, unless @var{follow-mounts?} is true. Report but ignore errors. -@end defun +@end deffn @defmac substitute* file @ ((regexp match-var@dots{}) body@dots{}) @dots{} @@ -10426,12 +10426,12 @@ Build Utilities @cindex file, searching This section documents procedures to search and filter files. -@defun file-name-predicate regexp +@deffn {Procedure} file-name-predicate regexp Return a predicate that returns true when passed a file name whose base name matches @var{regexp}. -@end defun +@end deffn -@defun find-files dir [pred] @ +@deffn {Procedure} find-files dir [pred] @ [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f] Return the lexicographically sorted list of files under @var{dir} for which @var{pred} returns true. @var{pred} is passed two arguments: the @@ -10442,7 +10442,7 @@ Build Utilities that symlinks are not followed. If @var{directories?} is true, then directories will also be included. If @var{fail-on-error?} is true, raise an exception upon error. -@end defun +@end deffn Here are a few examples where we assume that the current directory is the root of the Guix source tree: @@ -10461,13 +10461,13 @@ Build Utilities @result{} ("./libformat.a" "./libstore.a" @dots{}) @end lisp -@defun which program +@deffn {Procedure} which program Return the complete file name for @var{program} as found in @code{$PATH}, or @code{#f} if @var{program} could not be found. -@end defun +@end deffn -@defun search-input-file inputs name -@defunx search-input-directory inputs name +@deffn {Procedure} search-input-file inputs name +@deffnx {Procedure} search-input-directory inputs name Return the complete file name for @var{name} as found in @var{inputs}; @code{search-input-file} searches for a regular file and @code{search-input-directory} searches for a directory. If @var{name} @@ -10476,7 +10476,7 @@ Build Utilities Here, @var{inputs} must be an association list like @code{inputs} and @code{native-inputs} as available to build phases (@pxref{Build Phases}). -@end defun +@end deffn Here is a (simplified) example of how @code{search-input-file} is used in a build phase of the @code{wireguard-tools} package: @@ -10499,7 +10499,7 @@ Build Utilities essentially convenient wrappers around Guile's @code{system*} (@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}). -@defun invoke program args@dots{} +@deffn {Procedure} invoke program args@dots{} Invoke @var{program} with the given @var{args}. Raise an @code{&invoke-error} exception if the exit code is non-zero; otherwise return @code{#t}. @@ -10507,21 +10507,21 @@ Build Utilities The advantage compared to @code{system*} is that you do not need to check the return value. This reduces boilerplate in shell-script-like snippets for instance in package build phases. -@end defun +@end deffn -@defun invoke-error? c +@deffn {Procedure} invoke-error? c Return true if @var{c} is an @code{&invoke-error} condition. -@end defun +@end deffn -@defun invoke-error-program c -@defunx invoke-error-arguments c -@defunx invoke-error-exit-status c -@defunx invoke-error-term-signal c -@defunx invoke-error-stop-signal c +@deffn {Procedure} invoke-error-program c +@deffnx {Procedure} invoke-error-arguments c +@deffnx {Procedure} invoke-error-exit-status c +@deffnx {Procedure} invoke-error-term-signal c +@deffnx {Procedure} invoke-error-stop-signal c Access specific fields of @var{c}, an @code{&invoke-error} condition. -@end defun +@end deffn -@defun report-invoke-error c [port] +@deffn {Procedure} report-invoke-error c [port] Report to @var{port} (by default the current error port) about @var{c}, an @code{&invoke-error} condition, in a human-friendly way. @@ -10537,9 +10537,9 @@ Build Utilities @print{} command "date" "--imaginary-option" failed with status 1 @end lisp -@end defun +@end deffn -@defun invoke/quiet program args@dots{} +@deffn {Procedure} invoke/quiet program args@dots{} Invoke @var{program} with @var{args} and capture @var{program}'s standard output and standard error. If @var{program} succeeds, print nothing and return the unspecified value; otherwise, raise a @@ -10563,7 +10563,7 @@ Build Utilities date: unrecognized option '--imaginary-option' Try 'date --help' for more information. @end lisp -@end defun +@end deffn @subsection Build Phases @@ -10673,7 +10673,7 @@ Build Utilities To ease that task, the @code{(guix build utils)} module provides a couple of helpers to wrap commands. -@defun wrap-program program [#:sh sh] [#:rest variables] +@deffn {Procedure} wrap-program program [#:sh sh] [#:rest variables] Make a wrapper for @var{program}. @var{variables} should look like this: @lisp @@ -10705,9 +10705,9 @@ Build Utilities If @var{program} has previously been wrapped by @code{wrap-program}, the wrapper is extended with definitions for @var{variables}. If it is not, @var{sh} will be used as the interpreter. -@end defun +@end deffn -@defun wrap-script program [#:guile guile] [#:rest variables] +@deffn {Procedure} wrap-script program [#:guile guile] [#:rest variables] Wrap the script @var{program} such that @var{variables} are set first. The format of @var{variables} is the same as in the @code{wrap-program} procedure. This procedure differs from @code{wrap-program} in that it @@ -10720,7 +10720,7 @@ Build Utilities Note that this procedure can only be used once per file as Guile scripts are not supported. -@end defun +@end deffn @node Search Paths @section Search Paths @@ -10909,12 +10909,12 @@ Search Paths directories on the other hand in a set of environment variable definitions? That's the job of @code{evaluate-search-paths}. -@defun evaluate-search-paths search-paths directories [getenv] +@deffn {Procedure} evaluate-search-paths search-paths directories [getenv] Evaluate @var{search-paths}, a list of search-path specifications, for @var{directories}, a list of directory names, and return a list of specification/value pairs. Use @var{getenv} to determine the current settings and report only settings not already effective. -@end defun +@end deffn The @code{(guix profiles)} provides a higher-level helper procedure, @code{load-profile}, that sets the environment variables of a profile. @@ -11018,7 +11018,7 @@ The Store @end quotation @end defvr -@defun open-connection [uri] [#:reserve-space? #t] +@deffn {Procedure} open-connection [uri] [#:reserve-space? #t] Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When @var{reserve-space?} is true, instruct it to reserve a little bit of extra space on the file system so that the garbage collector can still @@ -11026,11 +11026,11 @@ The Store @var{file} defaults to @code{%default-socket-path}, which is the normal location given the options that were passed to @command{configure}. -@end defun +@end deffn -@defun close-connection server +@deffn {Procedure} close-connection server Close the connection to @var{server}. -@end defun +@end deffn @defvar current-build-output-port This variable is bound to a SRFI-39 parameter, which refers to the port @@ -11041,7 +11041,7 @@ The Store argument. @cindex invalid store items -@defun valid-path? server path +@deffn {Procedure} valid-path? server path Return @code{#t} when @var{path} designates a valid store item and @code{#f} otherwise (an invalid item may exist on disk but still be invalid, for instance because it is the result of an aborted or failed @@ -11049,19 +11049,19 @@ The Store A @code{&store-protocol-error} condition is raised if @var{path} is not prefixed by the store directory (@file{/gnu/store}). -@end defun +@end deffn -@defun add-text-to-store server name text [references] +@deffn {Procedure} add-text-to-store server name text [references] Add @var{text} under file @var{name} in the store, and return its store path. @var{references} is the list of store paths referred to by the resulting store path. -@end defun +@end deffn -@defun build-derivations store derivations [mode] +@deffn {Procedure} build-derivations store derivations [mode] Build @var{derivations}, a list of @code{} objects, @file{.drv} file names, or derivation/output pairs, using the specified @var{mode}---@code{(build-mode normal)} by default. -@end defun +@end deffn Note that the @code{(guix monads)} module provides a monad as well as monadic versions of the above procedures, with the goal of making it @@ -11135,7 +11135,7 @@ Derivations otherwise manipulate derivations. The lowest-level primitive to create a derivation is the @code{derivation} procedure: -@defun derivation store name builder args @ +@deffn {Procedure} derivation store name builder args @ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @ [#:system (%current-system)] [#:references-graphs #f] @ @@ -11181,7 +11181,7 @@ Derivations @var{properties} must be an association list describing ``properties'' of the derivation. It is kept as-is, uninterpreted, in the derivation. -@end defun +@end deffn @noindent Here's an example with a shell script as its builder, assuming @@ -11214,7 +11214,7 @@ Derivations @code{build-expression->derivation}, documented below. This procedure is now deprecated in favor of the much nicer @code{gexp->derivation}. -@defun build-expression->derivation store name exp @ +@deffn {Procedure} build-expression->derivation store name exp @ [#:system (%current-system)] [#:inputs '()] @ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ @@ -11246,7 +11246,7 @@ Derivations @var{references-graphs}, @var{allowed-references}, @var{disallowed-references}, @var{local-build?}, and @var{substitutable?}. -@end defun +@end deffn @noindent Here's an example of a single-output derivation that creates a directory @@ -11499,10 +11499,10 @@ The Store Monad The state is assumed to be a list. @end deffn -@defun run-with-state mval [state] +@deffn {Procedure} run-with-state mval [state] Run monadic value @var{mval} starting with @var{state} as the initial state. Return two values: the resulting value, and the resulting state. -@end defun +@end deffn The main interface to the store monad, provided by the @code{(guix store)} module, is as follows. @@ -11515,11 +11515,11 @@ The Store Monad passing it to the @code{run-with-store} procedure (see below). @end defvar -@defun run-with-store store mval @ +@deffn {Procedure} run-with-store store mval @ [#:guile-for-build] [#:system (%current-system)] Run @var{mval}, a monadic value in the store monad, in @var{store}, an open store connection. -@end defun +@end deffn @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}] Return as a monadic value the absolute file name in the store of the file @@ -11863,9 +11863,9 @@ G-Expressions @var{body}@dots{}. @end defmac -@defun gexp? obj +@deffn {Procedure} gexp? obj Return @code{#t} if @var{obj} is a G-expression. -@end defun +@end deffn G-expressions are meant to be written to disk, either as code building some derivation, or as plain files in the store. The monadic procedures @@ -11952,7 +11952,7 @@ G-Expressions @code{plain-file} can be used similarly; it differs in that the file content is directly passed as a string. -@defun local-file file [name] [#:recursive? #f] [#:select? (const #t)] +@deffn {Procedure} local-file file [name] [#:recursive? #f] [#:select? (const #t)] Return an object representing local file @var{file} to add to the store; this object can be used in a gexp. If @var{file} is a literal string denoting a relative file name, it is looked up relative to the source @@ -11972,23 +11972,23 @@ G-Expressions This is the declarative counterpart of the @code{interned-file} monadic procedure (@pxref{The Store Monad, @code{interned-file}}). -@end defun +@end deffn -@defun plain-file name content +@deffn {Procedure} plain-file name content Return an object representing a text file called @var{name} with the given @var{content} (a string or a bytevector) to be added to the store. This is the declarative counterpart of @code{text-file}. -@end defun +@end deffn -@defun computed-file name gexp [#:local-build? #t] [#:options '()] +@deffn {Procedure} computed-file name gexp [#:local-build? #t] [#:options '()] Return an object representing the store item @var{name}, a file or directory computed by @var{gexp}. When @var{local-build?} is true (the default), the derivation is built locally. @var{options} is a list of additional arguments to pass to @code{gexp->derivation}. This is the declarative counterpart of @code{gexp->derivation}. -@end defun +@end deffn @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @ [#:guile (default-guile)] [#:module-path %load-path] @ @@ -12019,13 +12019,13 @@ G-Expressions @end example @end deffn -@defun program-file name exp [#:guile #f] [#:module-path %load-path] +@deffn {Procedure} program-file name exp [#:guile #f] [#:module-path %load-path] Return an object representing the executable store item @var{name} that runs @var{gexp}. @var{guile} is the Guile package used to execute that script. Imported modules of @var{gexp} are looked up in @var{module-path}. This is the declarative counterpart of @code{gexp->script}. -@end defun +@end deffn @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @ [#:set-load-path? #t] [#:module-path %load-path] @ @@ -12044,12 +12044,12 @@ G-Expressions or a subset thereof. @end deffn -@defun scheme-file name exp [#:splice? #f] [#:set-load-path? #t] +@deffn {Procedure} scheme-file name exp [#:splice? #f] [#:set-load-path? #t] Return an object representing the Scheme file @var{name} that contains @var{exp}. This is the declarative counterpart of @code{gexp->file}. -@end defun +@end deffn @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{} Return as a monadic value a derivation that builds a text file @@ -12077,7 +12077,7 @@ G-Expressions preventing them from being garbage-collected during its lifetime. @end deffn -@defun mixed-text-file name text @dots{} +@deffn {Procedure} mixed-text-file name text @dots{} Return an object representing store file @var{name} containing @var{text}. @var{text} is a sequence of strings and file-like objects, as in: @@ -12088,9 +12088,9 @@ G-Expressions @end lisp This is the declarative counterpart of @code{text-file*}. -@end defun +@end deffn -@defun file-union name files +@deffn {Procedure} file-union name files Return a @code{} that builds a directory containing all of @var{files}. Each item in @var{files} must be a two-element list where the first element is the file name to use in the new directory, and the second element is a gexp @@ -12105,9 +12105,9 @@ G-Expressions @end lisp This yields an @code{etc} directory containing these two files. -@end defun +@end deffn -@defun directory-union name things +@deffn {Procedure} directory-union name things Return a directory that is the union of @var{things}, where @var{things} is a list of file-like objects denoting directories. For example: @@ -12116,9 +12116,9 @@ G-Expressions @end lisp yields a directory that is the union of the @code{guile} and @code{emacs} packages. -@end defun +@end deffn -@defun file-append obj suffix @dots{} +@deffn {Procedure} file-append obj suffix @dots{} Return a file-like object that expands to the concatenation of @var{obj} and @var{suffix}, where @var{obj} is a lowerable object and each @var{suffix} is a string. @@ -12143,7 +12143,7 @@ G-Expressions resulting script contains the absolute file name as a string, whereas in the second case, the resulting script contains a @code{(string-append @dots{})} expression to construct the file name @emph{at run time}. -@end defun +@end deffn @defmac let-system system body@dots{} @defmacx let-system (system target) body@dots{} @@ -12210,7 +12210,7 @@ G-Expressions has an associated gexp compiler, such as a @code{}. @end deffn -@defun gexp->approximate-sexp gexp +@deffn {Procedure} gexp->approximate-sexp gexp Sometimes, it may be useful to convert a G-exp into a S-exp. For example, some linters (@pxref{Invoking guix lint}) peek into the build phases of a package to detect potential problems. This conversion can @@ -12218,7 +12218,7 @@ G-Expressions in the process. More specifically, lowerable objects will be silently replaced with some arbitrary object -- currently the list @code{(*approximate*)}, but this may change. -@end defun +@end deffn @node Invoking guix repl @section Invoking @command{guix repl} @@ -17140,7 +17140,7 @@ File Systems @end table @end deftp -@defun file-system-label str +@deffn {Procedure} file-system-label str This procedure returns an opaque file system label from @var{str}, a string: @@ -17151,7 +17151,7 @@ File Systems File system labels are used to refer to file systems by label rather than by device name. See above for examples. -@end defun +@end deffn The @code{(gnu system file-systems)} exports the following useful variables. @@ -17202,7 +17202,7 @@ File Systems The @code{(gnu system uuid)} module provides tools to deal with file system ``unique identifiers'' (UUIDs). -@defun uuid str [type] +@deffn {Procedure} uuid str [type] Return an opaque UUID (unique identifier) object of the given @var{type} (a symbol) by parsing @var{str} (a string): @@ -17219,7 +17219,7 @@ File Systems UUIDs are another way to unambiguously refer to file systems in operating system configuration. See the examples above. -@end defun +@end deffn @menu @@ -17887,13 +17887,13 @@ Keyboard Layout list of additional options. In most cases the layout name is all you care about. -@defun keyboard-layout name [variant] [#:model] [#:options '()] +@deffn {Procedure} keyboard-layout name [variant] [#:model] [#:options '()] Return a new keyboard layout with the given @var{name} and @var{variant}. @var{name} must be a string such as @code{"fr"}; @var{variant} must be a string such as @code{"bepo"} or @code{"nodeadkeys"}. See the @code{xkeyboard-config} package for valid options. -@end defun +@end deffn Here are a few examples: @@ -18285,7 +18285,7 @@ Base Services (see below). @end defvar -@defun extra-special-file file target +@deffn {Procedure} extra-special-file file target Use @var{target} as the ``special file'' @var{file}. For example, adding the following lines to the @code{services} field of @@ -18296,7 +18296,7 @@ Base Services (extra-special-file "/usr/bin/env" (file-append coreutils "/bin/env")) @end lisp -@end defun +@end deffn @defvar host-name-service-type Type of the service that sets the system host name, whose value @@ -18370,14 +18370,14 @@ Base Services @end defvar -@defun host @var{address} @var{canonical-name} [@var{aliases}] +@deffn {Procedure} host @var{address} @var{canonical-name} [@var{aliases}] Return a new record for the host at @var{address} with the given @var{canonical-name} and possibly @var{aliases}. @var{address} must be a string denoting a valid IPv4 or IPv6 address, and @var{canonical-name} and the strings listed in @var{aliases} must be valid host names. -@end defun +@end deffn @defvar login-service-type Type of the service that provides a console login service, whose value @@ -18989,7 +18989,7 @@ Base Services @end table @end deftp -@defun udev-rule @var{file-name} @var{contents} +@deffn {Procedure} udev-rule @var{file-name} @var{contents} Return a udev-rule file named @var{file-name} containing the rules defined by the @var{contents} literal. @@ -19005,9 +19005,9 @@ Base Services "ATTR@{product@}==\"Example\", " "RUN+=\"/path/to/script\""))) @end lisp -@end defun +@end deffn -@defun udev-rules-service @var{name} @var{rules} [#:groups '()] +@deffn {Procedure} udev-rules-service @var{name} @var{rules} [#:groups '()] Return a service that extends @code{udev-service-type} with @var{rules} and @code{account-service-type} with @var{groups} as system groups. This works by creating a singleton service type @@ -19024,9 +19024,9 @@ Base Services (cons (udev-rules-service 'usb-thing %example-udev-rule) %desktop-services))) @end lisp -@end defun +@end deffn -@defun file->udev-rule @var{file-name} @var{file} +@deffn {Procedure} file->udev-rule @var{file-name} @var{file} Return a udev-rule file named @var{file-name} containing the rules defined within @var{file}, a file-like object. @@ -19048,7 +19048,7 @@ Base Services (sha256 (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) @end lisp -@end defun +@end deffn Additionally, Guix package definitions can be included in @var{rules} in order to extend the udev rules with the definitions found under their @@ -22510,22 +22510,22 @@ X Window @end table @end deftp -@defun set-xorg-configuration config [login-manager-service-type] +@deffn {Procedure} set-xorg-configuration config [login-manager-service-type] Tell the log-in manager (of type @var{login-manager-service-type}) to use @var{config}, an @code{} record. Since the Xorg configuration is embedded in the log-in manager's configuration---e.g., @code{gdm-configuration}---this procedure provides a shorthand to set the Xorg configuration. -@end defun +@end deffn -@defun xorg-start-command [config] +@deffn {Procedure} xorg-start-command [config] Return a @code{startx} script in which the modules, fonts, etc. specified in @var{config}, are available. The result should be used in place of @code{startx}. Usually the X server is started by a login manager. -@end defun +@end deffn @defvar screen-locker-service-type @@ -23933,7 +23933,7 @@ Desktop Services @end lisp @end defvar -@defun geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] +@deffn {Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] Return a configuration allowing an application to access GeoClue location data. @var{name} is the Desktop ID of the application, without the @code{.desktop} part. If @var{allowed?} is true, the application @@ -23942,7 +23942,7 @@ Desktop Services or not. Finally @var{users} is a list of UIDs of all users for which this application is allowed location info access. An empty users list means that all users are allowed. -@end defun +@end deffn @defvar %standard-geoclue-applications The standard list of well-known GeoClue application configurations, @@ -27904,7 +27904,7 @@ File-Sharing Services procedures provided by this module can be used to obtain a suitable hash value. -@defun transmission-password-hash password salt +@deffn {Procedure} transmission-password-hash password salt Returns a string containing the result of hashing @var{password} together with @var{salt}, in the format recognized by Transmission clients for their @code{rpc-password} configuration setting. @@ -27912,13 +27912,13 @@ File-Sharing Services @var{salt} must be an eight-character string. The @code{transmission-random-salt} procedure can be used to generate a suitable salt value at random. -@end defun +@end deffn -@defun transmission-random-salt +@deffn {Procedure} transmission-random-salt Returns a string containing a random, eight-character salt value of the type generated and used by Transmission clients, suitable for passing to the @code{transmission-password-hash} procedure. -@end defun +@end deffn These procedures are accessible from within a Guile REPL started with the @command{guix repl} command (@pxref{Invoking guix repl}). This is @@ -31057,11 +31057,11 @@ Web Services @end deftp -@defun nginx-php-location [#:nginx-package nginx] @ +@deffn {Procedure} nginx-php-location [#:nginx-package nginx] @ [socket (string-append "/var/run/php" @ (version-major (package-version php)) "-fpm.sock")] A helper function to quickly add php to an @code{nginx-server-configuration}. -@end defun +@end deffn A simple services setup for nginx with php can look like this: @lisp @@ -31084,7 +31084,7 @@ Web Services in @code{Nginx}. It is used to generate cat avatar from a seed, for instance the hash of a user's email address. -@defun cat-avatar-generator-service @ +@deffn {Procedure} cat-avatar-generator-service @ [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package cat-avatar-generator] @ [#:configuration (nginx-server-configuration)] @@ -31092,7 +31092,7 @@ Web Services extends the nginx configuration to add a server block that serves @code{package}, a version of cat-avatar-generator. During execution, cat-avatar-generator will be able to use @code{cache-dir} as its cache directory. -@end defun +@end deffn A simple setup for cat-avatar-generator can look like this: @lisp @@ -33117,7 +33117,7 @@ Continuous Integration The @code{(gnu services cuirass)} module provides the following service. -@defvr {Scheme Procedure} cuirass-service-type +@defvr {Procedure} cuirass-service-type The type of the Cuirass service. Its value must be a @code{cuirass-configuration} object, as described below. @end defvr @@ -33344,7 +33344,7 @@ Continuous Integration Laminar encourages the use of existing tools such as bash and cron instead of reinventing them. -@defvr {Scheme Procedure} laminar-service-type +@defvar laminar-service-type The type of the Laminar service. Its value must be a @code{laminar-configuration} object, as described below. @@ -33355,7 +33355,7 @@ Continuous Integration @lisp (service laminar-service-type) @end lisp -@end defvr +@end defvar @deftp {Data Type} laminar-configuration Data type representing the configuration of Laminar. @@ -35105,20 +35105,20 @@ Virtualization Services @end table @end deftp -@defun lookup-qemu-platforms platforms@dots{} +@deffn {Procedure} lookup-qemu-platforms platforms@dots{} Return the list of QEMU platform objects corresponding to @var{platforms}@dots{}. @var{platforms} must be a list of strings corresponding to platform names, such as @code{"arm"}, @code{"sparc"}, @code{"mips64el"}, and so on. -@end defun +@end deffn -@defun qemu-platform? obj +@deffn {Procedure} qemu-platform? obj Return true if @var{obj} is a platform object. -@end defun +@end deffn -@defun qemu-platform-name platform +@deffn {Procedure} qemu-platform-name platform Return the name of @var{platform}---a string such as @code{"arm"}. -@end defun +@end deffn @subsubheading QEMU Guest Agent @@ -35614,27 +35614,27 @@ Virtualization Services @end table @end deftp -@defun debootstrap-variant name configuration +@deffn {Procedure} debootstrap-variant name configuration This is a helper procedure that creates a @code{ganeti-os-variant} record. It takes two parameters: a name and a @code{debootstrap-configuration} object. -@end defun +@end deffn -@defun debootstrap-os variants@dots{} +@deffn {Procedure} debootstrap-os variants@dots{} This is a helper procedure that creates a @code{ganeti-os} record. It takes a list of variants created with @code{debootstrap-variant}. -@end defun +@end deffn -@defun guix-variant name configuration +@deffn {Procedure} guix-variant name configuration This is a helper procedure that creates a @code{ganeti-os-variant} record for use with the Guix OS provider. It takes a name and a G-expression that returns a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a Guix System configuration. -@end defun +@end deffn -@defun guix-os variants@dots{} +@deffn {Procedure} guix-os variants@dots{} This is a helper procedure that creates a @code{ganeti-os} record. It takes a list of variants produced by @code{guix-variant}. -@end defun +@end deffn @defvar %default-debootstrap-variants This is a convenience variable to make the debootstrap provider work @@ -36132,7 +36132,7 @@ Version Control Services @code{git-http-configuration} and then add that location to a web server. -@defun git-http-nginx-location-configuration @ +@deffn {Procedure} git-http-nginx-location-configuration @ [config=(git-http-configuration)] Compute an @code{nginx-location-configuration} that corresponds to the given Git http configuration. An example nginx service definition to @@ -36161,7 +36161,7 @@ Version Control Services service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your system services. @xref{Web Services}. -@end defun +@end deffn @subsubheading Cgit Service @@ -38842,7 +38842,7 @@ Miscellaneous Services @end lisp @end defvar -@defun fail2ban-jail-service svc-type jail +@deffn {Procedure} fail2ban-jail-service svc-type jail Extend @var{svc-type}, a @code{} object with @var{jail}, a @code{fail2ban-jail-configuration} object. @@ -38862,7 +38862,7 @@ Miscellaneous Services (enabled? #t))) (openssh-configuration ...)))) @end lisp -@end defun +@end deffn Below is the reference for the different @code{jail-service-type} configuration records. @@ -39470,7 +39470,7 @@ Initial RAM Disk @cindex initrd @cindex initial RAM disk -@defun raw-initrd file-systems @ +@deffn {Procedure} raw-initrd file-systems @ [#:linux-modules '()] [#:pre-mount #t] [#:mapped-devices '()] @ [#:keyboard-layout #f] [#:helper-packages '()] @ [#:qemu-networking? #f] [#:volatile-root? #f] @@ -39499,9 +39499,9 @@ Initial RAM Disk When @var{volatile-root?} is true, the root file system is writable but any changes to it are lost. -@end defun +@end deffn -@defun base-initrd file-systems @ +@deffn {Procedure} base-initrd file-systems @ [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f] [#:volatile-root? #f] @ [#:linux-modules '()] @@ -39523,7 +39523,7 @@ Initial RAM Disk for @var{file-systems} and for the given options. Additional kernel modules can be listed in @var{linux-modules}. They will be added to the initrd, and loaded at boot time in the order in which they appear. -@end defun +@end deffn Needless to say, the initrds we produce and use embed a statically-linked Guile, and the initialization program is a Guile @@ -39531,13 +39531,13 @@ Initial RAM Disk @code{expression->initrd} procedure builds such an initrd, given the program to run in that initrd. -@defun expression->initrd exp @ +@deffn {Procedure} expression->initrd exp @ [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a file-like object a Linux initrd (a gzipped cpio archive) containing @var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All the derivations referenced by @var{exp} are automatically copied to the initrd. -@end defun +@end deffn @node Bootloader Configuration @section Bootloader Configuration @@ -39883,14 +39883,14 @@ Bootloader Configuration @end table @end deftp -@defun grub-theme +@deffn {Procedure} grub-theme Return the default GRUB theme used by the operating system if no @code{theme} field is specified in @code{bootloader-configuration} record. It comes with a fancy background image displaying the GNU and Guix logos. -@end defun +@end deffn For example, to override the default resolution, you may use something like @@ -41142,7 +41142,7 @@ Service Reference services and service types. This interface is provided by the @code{(gnu services)} module. -@defun service type [value] +@deffn {Procedure} service type [value] Return a new service of @var{type}, a @code{} object (see below). @var{value} can be any object; it represents the parameters of this particular service instance. @@ -41167,20 +41167,20 @@ Service Reference In both cases the result is an instance of @code{openssh-service-type} with the default configuration. -@end defun +@end deffn -@defun service? obj +@deffn {Procedure} service? obj Return true if @var{obj} is a service. -@end defun +@end deffn -@defun service-kind service +@deffn {Procedure} service-kind service Return the type of @var{service}---i.e., a @code{} object. -@end defun +@end deffn -@defun service-value service +@deffn {Procedure} service-value service Return the value associated with @var{service}. It represents its parameters. -@end defun +@end deffn Here is an example of how a service is created and manipulated: @@ -41301,23 +41301,23 @@ Service Reference @xref{Service Types and Services}, for examples. @end deftp -@defun service-extension target-type compute +@deffn {Procedure} service-extension target-type compute Return a new extension for services of type @var{target-type}. @var{compute} must be a one-argument procedure: @code{fold-services} calls it, passing it the value associated with the service that provides the extension; it must return a valid value for the target service. -@end defun +@end deffn -@defun service-extension? obj +@deffn {Procedure} service-extension? obj Return true if @var{obj} is a service extension. -@end defun +@end deffn Occasionally, you might want to simply extend an existing service. This involves creating a new service type and specifying the extension of interest, which can be verbose; the @code{simple-service} procedure provides a shorthand for this. -@defun simple-service name target value +@deffn {Procedure} simple-service name target value Return a service that extends @var{target} with @var{value}. This works by creating a singleton service type @var{name}, of which the returned service is an instance. @@ -41329,7 +41329,7 @@ Service Reference (simple-service 'my-mcron-job mcron-service-type #~(job '(next-hour (3)) "guix gc -F 2G")) @end lisp -@end defun +@end deffn At the core of the service abstraction lies the @code{fold-services} procedure, which is responsible for ``compiling'' a list of services @@ -41339,10 +41339,10 @@ Service Reference service extensions down the service graph, updating each node parameters on the way, until it reaches the root node. -@defun fold-services services [#:target-type system-service-type] +@deffn {Procedure} fold-services services [#:target-type system-service-type] Fold @var{services} by propagating their extensions down to the root of type @var{target-type}; return the root service adjusted accordingly. -@end defun +@end deffn Lastly, the @code{(gnu services)} module also defines several essential service types, some of which are listed below. @@ -41625,7 +41625,7 @@ Shepherd Services @end deftp @cindex configuration file, of Shepherd services -@defun shepherd-configuration-action +@deffn {Procedure} shepherd-configuration-action Return a @code{configuration} action to display @var{file}, which should be the name of the service's configuration file. @@ -41655,7 +41655,7 @@ Shepherd Services @end example This can come in as a handy debugging tool! -@end defun +@end deffn @defvar shepherd-root-service-type The service type for the Shepherd ``root service''---i.e., PID@tie{}1. @@ -41910,28 +41910,28 @@ Complex Configurations @end lisp @end defmac -@defun maybe-value-set? value +@deffn {Procedure} maybe-value-set? value Predicate to check whether a user explicitly specified the value of a maybe field. -@end defun +@end deffn -@defun serialize-configuration configuration fields +@deffn {Procedure} serialize-configuration configuration fields Return a G-expression that contains the values corresponding to the @var{fields} of @var{configuration}, a record that has been generated by @code{define-configuration}. The G-expression can then be serialized to disk by using something like @code{mixed-text-file}. -@end defun +@end deffn -@defun empty-serializer field-name value +@deffn {Procedure} empty-serializer field-name value A serializer that just returns an empty string. The @code{serialize-package} procedure is an alias for this. -@end defun +@end deffn Once you have defined a configuration record, you will most likely also want to document it so that other people know to use it. To help with that, there are two procedures, both of which are documented below. -@defun generate-documentation documentation documentation-name +@deffn {Procedure} generate-documentation documentation documentation-name Generate a Texinfo fragment from the docstrings in @var{documentation}, a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}. @var{label} should be a symbol and should be the name of the @@ -41961,15 +41961,15 @@ Complex Configurations @var{documentation-name} should be a symbol and should be the name of the configuration record. -@end defun +@end deffn -@defun configuration->documentation configuration-symbol +@deffn {Procedure} configuration->documentation configuration-symbol Take @var{configuration-symbol}, the symbol corresponding to the name used when defining a configuration record with @code{define-configuration}, and print the Texinfo documentation of its fields. This is useful if there aren’t any nested configuration records since it only prints the documentation for the top-level fields. -@end defun +@end deffn As of right now, there is no automated way to generate documentation for configuration records and put them in the manual. Instead, every