aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/contributing.texi11
-rw-r--r--doc/guix-cookbook.texi12
-rw-r--r--doc/guix.texi201
3 files changed, 216 insertions, 8 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9e9b89782c..7337f4bd58 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -76,15 +76,17 @@ all the dependencies and appropriate environment variables are set up to
hack on Guix:
@example
-guix shell -D guix --pure
+guix shell -D guix -CPW
@end example
or even, from within a Git worktree for Guix:
@example
-guix shell --pure
+guix shell -CPW
@end example
+If @option{-C} (short for @option{--container}) is not supported on your
+system, try @command{--pure} instead of @option{-CPW}.
@xref{Invoking guix shell}, for more information on that command.
If you are unable to use Guix when building Guix from a checkout, the
@@ -1682,6 +1684,11 @@ command to submit patches. To list the available actions of the script,
you can invoke it via the @command{etc/teams.scm help} command. For
more information regarding teams, @pxref{Teams}.
+@quotation Note
+On foreign distros, you might have to use @command{./pre-inst-env git
+send-email} for @file{etc/teams.scm} to work.
+@end quotation
+
@unnumberedsubsubsec Multiple Patches
@anchor{Multiple Patches}
@cindex cover letter
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 3d86fca396..cdca411706 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -78,7 +78,7 @@ manual}).
* System Configuration:: Customizing the GNU System
* Containers:: Isolated environments and nested systems
* Advanced package management:: Power to the users!
-* Software Development:: Environments, continuous integration, etc.
+* Software Development:: Environments, continuous integration, etc.
* Environment management:: Control environment
* Installing Guix on a Cluster:: High-performance computing.
@@ -167,6 +167,16 @@ Guix Profiles in Practice
* The benefits of manifests::
* Reproducible profiles::
+Software Development
+
+* Getting Started:: Step 0: using `guix shell'.
+* Building with Guix:: Step 1: building your code.
+* The Repository as a Channel:: Step 2: turning the repo in a channel.
+* Package Variants:: Bonus: Defining variants.
+* Setting Up Continuous Integration:: Step 3: continuous integration.
+* Build Manifest:: Bonus: Manifest.
+* Wrapping Up:: Recap.
+
Environment management
* Guix environment via direnv:: Setup Guix environment with direnv
diff --git a/doc/guix.texi b/doc/guix.texi
index ec26a2295c..50d66e9557 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -119,6 +119,9 @@ Copyright @copyright{} 2023 Tanguy Le Carrour@*
Copyright @copyright{} 2023 Zheng Junjie@*
Copyright @copyright{} 2023 Brian Cully@*
Copyright @copyright{} 2023 Felix Lechner@*
+Copyright @copyright{} 2023 Foundation Devices, Inc.@*
+Copyright @copyright{} 2023 Thomas Ieong@*
+Copyright @copyright{} 2023 Saku Laesvuori@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -4058,6 +4061,7 @@ guix-daemon}). It can also be disabled temporarily by passing the
@node Getting Substitutes from Other Servers
@subsection Getting Substitutes from Other Servers
+@c Note: This section name appears in a hint printed by 'guix weather'.
@cindex substitute servers, adding more
Guix can look up and fetch substitutes from several servers. This is
@@ -4157,6 +4161,21 @@ can list as many substitute servers as you like, with the caveat that
substitute lookup can be slowed down if too many servers need to be
contacted.
+@quotation Troubleshooting
+To diagnose problems, you can run @command{guix weather}. For example,
+running:
+
+@example
+guix weather coreutils
+@end example
+
+@noindent
+not only tells you which of the currently-configured servers has
+substitutes for the @code{coreutils} package, it also reports whether
+one of these servers is unauthorized. @xref{Invoking guix weather}, for
+more information.
+@end quotation
+
Note that there are also situations where one may want to add the URL of
a substitute server @emph{without} authorizing its key.
@xref{Substitute Authentication}, to understand this fine point.
@@ -7975,6 +7994,10 @@ The exact set of supported keywords depends on the build system
@code{#:phases}. The @code{#:phases} keyword in particular lets you
modify the set of build phases for your package (@pxref{Build Phases}).
+The REPL has dedicated commands to interactively inspect values of some
+of these arguments, as a convenient debugging aid (@pxref{Using Guix
+Interactively}).
+
@quotation Compatibility Note
Until version 1.3.0, the @code{arguments} field would typically use
@code{quote} (@code{'}) or @code{quasiquote} (@code{`}) and no
@@ -8774,6 +8797,23 @@ when @var{cut?} returns true for a given package. When @var{deep?} is true, @va
applied to implicit inputs as well.
@end deffn
+@quotation Tips
+Understanding what a variant really looks like can be difficult as one
+starts combining the tools shown above. There are several ways to
+inspect a package before attempting to build it that can prove handy:
+
+@itemize
+@item
+You can inspect the package interactively at the REPL, for instance to
+view its inputs, the code of its build phases, or its configure flags
+(@pxref{Using Guix Interactively}).
+
+@item
+When rewriting dependencies, @command{guix graph} can often help
+visualize the changes that are made (@pxref{Invoking guix graph}).
+@end itemize
+@end quotation
+
@node Writing Manifests
@section Writing Manifests
@@ -9558,6 +9598,20 @@ debugging information''), which roughly means that code is compiled with
@code{-O2 -g}, as is the case for Autoconf-based packages by default.
@end defvar
+@defvar composer-build-system
+This variable is exported by @code{(guix build-system composer)}. It
+implements the build procedure for packages using
+@url{https://getcomposer.org/, Composer}, the PHP package manager.
+
+It automatically adds the @code{php} package to the set of inputs. Which
+package is used can be specified with the @code{#:php} parameter.
+
+The @code{#:test-target} parameter is used to control which script is run
+for the tests. By default, the @code{test} script is run if it exists. If
+the script does not exist, the build system will run @code{phpunit} from the
+source directory, assuming there is a @file{phpunit.xml} file.
+@end defvar
+
@defvar dune-build-system
This variable is exported by @code{(guix build-system dune)}. It
supports builds of packages using @uref{https://dune.build/, Dune}, a build
@@ -10585,6 +10639,11 @@ we have seen before. @xref{Build Utilities}, for more about
the helpers used by this phase, and for more examples of
@code{modify-phases}.
+@quotation Tip
+You can inspect the code associated with a package's @code{#:phases}
+argument interactively, at the REPL (@pxref{Using Guix Interactively}).
+@end quotation
+
@cindex code staging
@cindex staging, of code
Keep in mind that build phases are code evaluated at the time the
@@ -12763,6 +12822,30 @@ scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
$5 = ("." ".." "egrep" "fgrep" "grep")
@end example
+As a packager, you may be willing to inspect the build phases or flags
+of a given package; this is particularly useful when relying a lot on
+inheritance to define package variants (@pxref{Defining Package
+Variants}) or when package arguments are a result of some computation,
+both of which can make it harder to foresee what ends up in the package
+arguments. Additional commands let you inspect those package arguments:
+
+@example
+scheme@@(guix-user)> ,phases grep
+$1 = (modify-phases %standard-phases
+ (add-after 'install 'fix-egrep-and-fgrep
+ (lambda* (#:key outputs #:allow-other-keys)
+ (let* ((out (assoc-ref outputs "out"))
+ (bin (string-append out "/bin")))
+ (substitute* (list (string-append bin "/egrep")
+ (string-append bin "/fgrep"))
+ (("^exec grep")
+ (string-append "exec " bin "/grep")))))))
+scheme@@(guix-user)> ,configure-flags findutils
+$2 = (list "--localstatedir=/var")
+scheme@@(guix-user)> ,make-flags binutils
+$3 = '("MAKEINFO=true")
+@end example
+
At a lower-level, a useful command is @code{lower}: it takes a file-like
object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
store file:
@@ -12794,6 +12877,17 @@ This is similar to the @option{--verbosity} command-line option
shows build events only, and higher levels print build logs.
@end deffn
+@deffn {REPL command} phases @var{package}
+@deffnx {REPL command} configure-flags @var{package}
+@deffnx {REPL command} make-flags @var{package}
+These REPL commands return the value of one element of the
+@code{arguments} field of @var{package} (@pxref{package Reference}): the
+first one show the staged code associated with @code{#:phases}
+(@pxref{Build Phases}), the second shows the code for
+@code{#:configure-flags}, and @code{,make-flags} returns the code for
+@code{#:make-flags}.
+@end deffn
+
@deffn {REPL command} run-in-store @var{exp}
Run @var{exp}, a monadic expression, through the store monad.
@xref{The Store Monad}, for more information.
@@ -14459,6 +14553,26 @@ Additional options include:
Traverse the dependency graph of the given upstream package recursively
and generate package expressions for all those packages that are not yet
in Guix.
+@end table
+
+@item composer
+@cindex Composer
+@cindex PHP
+Import metadata from the @uref{https://getcomposer.org/, Composer} package
+archive used by the PHP community, as in this example:
+
+@example
+guix import composer phpunit/phpunit
+@end example
+
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
@item --repo
By default, packages are searched in the official OPAM repository. This
option, which can be used more than once, lets you add other repositories
@@ -16437,7 +16551,10 @@ up building packages by yourself (@pxref{Substitutes}). The
specified servers so you can have an idea of whether you'll be grumpy
today. It can sometimes be useful info as a user, but it is primarily
useful to people running @command{guix publish} (@pxref{Invoking guix
-publish}).
+publish}). Sometimes substitutes @emph{are} available but they are not
+authorized on your system; @command{guix weather} reports it so you can
+authorize them if you want (@pxref{Getting Substitutes from Other
+Servers}).
@cindex statistics, for substitutes
@cindex availability of substitutes
@@ -16504,8 +16621,9 @@ The available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
@var{urls} is the space-separated list of substitute server URLs to
-query. When this option is omitted, the default set of substitute
-servers is queried.
+query. When this option is omitted, the URLs specified with the
+@option{--substitute-urls} option of @command{guix-daemon} are used or,
+as a last resort, the default set of substitute URLs.
@item --system=@var{system}
@itemx -s @var{system}
@@ -16699,6 +16817,7 @@ The available targets are:
- aarch64-linux-gnu
- arm-linux-gnueabihf
+ - avr
- i586-pc-gnu
- i686-linux-gnu
- i686-w64-mingw32
@@ -19316,7 +19435,8 @@ and DNS-SD.
@anchor{guix-configuration-build-machines}
@item @code{build-machines} (default: @code{#f})
This field must be either @code{#f} or a list of gexps evaluating to a
-@code{build-machine} record (@pxref{Daemon Offload Setup}).
+@code{build-machine} record or to a list of @code{build-machine} records
+(@pxref{Daemon Offload Setup}).
When it is @code{#f}, the @file{/etc/guix/machines.scm} file is left
untouched. Otherwise, the list of of gexps is written to
@@ -19385,7 +19505,8 @@ A list of file-like objects where each element contains a public key.
A list of strings where each element is a substitute URL.
@item @code{build-machines} (default: @code{'()})
-A list of gexps that evaluate to @code{build-machine} records
+A list of gexps that evaluate to @code{build-machine} records or to a list of
+@code{build-machine} records.
(@pxref{Daemon Offload Setup}).
Using this field, a service may add new build machines to receive builds
@@ -27589,6 +27710,66 @@ on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
@end table
@end deftp
+@subsubheading Rspamd Service
+@cindex email
+@cindex spam
+
+@defvar rspamd-service-type
+This is the type of the @uref{https://rspamd.com/, Rspamd} filtering
+system whose value should be a @code{rspamd-configuration}.
+@end defvar
+
+@c %start of fragment
+
+@deftp {Data Type} rspamd-configuration
+Available @code{rspamd-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{rspamd}) (type: file-like)
+The package that provides rspamd.
+
+@item @code{config-file} (default: @code{%default-rspamd-config-file}) (type: file-like)
+File-like object of the configuration file to use. By default all
+workers are enabled except fuzzy and they are binded to their usual
+ports, e.g localhost:11334, localhost:11333 and so on
+
+@item @code{local.d-files} (default: @code{()}) (type: directory-tree)
+Configuration files in local.d, provided as a list of two element lists
+where the first element is the filename and the second one is a
+file-like object. Settings in these files will be merged with the
+defaults.
+
+@item @code{override.d-files} (default: @code{()}) (type: directory-tree)
+Configuration files in override.d, provided as a list of two element
+lists where the first element is the filename and the second one is a
+file-like object. Settings in these files will override the defaults.
+
+@item @code{user} (default: @code{%default-rspamd-account}) (type: user-account)
+The user to run rspamd as.
+
+@item @code{group} (default: @code{%default-rspamd-group}) (type: user-group)
+The group to run rspamd as.
+
+@item @code{debug?} (default: @code{#f}) (type: boolean)
+Force debug output.
+
+@item @code{insecure?} (default: @code{#f}) (type: boolean)
+Ignore running workers as privileged users.
+
+@item @code{skip-template?} (default: @code{#f}) (type: boolean)
+Do not apply Jinja templates.
+
+@item @code{shepherd-requirements} (default: @code{(loopback)}) (type: list-of-symbols)
+This is a list of symbols naming Shepherd services that this service
+will depend on.
+
+@end table
+
+@end deftp
+
+
+@c %end of fragment
+
@node Messaging Services
@subsection Messaging Services
@@ -45763,6 +45944,11 @@ This optional string field is only relevant if the kernel is Linux. In
that case, it corresponds to the ARCH variable used when building Linux,
@code{"mips"} for instance.
+@item @code{rust-target} (default: @code{#false})
+This optional string field is used to determine which rust target is best
+supported by this platform. For example, the base level system targeted by
+@code{armhf-linux} system is closest to @code{armv7-unknown-linux-gnueabihf}.
+
@item @code{glibc-dynamic-linker}
This field is the name of the GNU C Library dynamic linker for the
corresponding system, as a string. It can be
@@ -45824,6 +46010,11 @@ Platform targeting x86 CPU running GNU/Hurd (also referred to as
``GNU'').
@end defvar
+@defvar avr
+Platform targeting AVR CPUs without an operating system, with run-time support
+from AVR Libc.
+@end defvar
+
@node System Images
@chapter Creating System Images