diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 11 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 12 | ||||
| -rw-r--r-- | doc/guix.texi | 201 |
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 |