diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/contributing.texi | 14 | ||||
-rw-r--r-- | doc/guix.texi | 674 | ||||
-rw-r--r-- | doc/package-hello.json | 6 |
3 files changed, 645 insertions, 49 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 5707ff5cde..a7d91724fb 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -2111,9 +2111,15 @@ they are ready to become a committer. Commit access should not be thought of as a ``badge of honor'' but rather as a responsibility a contributor is willing to take to help the project. It is expected from all contributors, and even more so from committers, to help build -consensus and make decisions based on consensus. To learn what -consensus decision making means and understand its finer details, you -are encouraged to read +consensus and make decisions based on consensus. By using consensus, we +are committed to finding solutions that everyone can live with. It +implies that no decision is made against significant concerns and these +concerns are actively resolved with proposals that work for everyone. A +contributor (which may or may not have commit access) wishing to block a +proposal bears a special responsibility for finding alternatives, +proposing ideas/code or explain the rationale for the status quo to +resolve the deadlock. To learn what consensus decision making means and +understand its finer details, you are encouraged to read @url{https://www.seedsforchange.org.uk/consensus}. The following sections explain how to get commit access, how to be ready @@ -2328,7 +2334,7 @@ Perhaps the biggest action you can do to help GNU Guix grow as a project is to review the work contributed by others. You do not need to be a committer to do so; applying, reading the source, building, linting and running other people's series and sharing your comments about your -experience will give some confidence to committers. Basically, you gmust +experience will give some confidence to committers. Basically, you must ensure the check list found in the @ref{Submitting Patches} section has been correctly followed. A reviewed patch series should give the best chances for the proposed change to be merged faster, so if a change you diff --git a/doc/guix.texi b/doc/guix.texi index ac17f91f7d..f6476e0d81 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -22,7 +22,7 @@ @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2} @copying -Copyright @copyright{} 2012-2023 Ludovic Courtès@* +Copyright @copyright{} 2012-2024 Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* @@ -43,7 +43,7 @@ Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@* Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@* Copyright @copyright{} 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe@* Copyright @copyright{} 2017 Federico Beffa@* -Copyright @copyright{} 2017, 2018 Carlo Zancanaro@* +Copyright @copyright{} 2017, 2018, 2024 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@* @@ -124,6 +124,7 @@ Copyright @copyright{} 2023 Thomas Ieong@* Copyright @copyright{} 2023 Saku Laesvuori@* Copyright @copyright{} 2023 Graham James Addis@* Copyright @copyright{} 2023 Tomas Volf@* +Copyright @copyright{} 2024 Herman Rimm@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -732,14 +733,17 @@ ready to use it. @cindex installing Guix from binaries @cindex installer script -This section describes how to install Guix on an arbitrary system from a -self-contained tarball providing binaries for Guix and for all its -dependencies. This is often quicker than installing from source, which -is described in the next sections. The only requirement is to have -GNU@tie{}tar and Xz. +This section describes how to install Guix from a self-contained tarball +providing binaries for Guix and for all its dependencies. This is often +quicker than installing from source, which is described in the next +sections. Binary installation requires a system using a Hurd or Linux +kernel; the GNU@tie{}tar and Xz commands must also be available. + +@quotation Important +This section only applies to systems without Guix. Following it for +existing Guix installations will overwrite important system files. @c Note duplicated from the ``Installation'' node. -@quotation Note We recommend the use of this @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, shell installer script}. The script automates the download, installation, and @@ -1297,6 +1301,11 @@ environment variable is set to the non-existent @file{/homeless-shelter}. This helps to highlight inappropriate uses of @env{HOME} in the build scripts of packages. +All this usually enough to ensure details of the environment do not +influence build processes. In some exceptional cases where more control +is needed---typically over the date, kernel, or CPU---you can resort to +a virtual build machine (@pxref{build-vm, virtual build machines}). + You can influence the directory where the daemon stores build trees @i{via} the @env{TMPDIR} environment variable. However, the build tree within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0}, @@ -9850,7 +9859,7 @@ MbedTLS package: (("generate_wrapper_header.*") (string-append "generate_wrapper_header(\"MbedTLS\", \"" - (assoc-ref inputs "mbedtls-apache") "\")\n")))) + (assoc-ref inputs "mbedtls") "\")\n")))) ;; There's a Julia file for each platform, override them all. (find-files "src/wrappers/" "\\.jl$")))) @end lisp @@ -14021,6 +14030,9 @@ the certificates of X.509 authorities from the directory pointed to by the @env{SSL_CERT_DIR} environment variable (@pxref{X.509 Certificates}), unless @option{--no-check-certificate} is used. +Alternatively, @command{guix download} can also retrieve a Git +repository, possibly a specific commit, tag, or branch. + The following options are available: @table @code @@ -14045,6 +14057,26 @@ URL, which makes you vulnerable to ``man-in-the-middle'' attacks. @itemx -o @var{file} Save the downloaded file to @var{file} instead of adding it to the store. + +@item --git +@itemx -g +Checkout the Git repository at the latest commit on the default branch. + +@item --commit=@var{commit-or-tag} +Checkout the Git repository at @var{commit-or-tag}. + +@var{commit-or-tag} can be either a tag or a commit defined in the Git +repository. + +@item --branch=@var{branch} +Checkout the Git repository at @var{branch}. + +The repository will be checked out at the latest commit of @var{branch}, +which must be a valid branch of the Git repository. + +@item --recursive +@itemx -r +Recursively clone the Git repository. @end table @node Invoking guix hash @@ -14155,12 +14187,21 @@ is a package definition, or a template thereof, in the format we know The general syntax is: @example -guix import @var{importer} @var{options}@dots{} +guix import [@var{global-options}@dots{}] @var{importer} @var{package} [@var{options}@dots{}] @end example @var{importer} specifies the source from which to import package metadata, and @var{options} specifies a package identifier and other -options specific to @var{importer}. +options specific to @var{importer}. @command{guix import} itself has the +following @var{global-options}: + +@table @code +@item --insert=@var{file} +@itemx -i @var{file} +Insert the package definition(s) that the @var{importer} generated into the +specified @var{file}, either in alphabetical order among existing package +definitions, or at the end of the file otherwise. +@end table Some of the importers rely on the ability to run the @command{gpgv} command. For these, GnuPG must be installed and in @code{$PATH}; run @code{guix install @@ -14311,7 +14352,7 @@ statistical and graphical environment}. Information is extracted from the @file{DESCRIPTION} file of the package. -The command command below imports metadata for the Cairo R package: +The command below imports metadata for the Cairo R package: @example guix import cran Cairo @@ -14371,10 +14412,10 @@ Information about the package is obtained from the TeX Live package database, a plain text file that is included in the @code{texlive-scripts} package. The source code is downloaded from possibly multiple locations in the SVN repository of the Tex Live -project. +project. Note that therefore SVN must be installed and in @code{$PATH}; +run @code{guix install subversion} if needed. -The command command below imports metadata for the @code{fontspec} -TeX package: +The command below imports metadata for the @code{fontspec} TeX package: @example guix import texlive fontspec @@ -16721,6 +16762,20 @@ guix package}). This option can be repeated several times, in which case the manifests are concatenated. +@item --expression=@var{expr} +@itemx -e @var{expr} +Consider the package @var{expr} evaluates to. + +A typical use case for this option is specifying a package that is +hidden and thus cannot be referred to in the usual way, as in this +example: + +@example +guix weather -e '(@@@@ (gnu packages rust) rust-bootstrap)' +@end example + +This option can be repeated. + @item --coverage[=@var{count}] @itemx -c [@var{count}] Report on substitute coverage for packages: list packages with at least @@ -16903,6 +16958,7 @@ The available targets are: - i686-linux-gnu - i686-w64-mingw32 - mips64el-linux-gnu + - or1k-elf - powerpc-linux-gnu - powerpc64le-linux-gnu - riscv64-linux-gnu @@ -20948,9 +21004,214 @@ networks. @item @code{disable-vpn?} (default: @code{#f}) When true, disable connman's vpn plugin. +@item @code{general-configuration} (default: @code{(connman-general-configuration)}) +Configuration serialized to @file{main.conf} and passed as @option{--config} +to @command{connmand}. + @end table @end deftp +@c %start of fragment + +@deftp {Data Type} connman-general-configuration +Available @code{connman-general-configuration} fields are: + +@table @asis +@item @code{input-request-timeout} (type: maybe-number) +Set input request timeout. Default is 120 seconds. The request for +inputs like passphrase will timeout after certain amount of time. Use +this setting to increase the value in case of different user interface +designs. + +@item @code{browser-launch-timeout} (type: maybe-number) +Set browser launch timeout. Default is 300 seconds. The request for +launching a browser for portal pages will timeout after certain amount +of time. Use this setting to increase the value in case of different +user interface designs. + +@item @code{background-scanning?} (type: maybe-boolean) +Enable background scanning. Default is true. If wifi is disconnected, +the background scanning will follow a simple back off mechanism from 3s +up to 5 minutes. Then, it will stay in 5 minutes unless user +specifically asks for scanning through a D-Bus call. If so, the +mechanism will start again from 3s. This feature activates also the +background scanning while being connected, which is required for roaming +on wifi. When @code{background-scanning?} is false, ConnMan will not +perform any scan regardless of wifi is connected or not, unless it is +requested by the user through a D-Bus call. + +@item @code{use-gateways-as-timeservers?} (type: maybe-boolean) +Assume that service gateways also function as timeservers. Default is +false. + +@item @code{fallback-timeservers} (type: maybe-list) +List of Fallback timeservers. These timeservers are used for NTP sync +when there are no timeservers set by the user or by the service, and +when @code{use-gateways-as-timeservers?} is @code{#f}. These can +contain a mixed combination of fully qualified domain names, IPv4 and +IPv6 addresses. + +@item @code{fallback-nameservers} (type: maybe-list) +List of fallback nameservers appended to the list of nameservers given +by the service. The nameserver entries must be in numeric format, host +names are ignored. + +@item @code{default-auto-connect-technologies} (type: maybe-list) +List of technologies that are marked autoconnectable by default. The +default value for this entry when empty is @code{"ethernet"}, +@code{"wifi"}, @code{"cellular"}. Services that are automatically +connected must have been set up and saved to storage beforehand. + +@item @code{default-favourite-technologies} (type: maybe-list) +List of technologies that are marked favorite by default. The default +value for this entry when empty is @code{"ethernet"}. Connects to +services from this technology even if not setup and saved to storage. + +@item @code{always-connected-technologies} (type: maybe-list) +List of technologies which are always connected regardless of +preferred-technologies setting (@code{auto-connect?} @code{#t}). The +default value is empty and this feature is disabled unless explicitly +enabled. + +@item @code{preferred-technologies} (type: maybe-list) +List of preferred technologies from the most preferred one to the least +preferred one. Services of the listed technology type will be tried one +by one in the order given, until one of them gets connected or they are +all tried. A service of a preferred technology type in state 'ready' +will get the default route when compared to another preferred type +further down the list with state 'ready' or with a non-preferred type; a +service of a preferred technology type in state 'online' will get the +default route when compared to either a non-preferred type or a +preferred type further down in the list. + +@item @code{network-interface-blacklist} (type: maybe-list) +List of blacklisted network interfaces. Found interfaces will be +compared to the list and will not be handled by ConnMan, if their first +characters match any of the list entries. Default value is +@code{"vmnet"}, @code{"vboxnet"}, @code{"virbr"}, @code{"ifb"}. + +@item @code{allow-hostname-updates?} (type: maybe-boolean) +Allow ConnMan to change the system hostname. This can happen for +example if we receive DHCP hostname option. Default value is @code{#t}. + +@item @code{allow-domainname-updates?} (type: maybe-boolean) +Allow connman to change the system domainname. This can happen for +example if we receive DHCP domainname option. Default value is +@code{#t}. + +@item @code{single-connected-technology?} (type: maybe-boolean) +Keep only a single connected technology at any time. When a new service +is connected by the user or a better one is found according to +preferred-technologies, the new service is kept connected and all the +other previously connected services are disconnected. With this setting +it does not matter whether the previously connected services are in +'online' or 'ready' states, the newly connected service is the only one +that will be kept connected. A service connected by the user will be +used until going out of network coverage. With this setting enabled +applications will notice more network breaks than normal. Note this +options can't be used with VPNs. Default value is @code{#f}. + +@item @code{tethering-technologies} (type: maybe-list) +List of technologies that are allowed to enable tethering. The default +value is @code{"wifi"}, @code{"bluetooth"}, @code{"gadget"}. Only those +technologies listed here are used for tethering. If one wants to tether +ethernet, then add @code{"ethernet"} in the list. Note that if ethernet +tethering is enabled, then a DHCP server is started on all ethernet +interfaces. Tethered ethernet should never be connected to corporate or +home network as it will disrupt normal operation of these networks. Due +to this ethernet is not tethered by default. Do not activate ethernet +tethering unless you really know what you are doing. + +@item @code{persistent-tethering-mode?} (type: maybe-boolean) +Restore earlier tethering status when returning from offline mode, +re-enabling a technology, and after restarts and reboots. Default value +is @code{#f}. + +@item @code{enable-6to4?} (type: maybe-boolean) +Automatically enable anycast 6to4 if possible. This is not recommended, +as the use of 6to4 will generally lead to a severe degradation of +connection quality. See RFC6343. Default value is @code{#f} (as +recommended by RFC6343 section 4.1). + +@item @code{vendor-class-id} (type: maybe-string) +Set DHCP option 60 (Vendor Class ID) to the given string. This option +can be used by DHCP servers to identify specific clients without having +to rely on MAC address ranges, etc. + +@item @code{enable-online-check?} (type: maybe-boolean) +Enable or disable use of HTTP GET as an online status check. When a +service is in a READY state, and is selected as default, ConnMan will +issue an HTTP GET request to verify that end-to-end connectivity is +successful. Only then the service will be transitioned to ONLINE state. +If this setting is false, the default service will remain in READY +state. Default value is @code{#t}. + +@item @code{online-check-ipv4-url} (type: maybe-string) +IPv4 URL used during the online status check. Please refer to the +README for more detailed information. Default value is +@uref{http://ipv4.connman.net/online/status.html}. + +@item @code{online-check-ipv6-url} (type: maybe-string) +IPv6 URL used during the online status check. Please refer to the +README for more detailed information. Default value is +@uref{http://ipv6.connman.net/online/status.html}. + +@item @code{online-check-initial-interval} (type: maybe-number) +Range of intervals between two online check requests. Please refer to +the README for more detailed information. Default value is @samp{1}. + +@item @code{online-check-max-interval} (type: maybe-number) +Range of intervals between two online check requests. Please refer to +the README for more detailed information. Default value is @samp{1}. + +@item @code{enable-online-to-ready-transition?} (type: maybe-boolean) +WARNING: This is an experimental feature. In addition to +@code{enable-online-check} setting, enable or disable use of HTTP GET to +detect the loss of end-to-end connectivity. If this setting is +@code{#f}, when the default service transitions to ONLINE state, the +HTTP GET request is no more called until next cycle, initiated by a +transition of the default service to DISCONNECT state. If this setting +is @code{#t}, the HTTP GET request keeps being called to guarantee that +end-to-end connectivity is still successful. If not, the default +service will transition to READY state, enabling another service to +become the default one, in replacement. Default value is @code{#f}. + +@item @code{auto-connect-roaming-services?} (type: maybe-boolean) +Automatically connect roaming services. This is not recommended unless +you know you won't have any billing problem. Default value is +@code{#f}. + +@item @code{address-conflict-detection?} (type: maybe-boolean) +Enable or disable the implementation of IPv4 address conflict detection +according to RFC5227. ConnMan will send probe ARP packets to see if an +IPv4 address is already in use before assigning the address to an +interface. If an address conflict occurs for a statically configured +address, an IPv4LL address will be chosen instead (according to +RFC3927). If an address conflict occurs for an address offered via +DHCP, ConnMan sends a DHCP DECLINE once and for the second conflict +resorts to finding an IPv4LL address. Default value is @code{#f}. + +@item @code{localtime} (type: maybe-string) +Path to localtime file. Defaults to @file{/etc/localtime}. + +@item @code{regulatory-domain-follows-timezone?} (type: maybe-boolean) +Enable regulatory domain to be changed along timezone changes. With +this option set to true each time the timezone changes the first present +ISO3166 country code is read from +@file{/usr/share/zoneinfo/zone1970.tab} and set as regulatory domain +value. Default value is @code{#f}. + +@item @code{resolv-conf} (type: maybe-string) +Path to resolv.conf file. If the file does not exist, but intermediate +directories exist, it will be created. If this option is not set, it +tries to write into @file{/var/run/connman/resolv.conf} if it fails +(@file{/var/run/connman} does not exist or is not writeable). If you do +not want to update resolv.conf, you can set @file{/dev/null}. + +@end table + +@end deftp + @cindex WPA Supplicant @defvar wpa-supplicant-service-type This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA @@ -25555,6 +25816,9 @@ The @code{(gnu services databases)} module provides the following services. @subsubheading PostgreSQL +@defvar postgresql-service-type +The service type for the PostgreSQL database server. Its value should +be a valid @code{postgresql-configuration} object, documented below. The following example describes a PostgreSQL service with the default configuration. @@ -25581,6 +25845,7 @@ sudo -u postgres -s /bin/sh createuser --interactive createdb $MY_USER_LOGIN # Replace appropriately. @end example +@end defvar @deftp {Data Type} postgresql-configuration Data type representing the configuration for the @@ -27888,7 +28153,7 @@ Prosodyctl will also help you to import certificates from the them. See @url{https://prosody.im/doc/letsencrypt}. @example -prosodyctl --root cert import /etc/letsencrypt/live +prosodyctl --root cert import /etc/certs @end example The available configuration parameters follow. Each parameter @@ -28354,10 +28619,11 @@ services: @subsubheading Jami -@cindex jami, service - -This section describes how to configure a Jami server that can be used -to host video (or audio) conferences, among other uses. The following +@defvar jami-service-type +The service type for running Jami as a service. It takes a +@code{jami-configuration} object as a value, documented below. This +section describes how to configure a Jami server that can be used to +host video (or audio) conferences, among other uses. The following example demonstrates how to specify Jami account archives (backups) to be provisioned automatically: @@ -28485,6 +28751,7 @@ Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199 The remaining actions should be self-explanatory. The complete set of available configuration options is detailed below. +@end defvar @c TODO: Ideally, the following fragments would be auto-generated at @c build time, so that they needn't be manually duplicated. @@ -28581,6 +28848,12 @@ account fingerprint for a registered username. This section describes how to set up and run a @uref{https://mumble.info, Mumble} server (formerly known as Murmur). +@defvar mumble-server-service-type + +This is the service to run a Mumble server. It takes a +@code{mumble-server-configuration} object as its value, defined below. +@end defvar + @deftp {Data Type} mumble-server-configuration The service type for the Mumble server. An example configuration can look like this: @@ -28591,8 +28864,8 @@ look like this: (welcome-text "Welcome to this Mumble server running on Guix!") (cert-required? #t) ;disallow text password logins - (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") - (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) + (ssl-cert "/etc/certs/mumble.example.com/fullchain.pem") + (ssl-key "/etc/certs/mumble.example.com/privkey.pem"))) @end lisp After reconfiguring your system, you can manually set the mumble-server @@ -28710,12 +28983,12 @@ Should logged ips be obfuscated to protect the privacy of users. File name of the SSL/TLS certificate used for encrypted connections. @lisp -(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") +(ssl-cert "/etc/certs/example.com/fullchain.pem") @end lisp @item @code{ssl-key} (default: @code{#f}) Filepath to the ssl private key used for encrypted connections. @lisp -(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") +(ssl-key "/etc/certs/example.com/privkey.pem") @end lisp @item @code{ssl-dh-params} (default: @code{#f}) @@ -31603,6 +31876,50 @@ Additional arguments to pass to the @command{varnishd} process. @end table @end deftp +@subheading Whoogle Search +@cindex Whoogle Search + +@uref{https://github.com/benbusby/whoogle-search, Whoogle Search} is a +self-hosted, ad-free, privacy-respecting meta search engine that collects +and displays Google search results. By default, you can configure it by +adding this line to the @code{services} field of your operating system +declaration: + +@lisp +(service whoogle-service-type) +@end lisp + +As a result, Whoogle Search runs as local Web server, which you can +access by opening @indicateurl{http://localhost:5000} in your browser. +The configuration reference is given below. + +@defvar whoogle-service-type +Service type for Whoogle Search. Its value must be a +@code{whoogle-configuration} record---see below. +@end defvar + +@deftp {Data Type} whoogle-configuration +Data type representing Whoogle Search service configuration. + +@table @asis +@item @code{package} (default: @code{whoogle-search}) +The Whoogle Search package to use. + +@item @code{host} (default: @code{"127.0.0.1"}) +The host address to run Whoogle on. + +@item @code{port} (default: @code{5000}) +The port where Whoogle will be exposed. + +@item @code{environment-variables} (default: @code{'()}) +A list of strings with the environment variables to configure Whoogle. +You can consult +@uref{https://github.com/benbusby/whoogle-search/blob/main/whoogle.template.env, +its environment variables template} for the list of available options. + +@end table +@end deftp + @subsubheading Patchwork @cindex Patchwork Patchwork is a patch tracking system. It can collect patches sent to a @@ -32307,21 +32624,13 @@ A service type for the @code{certbot} Let's Encrypt client. Its value must be a @code{certbot-configuration} record as in this example: @lisp -(define %certbot-deploy-hook - (program-file "certbot-deploy-hook.scm" - (with-imported-modules '((gnu services herd)) - #~(begin - (use-modules (gnu services herd)) - (with-shepherd-action 'nginx ('reload) result result))))) - (service certbot-service-type (certbot-configuration (email "foo@@example.net") (certificates (list (certificate-configuration - (domains '("example.net" "www.example.net")) - (deploy-hook %certbot-deploy-hook)) + (domains '("example.net" "www.example.net"))) (certificate-configuration (domains '("bar.example.net"))))))) @end lisp @@ -32435,12 +32744,18 @@ certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a space-delimited list of renewed certificate domains (for example, @samp{"example.com www.example.com"}. +@item @code{start-self-signed?} (default: @code{#t}) +Whether to generate an initial self-signed certificate during system +activation. This option is particularly useful to allow @code{nginx} to +start before @code{certbot} has run, because @code{certbot} relies on +@code{nginx} running to perform HTTP challenges. + @end table @end deftp For each @code{certificate-configuration}, the certificate is saved to -@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is -saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. +@code{/etc/certs/@var{name}/fullchain.pem} and the key is +saved to @code{/etc/certs/@var{name}/privkey.pem}. @node DNS Services @subsection DNS Services @cindex DNS (domain name system) @@ -36081,6 +36396,142 @@ host. If empty, QEMU uses a default file name. @end deftp +@anchor{build-vm} +@subsubheading Virtual Build Machines + +@cindex virtual build machines +@cindex build VMs +@cindex VMs, for offloading +@dfn{Virtual build machines} or ``build VMs'' let you offload builds to +a fully controlled environment. ``How can it be more controlled than +regular builds? And why would it be useful?'', you ask. Good +questions. + +Builds spawned by @code{guix-daemon} indeed run in a controlled +environment; specifically the daemon spawns build processes in separate +namespaces and in a chroot, such as that build processes only see their +declared dependencies and a well-defined subset of the file system tree +(@pxref{Build Environment Setup}, for details). A few aspects of the +environments are not controlled though: the operating system kernel, the +CPU model, and the date. Most of the time, these aspects have no impact +on the build process: the level of isolation @code{guix-daemon} provides +is ``good enough''. + +@cindex time traps +However, there are occasionally cases where those aspects @emph{do} +influence the build process. A typical example is @dfn{time traps}: +build processes that stop working after a certain date@footnote{The most +widespread example of time traps is test suites that involve checking +the expiration date of a certificate. Such tests exists in TLS +implementations such as OpenSSL and GnuTLS, but also in high-level +software such as Python.}. Another one is software that optimizes for +the CPU microarchitecture it is built on or, worse, bugs that manifest +only on specific CPUs. + +To address that, @code{virtual-build-machine-service-type} lets you add +a virtual build machine on your system, as in this example: + +@lisp +(use-modules (gnu services virtualization)) + +(operating-system + ;; @dots{} + (services (append (list (service virtual-build-machine-service-type)) + %base-services))) +@end lisp + +By default, you have to explicitly start the build machine when you need +it, at which point builds may be offloaded to it (@pxref{Daemon Offload +Setup}): + +@example +herd start build-vm +@end example + +With the default setting shown above, the build VM runs with its clock +set to a date several years in the past, and on a CPU model that +corresponds to that date---a model possibly older than that of your +machine. This lets you rebuild today software from the past that would +otherwise fail to build due to a time trap or other issues in its build +process. You can view the VM's config like this: + +@example +herd configuration build-vm +@end example + +You can configure the build VM, as in this example: + +@lisp +(service virtual-build-machine-service-type + (virtual-build-machine + (cpu "Westmere") + (cpu-count 8) + (memory-size (* 1 1024)) + (auto-start? #t))) +@end lisp + +The available options are shown below. + +@defvar virtual-build-machine-service-type +This is the service type to run @dfn{virtual build machines}. Virtual +build machines are configured so that builds are offloaded to them when +they are running. +@end defvar + +@deftp {Data Type} virtual-build-machine +This is the data type specifying the configuration of a build machine. +It contains the fields below: + +@table @asis +@item @code{name} (default: @code{'build-vm}) +The name of this build VM. It is used to construct the name of its +Shepherd service. + +@item @code{image} +The image of the virtual machine (@pxref{System Images}). This notably +specifies the virtual disk size and the operating system running into it +(@pxref{operating-system Reference}). The default value is a minimal +operating system image. + +@item @code{qemu} (default: @code{qemu-minimal}) +The QEMU package to run the image. + +@item @code{cpu} +The CPU model being emulated as a string denoting a model known to QEMU. + +The default value is a model that matches @code{date} (see below). To +see what CPU models are available, run, for example: + +@example +qemu-system-x86_64 -cpu help +@end example + +@item @code{cpu-count} (default: @code{4}) +The number of CPUs emulated by the virtual machine. + +@item @code{memory-size} (default: @code{2048}) +Size in mebibytes (MiB) of the virtual machine's main memory (RAM). + +@item @code{date} (default: a few years ago) +Date inside the virtual machine when it starts; this must be a SRFI-19 +date object (@pxref{SRFI-19 Date,,, guile, GNU Guile Reference Manual}). + +@item @code{port-forwardings} (default: 11022 and 11004) +TCP ports of the virtual machine forwarded to the host. By default, the +SSH and secrets ports are forwarded into the host. + +@item @code{systems} (default: @code{(list (%current-system))}) +List of system types supported by the build VM---e.g., +@code{"x86_64-linux"}. + +@item @code{auto-start?} (default: @code{#f}) +Whether to start the virtual machine when the system boots. +@end table +@end deftp + +In the next section, you'll find a variant on this theme: GNU/Hurd +virtual machines! + @anchor{hurd-vm} @subsubheading The Hurd in a Virtual Machine @@ -37126,9 +37577,9 @@ serve the default @file{/srv/git} over HTTPS might be: (listen '("443 ssl")) (server-name "git.my-host.org") (ssl-certificate - "/etc/letsencrypt/live/git.my-host.org/fullchain.pem") + "/etc/certs/git.my-host.org/fullchain.pem") (ssl-certificate-key - "/etc/letsencrypt/live/git.my-host.org/privkey.pem") + "/etc/certs/git.my-host.org/privkey.pem") (locations (list (git-http-nginx-location-configuration @@ -38253,9 +38704,9 @@ footers. (nginx-server-block (nginx-server-configuration (ssl-certificate - "/etc/letsencrypt/live/myweb.site/fullchain.pem") + "/etc/certs/myweb.site/fullchain.pem") (ssl-certificate-key - "/etc/letsencrypt/live/myweb.site/privkey.pem") + "/etc/certs/myweb.site/privkey.pem") (listen '("443 ssl http2" "[::]:443 ssl http2")) (locations (list @@ -40060,16 +40511,31 @@ After @command{guix system reconfigure} configure Nix for your user: @itemize @item Add a Nix channel and update it. See -@url{https://nixos.org/nix/manual/, Nix Package Manager Guide}. +@url{https://nixos.wiki/wiki/Nix_channels, Nix channels} for more +information about the available channels. If you would like to use the +unstable Nix channel you can do this by running: + +@example +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable +$ nix-channel --update +@end example + +@item Create your Nix profile directory: + +@example +$ sudo mkdir -p /nix/var/nix/profiles/per-user/$USER +$ sudo chown $USER:root /nix/var/nix/profiles/per-user/$USER +@end example @item Create a symlink to your profile and activate Nix profile: -@end itemize @example $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile $ source /run/current-system/profile/etc/profile.d/nix.sh @end example +@end itemize + @end defvar @deftp {Data Type} nix-configuration @@ -42888,6 +43354,15 @@ shepherd, The GNU Shepherd Manual}, for more info. Whether to restart the service when it stops, for instance when the underlying process dies. +@item @code{respawn-limit} (default: @code{#f}) +Set a limit on how many times and how frequently a service may be +restarted by Shepherd before it is disabled. @xref{Defining +Services,,, shepherd, The GNU Shepherd Manual}, for details. + +@item @code{respawn-delay} (default: @code{#f}) +When true, this is the delay in seconds before restarting a failed +service. + @item @code{start} @itemx @code{stop} (default: @code{#~(const #f)}) The @code{start} and @code{stop} fields refer to the Shepherd's @@ -43120,7 +43595,7 @@ A clause has the following form: the generated record. @var{type-decl} is either @code{@var{type}} for fields that require a -value to be set or @code{(@var{type} @var{default})} otherwise. +value to be set or @code{(@var{type} @var{default-value})} otherwise. @var{type} is the type of the value corresponding to @var{field-name}; since Guile is untyped, a predicate @@ -43961,6 +44436,116 @@ to use alternative services to implement more advanced use cases like read-only home. Feel free to experiment and share your results. @end defvar +@cindex dot files in Guix Home +It is often the case that Guix Home users already have a setup for versioning +their user configuration files (also known as @emph{dot files}) in a single +directory, and some way of automatically deploy changes to their user home. + +@cindex Stow-like dot file management +The @code{home-dotfiles-service-type} from @code{(gnu home services dotfiles)} +is designed to ease the way into using Guix Home for this kind of users, +allowing them to point the service to their dotfiles directory, which must +follow the layout suggested by +@uref{https://www.gnu.org/software/stow/, GNU Stow}, +and have their dotfiles automatically deployed to their user home, without +migrating them to Guix native configurations. + +The dotfiles directory layout is expected to be structured as follows. Please +keep in mind that it is advisable to keep your dotfiles directories under +version control, for example in the same repository where you'd track your +Guix Home configuration. + +@example +~$ tree -a ./dotfiles/ +dotfiles/ +├── git +│ └── .gitconfig +├── gpg +│ └── .gnupg +│ ├── gpg-agent.conf +│ └── gpg.conf +├── guile +│ └── .guile +├── guix +│ └── .config +│ └── guix +│ └── channels.scm +├── nix +│ ├── .config +│ │ └── nixpkgs +│ │ └── config.nix +│ └── .nix-channels +├── tmux +│ └── .tmux.conf +└── vim + └── .vimrc + +13 directories, 10 files +@end example + +For an informal specification please refer to the Stow manual +(@pxref{Top,,, stow, Introduction}). A suitable configuration would then +be: + +@lisp +(home-environment + ;; @dots{} + (services + (service home-dotfiles-service-type + (home-dotfiles-configuration + (directories (list "./dotfiles")))))) +@end lisp + +The expected home directory state would then be: + +@example +. +├── .config +│ ├── guix +│ │ └── channels.scm +│ └── nixpkgs +│ └── config.nix +├── .gitconfig +├── .gnupg +│ ├── gpg-agent.conf +│ └── gpg.conf +├── .guile +├── .nix-channels +├── .tmux.conf +└── .vimrc +@end example + +@defvar home-dotfiles-service-type +Return a service which is very similiar to @code{home-files-service-type} +(and actually extends it), but designed to ease the way into using Guix +Home for users that already track their dotfiles under some kind of version +control. This service allows users to point Guix Home to their dotfiles +directory and have their files automatically deployed to their home directory +just like Stow would, without migrating all of their dotfiles to Guix native +configurations. +@end defvar + +@deftp {Data Type} home-dotfiles-configuration +Available @code{home-dotfiles-configuration} fields are: + +@table @asis +@item @code{source-directory} (default: @code{(current-source-directory)}) +The path where dotfile directories are resolved. By default dotfile directories +are resolved relative the source location where +@code{home-dotfiles-configuration} appears. + +@item @code{directories} (type: list-of-strings) +The list of dotfiles directories where @code{home-dotfiles-service-type} will +look for application dotfiles. + +@item @code{exclude} (default: @code{'(".*~" ".*\\.swp" "\\.git" "\\.gitignore")}) +The list of file patterns @code{home-dotfiles-service-type} will exclude while +visiting each one of the @code{directories}. + +@end table + +@end deftp + @defvar home-xdg-configuration-files-service-type The service is very similar to @code{home-files-service-type} (and actually extends it), but used for defining files, which will go to @@ -46167,6 +46752,11 @@ Platform targeting AVR CPUs without an operating system, with run-time support from AVR Libc. @end defvar +@defvar or1k-elf +Platform targeting OpenRISC 1000 CPU without an operating system and without a +C standard library. +@end defvar + @node System Images @chapter Creating System Images diff --git a/doc/package-hello.json b/doc/package-hello.json index a47e266e4b..60193e97e6 100644 --- a/doc/package-hello.json +++ b/doc/package-hello.json @@ -6,7 +6,7 @@ "build-system": "gnu", "arguments": { "tests?": false - } + }, "home-page": "https://www.gnu.org/software/hello/", "synopsis": "Hello, GNU world: An example GNU package", "description": "GNU Hello prints a greeting.", @@ -16,11 +16,11 @@ { "name": "greeter", "version": "1.0", - "source": "https://example.com/greeter-1.0.tar.gz", + "source": "mirror://gnu/hello/hello-2.10.tar.gz", "build-system": "gnu", "arguments": { "test-target": "foo", - "parallel-build?": false, + "parallel-build?": false }, "home-page": "https://example.com/", "synopsis": "Greeter using GNU Hello", |