From ec9c8b0c1a0982e97375df0ae44af4fdc72c3757 Mon Sep 17 00:00:00 2001 From: Maxim Cournoyer Date: Wed, 21 Feb 2024 11:55:25 -0500 Subject: doc: Refine wording of binary installation introductory text. * doc/guix.texi (Binary Installation): Mention the requirement to use a Hurd or Linux kernel for the binary installation. Suggested-by: Matt Change-Id: Ibc0552f59be4fdaaf8d44a5222e6feb925d3f06f --- doc/guix.texi | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 9966a8e697..34aa3545da 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -732,14 +732,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 -- cgit v1.2.3 From bf746ae2586030ad70904c151ddd1f8ee6645926 Mon Sep 17 00:00:00 2001 From: Herman Rimm Date: Tue, 20 Feb 2024 21:45:09 +0100 Subject: doc: Note SVN dependency of texlive importer. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Invoking guix import): Note dependency and remove duplicated words. Change-Id: I94320db8c8ab3569aa461876522d5560e37a19ea Signed-off-by: Ludovic Courtès --- doc/guix.texi | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 34aa3545da..b761ec58bc 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -14342,7 +14342,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 @@ -14402,10 +14402,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 -- cgit v1.2.3 From 635af8628c096526e3a79348f484e641aa05f04a Mon Sep 17 00:00:00 2001 From: Herman Rimm Date: Tue, 20 Feb 2024 21:45:13 +0100 Subject: import: Insert packages into modules alphabetically. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * guix/scripts/import.scm (guix-import): Add 'insert' option. (import-as-definitions): Add procedure. * doc/guix.texi (Invoking guix import): Describe 'insert' option. Change-Id: Id87ea707123630e12bcb6788599acac6895b26c4 Signed-off-by: Ludovic Courtès --- doc/guix.texi | 14 +++++++-- guix/scripts/import.scm | 82 ++++++++++++++++++++++++++++++++----------------- 2 files changed, 65 insertions(+), 31 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index b761ec58bc..671cdab6f8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -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 @@ -14186,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 diff --git a/guix/scripts/import.scm b/guix/scripts/import.scm index 77fcfe3990..aca4e61f26 100644 --- a/guix/scripts/import.scm +++ b/guix/scripts/import.scm @@ -67,10 +67,39 @@ (define (show-help) (display (G_ " -h, --help display this help and exit")) (display (G_ " + -i, --insert insert packages into file alphabetically")) + (display (G_ " -V, --version display version information and exit")) (newline) (show-bug-report-information)) +(define (import-as-definitions importer args proc) + "Wrap package expressions from IMPORTER with 'define-public and invoke +PROC callback." + (if (member importer importers) + (match (apply (resolve-importer importer) args) + ((and expr (or ('package _ ...) + ('let _ ...))) + (proc (package->definition expr))) + ((and expr ('define-public _ ...)) + (proc expr)) + ((expressions ...) + (for-each (lambda (expr) + (match expr + ((and expr (or ('package _ ...) + ('let _ ...))) + (proc (package->definition expr))) + ((and expr ('define-public _ ...)) + (proc expr)))) + expressions)) + (x + (leave (G_ "'~a' import failed~%") importer))) + (let ((hint (string-closest importer importers #:threshold 3))) + (report-error (G_ "~a: invalid importer~%") importer) + (when hint + (display-hint (G_ "Did you mean @code{~a}?~%") hint)) + (exit 1)))) + (define-command (guix-import . args) (category packaging) (synopsis "import a package definition from an external repository") @@ -84,33 +113,28 @@ (define-command (guix-import . args) (exit 0)) ((or ("-V") ("--version")) (show-version-and-exit "guix import")) + ((or ("-i" file importer args ...) + ("--insert" file importer args ...)) + (let ((find-and-insert + (lambda (expr) + (match expr + (('define-public term _ ...) + (let ((source-properties + (find-definition-insertion-location + file term))) + (if source-properties + (insert-expression source-properties expr) + (let ((port (open-file file "a"))) + (pretty-print-with-comments port expr) + (newline port) + (close-port port))))))))) + (import-as-definitions importer args find-and-insert))) ((importer args ...) - (if (member importer importers) - (let ((print (lambda (expr) - (leave-on-EPIPE - (pretty-print-with-comments (current-output-port) expr))))) - (match (apply (resolve-importer importer) args) - ((and expr (or ('package _ ...) - ('let _ ...))) - (print (package->definition expr))) - ((and expr ('define-public _ ...)) - (print expr)) - ((? list? expressions) - (for-each (lambda (expr) - (match expr - ((and expr (or ('package _ ...) - ('let _ ...))) - (print (package->definition expr))) - ((and expr ('define-public _ ...)) - (print expr))) - ;; Two newlines: one after the closing paren, and - ;; one to leave a blank line. - (newline) (newline)) - expressions)) - (x - (leave (G_ "'~a' import failed~%") importer)))) - (let ((hint (string-closest importer importers #:threshold 3))) - (report-error (G_ "~a: invalid importer~%") importer) - (when hint - (display-hint (G_ "Did you mean @code{~a}?~%") hint)) - (exit 1)))))) + (let ((print (lambda (expr) + (leave-on-EPIPE + (pretty-print-with-comments + (current-output-port) expr) + ;; Two newlines: one after the closing paren, and + ;; one to leave a blank line. + (newline) (newline))))) + (import-as-definitions importer args print))))) -- cgit v1.2.3 From b386c11e7804e0b577411d930b60f1e0a4a0382c Mon Sep 17 00:00:00 2001 From: Herman Rimm Date: Tue, 20 Feb 2024 21:45:15 +0100 Subject: import: Do not return package name with json importer. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * guix/import/json.scm (json->code): Do not return package names after package expressions. * doc/package-hello.json: Fix comma errors and use valid greeter URL. Change-Id: Id71924e72f690a9bda5fbfdb65a443029adfd158 Signed-off-by: Ludovic Courtès --- doc/package-hello.json | 6 +++--- guix/import/json.scm | 13 ++++++------- 2 files changed, 9 insertions(+), 10 deletions(-) (limited to 'doc') 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", diff --git a/guix/import/json.scm b/guix/import/json.scm index b87e9918c5..bf346a1bef 100644 --- a/guix/import/json.scm +++ b/guix/import/json.scm @@ -78,14 +78,13 @@ (define (json->code file-name) #:result (append result (list - (package->code (alist->package pkg names)) - (string->symbol (assoc-ref pkg "name")))))))) - (list #:names '() - #:result '()) - packages)))) + (package->code + (alist->package pkg names)))))))) + (list #:names '() + #:result '()) + packages)))) (package - (list (package->code (alist->package json)) - (string->symbol (assoc-ref json "name"))))))) + (list (package->code (alist->package json))))))) (const #f))) (define (json->scheme-file file) -- cgit v1.2.3 From e64617c5fab2bec558ae6333cdbdcd62cac8ad1f Mon Sep 17 00:00:00 2001 From: Carlo Zancanaro Date: Wed, 7 Feb 2024 00:18:49 +1100 Subject: doc: Document required setup steps for Nix service. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Nix service): Add specific channel setup commands, add commands to create profile directory. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 671cdab6f8..f6476e0d81 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -40511,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 -- cgit v1.2.3 From 60c9a339df930093064d37f91070915c25a7493b Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 21 Feb 2024 15:45:15 +0100 Subject: doc: Add “Getting Started with the System” section. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Getting Started with the System): New node. (After System Installation): Refer to it. Move note about ‘sudo guix pull’ to the “Getting Started with the System”. (Getting Started): Refer to it. Move note about ‘guix system roll-back’ to “Getting Started with the System”. (Features): Refer to it. (Using the Configuration System): Adjust intro. Add “Troubleshooting” note that mentions ‘guix style -f’ for misplaced parens. (Instantiating the System): Simplify and cross-reference “Getting Started with the System”. Change-Id: Ie74f598450e8059a4579a016e2aeca2edd7696a7 --- doc/guix.texi | 320 ++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 244 insertions(+), 76 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index f6476e0d81..dca91dc0c9 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -358,6 +358,7 @@ Foreign Architectures System Configuration +* Getting Started with the System:: Your first steps. * Using the Configuration System:: Customizing your GNU system. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. @@ -2879,8 +2880,8 @@ unless your configuration specifies otherwise @node After System Installation @section After System Installation -Success, you've now booted into Guix System! From then on, you can update the -system whenever you want by running, say: +Success, you've now booted into Guix System! You can upgrade the system +whenever you want by running: @example guix pull @@ -2888,24 +2889,10 @@ sudo guix system reconfigure /etc/config.scm @end example @noindent -This builds a new system generation with the latest packages and services -(@pxref{Invoking guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Security Updates}). - -@c See . -@quotation Note -@cindex sudo vs. @command{guix pull} -Note that @command{sudo guix} runs your user's @command{guix} command and -@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To -explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. - -The difference matters here, because @command{guix pull} updates -the @command{guix} command and package definitions only for the user it is run -as. This means that if you choose to use @command{guix system reconfigure} in -root's login shell, you'll need to @command{guix pull} separately. -@end quotation +This builds a new system @dfn{generation} with the latest packages and +services. -Now, @pxref{Getting Started}, and +Now, @pxref{Getting Started with the System}, and join us on @code{#guix} on the Libera Chat IRC network or on @email{guix-devel@@gnu.org} to share your experience! @@ -3159,22 +3146,9 @@ sudo guix system reconfigure /etc/config.scm @end example Upon completion, the system runs the latest versions of its software -packages. When you eventually reboot, you'll notice a sub-menu in the -bootloader that reads ``Old system generations'': it's what allows you -to boot @emph{an older generation of your system}, should the latest -generation be ``broken'' or otherwise unsatisfying. Just like for -packages, you can always @emph{roll back} to a previous generation -@emph{of the whole system}: - -@example -sudo guix system roll-back -@end example - -There are many things you'll probably want to tweak on your system: -adding new user accounts, adding new system services, fiddling with the -configuration of those services, etc. The system configuration is -@emph{entirely} described in the @file{/etc/config.scm} file. -@xref{Using the Configuration System}, to learn how to change it. +packages. Just like for packages, you can always @emph{roll back} to a +previous generation @emph{of the whole system}. @xref{Getting Started +with the System}, to learn how to manage your system. Now you know enough to get started! @@ -3283,7 +3257,7 @@ out to have a serious bug, users may roll back to the previous instance of their profile, which was known to work well. Similarly, the global system configuration on Guix is subject to transactional upgrades and roll-back -(@pxref{Using the Configuration System}). +(@pxref{Getting Started with the System}). All packages in the package store may be @emph{garbage-collected}. Guix can determine which packages are still referenced by user @@ -17101,6 +17075,7 @@ instantiated. Then we show how this mechanism can be extended, for instance to support new system services. @menu +* Getting Started with the System:: Your first steps. * Using the Configuration System:: Customizing your GNU system. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. @@ -17121,14 +17096,222 @@ instance to support new system services. * Defining Services:: Adding new service definitions. @end menu +@node Getting Started with the System +@section Getting Started + +@cindex system configuration file +@cindex configuration file, of the system +You're reading this section probably because you have just installed +Guix System (@pxref{System Installation}) and would like to know where +to go from here. If you're already familiar with GNU/Linux system +administration, the way Guix System is configured is very different from +what you're used to: you won't install a system service by running +@command{guix install}, you won't configure services by modifying files +under @file{/etc}, and you won't create user accounts by invoking +@command{useradd}; instead, all these aspects are spelled out in a +@dfn{system configuration file}. + +The first step with Guix System is thus to write the @dfn{system +configuration file}; luckily, system installation already generated one +for you and stored it under @file{/etc/config.scm}. + +@quotation Note +You can store your system configuration file anywhere you like---it +doesn't have to be at @file{/etc/config.scm}. It's a good idea to keep +it under version control, for instance in a +@uref{https://git-scm.com/book/en/, Git repository}. +@end quotation + +The @emph{entire} configuration of the system---user accounts, system +services, timezone, locale settings---is declared in this file, which +follows this template: + +@lisp +(use-modules (gnu)) +(use-package-modules @dots{}) +(use-service-modules @dots{}) + +(operating-system + (host-name @dots{}) + (timezone @dots{}) + (locale @dots{}) + (bootloader @dots{}) + (file-systems @dots{}) + (users @dots{}) + (packages @dots{}) + (services @dots{})) +@end lisp + +This configuration file is in fact a Scheme program; the first lines +pull in modules providing variables you might need in the rest of the +file---e.g., packages, services, etc. The @code{operating-system} form +declares the system configuration as a @dfn{record} with a number of +@dfn{fields}. @xref{Using the Configuration System}, to view complete +examples and learn what to put in there. + +The second step, once you have this configuration file, is to test it. +Of course, you can skip this step if you're feeling lucky---you choose! +To do that, pass your configuration file to @command{guix system vm} (no +need to be root, you can do that as a regular user): + +@example +guix system vm /etc/config.scm +@end example + +@noindent +This command returns the name of a shell script that starts a virtual +machine (VM) running the system @emph{as described in the configuration +file}: + +@example +/gnu/store/@dots{}-run-vm.sh +@end example + +@noindent +In this VM, you can log in as @code{root} with no password. That's a +good way to check that your configuration file is correct and that it +gives the expected result, without touching your system. @xref{Invoking +guix system}, for more information. + +@quotation Note +When using @command{guix system vm}, aspects tied to your hardware such +as file systems and mapped devices are overridden because they cannot be +meaningfully tested in the VM@. Other aspects such as static network +configuration (@pxref{Networking Setup, +@code{static-networking-service-type}}) are @emph{not} overridden but +they may not work inside the VM@. +@end quotation + +@cindex system instantiation +@cindex reconfiguring the system +The third step, once you're happy with your configuration, is to +@dfn{instantiate} it---make this configuration effective on your system. +To do that, run: + +@example +sudo guix system reconfigure /etc/config.scm +@end example + +@cindex upgrading system services +@cindex system services, upgrading +@noindent +This operation is @dfn{transactional}: either it succeeds and you end up +with an upgraded system, or it fails and nothing has changed. Note that +it does @emph{not} restart system services that were already running. +Thus, to upgrade those services, you have to reboot or to explicitly +restart them; for example, to restart the secure shell (SSH) daemon, you +would run: + +@example +sudo herd restart sshd +@end example + +@quotation Note +System services are managed by the Shepherd (@pxref{Jump Start,,, +shepherd, The GNU Shepherd Manual}). The @code{herd} command lets you +inspect, start, and stop services. To view the status of services, run: + +@example +sudo herd status +@end example + +To view detailed information about a given service, add its name to the +command: + +@example +sudo herd status sshd +@end example + +@xref{Services}, for more information. +@end quotation + +@cindex provenance, of the system +The system records its @dfn{provenance}---the configuration file and +channels that were used to deploy it. You can view it like so: + +@example +guix system describe +@end example + +Additionally, @command{guix system reconfigure} preserves previous +system generations, which you can list: + +@example +guix system list-generations +@end example + +@noindent +@cindex roll back, for the system +Crucially, that means that you can always @emph{roll back} to an earlier +generation should something go wrong! When you eventually reboot, +you'll notice a sub-menu in the bootloader that reads ``Old system +generations'': it's what allows you to boot @emph{an older generation of +your system}, should the latest generation be ``broken'' or otherwise +unsatisfying. You can also ``permanently'' roll back, like so: + +@example +sudo guix system roll-back +@end example + +@noindent +Alternatively, you can use @command{guix system switch-generation} to +switch to a specific generation. + +Once in a while, you'll want to delete old generations that you do not +need anymore to allow @dfn{garbage collection} to free space +(@pxref{Invoking guix gc}). For example, to remove generations older +than 4 months, run: + +@example +sudo guix system delete-generations 4m +@end example + +From there on, anytime you want to change something in the system +configuration, be it adding a user account or changing parameters of a +service, you will first update your configuration file and then run +@command{guix system reconfigure} as shown above. +@cindex upgrade, of the system +Likewise, to @emph{upgrade} system software, you first fetch an +up-to-date Guix and then reconfigure your system with that new Guix: + +@example +guix pull +sudo guix system reconfigure /etc/config.scm +@end example + +@noindent +We recommend doing that regularly so that your system includes the +latest security updates (@pxref{Security Updates}). + +@c See . +@quotation Note +@cindex sudo vs. @command{guix pull} +@command{sudo guix} runs your user's @command{guix} command and +@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. + +The difference matters here, because @command{guix pull} updates +the @command{guix} command and package definitions only for the user it is run +as. This means that if you choose to use @command{guix system reconfigure} in +root's login shell, you'll need to @command{guix pull} separately. +@end quotation + +That's it! If you're getting starting with Guix entirely, +@pxref{Getting Started}. The next sections dive in more detail into the +crux of the matter: system configuration. + @node Using the Configuration System @section Using the Configuration System +The previous section showed the overall workflow you would follow when +administering a Guix System machine (@pxref{Getting Started with the +System}). Let's now see in more detail what goes into the system +configuration file. + The operating system is configured by providing an @code{operating-system} declaration in a file that can then be passed to -the @command{guix system} command (@pxref{Invoking guix system}). A -simple setup, with the default Linux-Libre -kernel, initial RAM disk, and a couple of system services added to those +the @command{guix system} command (@pxref{Invoking guix system}), as +we've seen before. A simple setup, with the default Linux-Libre kernel, +initial RAM disk, and a couple of system services added to those provided by default looks like this: @findex operating-system @@ -17136,8 +17319,8 @@ provided by default looks like this: @include os-config-bare-bones.texi @end lisp -The configuration is declarative and hopefully mostly self-describing. -It is actually code in the Scheme programming language; the whole +The configuration is declarative. +It is code in the Scheme programming language; the whole @code{(operating-system @dots{})} expression produces a @dfn{record} with a number of @dfn{fields}. Some of the fields defined @@ -17146,16 +17329,21 @@ Others, such as @code{packages} and @code{services}, can be omitted, in which case they get a default value. @xref{operating-system Reference}, for details about all the available fields. -Below we discuss the effect of some of the most important fields, -and how to @dfn{instantiate} the operating system using -@command{guix system}. +Below we discuss the meaning of some of the most important fields. -@quotation Do not panic -@cindex Scheme programming language, getting started -Intimidated by the Scheme language or curious about it? The Cookbook -has a short section to get started that explains the fundamentals, which -you will find helpful when hacking your configuration. @xref{A Scheme -Crash Course,,, guix-cookbook, GNU Guix Cookbook}. +@quotation Troubleshooting +The configuration file is a Scheme program and you might get the syntax +or semantics wrong as you get started. Syntactic issues such as +misplaced parentheses can often be identified by reformatting your file: + +@example +guix style -f config.scm +@end example + +The Cookbook has a short section to get started with the Scheme +programming language that explains the fundamentals, which you will find +helpful when hacking your configuration. @xref{A Scheme Crash Course,,, +guix-cookbook, GNU Guix Cookbook}. @end quotation @unnumberedsubsec Bootloader @@ -17350,16 +17538,13 @@ Alternatively, the @code{modify-services} macro can be used: @unnumberedsubsec Instantiating the System +@cindex system instantiation +@cindex reconfiguring the system Assuming the @code{operating-system} declaration -is stored in the @file{my-system-config.scm} -file, the @command{guix system reconfigure my-system-config.scm} command -instantiates that configuration, and makes it the default GRUB boot -entry (@pxref{Invoking guix system}). - -@quotation Note -We recommend that you keep this @file{my-system-config.scm} file safe -and under version control to easily track changes to your configuration. -@end quotation +is stored in the @file{config.scm} +file, the @command{sudo guix system reconfigure config.scm} command +instantiates that configuration, and makes it the default boot +entry. @xref{Getting Started with the System}, for an overview. The normal way to change the system configuration is by updating this file and re-running @command{guix system reconfigure}. One should never @@ -17369,23 +17554,6 @@ fact, you must avoid that since that would not only void your warranty but also prevent you from rolling back to previous versions of your system, should you ever need to. -@cindex roll-back, of the operating system -Speaking of roll-back, each time you run @command{guix system -reconfigure}, a new @dfn{generation} of the system is created---without -modifying or deleting previous generations. Old system generations get -an entry in the bootloader boot menu, allowing you to boot them in case -something went wrong with the latest generation. Reassuring, no? The -@command{guix system list-generations} command lists the system -generations available on disk. It is also possible to roll back the -system via the commands @command{guix system roll-back} and -@command{guix system switch-generation}. - -Although the @command{guix system reconfigure} command will not modify -previous generations, you must take care when the current generation is not -the latest (e.g., after invoking @command{guix system roll-back}), since -the operation might overwrite a later generation (@pxref{Invoking guix -system}). - @unnumberedsubsec The Programming Interface At the Scheme level, the bulk of an @code{operating-system} declaration -- cgit v1.2.3 From edde7ee1bcb098663038014190e79578ed0d99db Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 21 Feb 2024 15:47:40 +0100 Subject: doc: Add “Inspecting Services” section. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Inspecting Services): New subsection. Change-Id: I71378101de913a494e0d0e93cc76434c5a70b520 --- doc/guix.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index dca91dc0c9..87fe9f803c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17536,6 +17536,61 @@ Alternatively, the @code{modify-services} macro can be used: (delete avahi-service-type)) @end lisp +@unnumberedsubsec Inspecting Services + +@cindex troubleshooting, for system services +@cindex inspecting system services +@cindex system services, inspecting +As you work on your system configuration, you might wonder why some +system service doesn't show up or why the system is not as you expected. +There are several ways to inspect and troubleshoot problems. + +@cindex dependency graph, of Shepherd services +First, you can inspect the dependency graph of Shepherd services like +so: + +@example +guix system shepherd-graph /etc/config.scm | \ + guix shell xdot -- xdot - +@end example + +This lets you visualize the Shepherd services as defined in +@file{/etc/config.scm}. Each box is a service as would be shown by +@command{sudo herd status} on the running system, and each arrow denotes +a dependency (in the sense that if service @var{A} depends on @var{B}, +then @var{B} must be started before @var{A}). + +@cindex extension graph, of services +Not all ``services'' are Shepherd services though, since Guix System +uses a broader definition of the term (@pxref{Services}). To visualize +system services and their relations at a higher level, run: + +@example +guix system extension-graph /etc/config.scm | \ + guix shell xdot -- xdot - +@end example + +This lets you view the @dfn{service extension graph}: how services +``extend'' each other, for instance by contributing to their +configuration. @xref{Service Composition}, to understand the meaning of +this graph. + +Last, you may also find it useful to inspect your system configuration +at the REPL (@pxref{Using Guix Interactively}). Here is an example +session: + +@example +$ guix repl +scheme@@(guix-user)> ,use (gnu) +scheme@@(guix-user)> (define os (load "config.scm")) +scheme@@(guix-user)> ,pp (map service-kind (operating-system-services os)) +$1 = (# + @dots{}) +@end example + +@xref{Service Reference}, to learn about the Scheme interface to +manipulate and inspect services. + @unnumberedsubsec Instantiating the System @cindex system instantiation -- cgit v1.2.3 From 364422d0ac6608e9297070b80d091a3c11c6cce7 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Sat, 2 Mar 2024 18:46:06 +0100 Subject: doc: Fix typo in “Getting Started with the System”. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Getting Started with the System): Fix typo. Change-Id: Idc52b9a4d5f5003899613595b6b275e098f6a3a8 --- doc/guix.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 87fe9f803c..176c92971f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17295,7 +17295,7 @@ as. This means that if you choose to use @command{guix system reconfigure} in root's login shell, you'll need to @command{guix pull} separately. @end quotation -That's it! If you're getting starting with Guix entirely, +That's it! If you're getting started with Guix entirely, @pxref{Getting Started}. The next sections dive in more detail into the crux of the matter: system configuration. -- cgit v1.2.3 From 01f685d56016ae529381a73daedccc1949b808ec Mon Sep 17 00:00:00 2001 From: Giacomo Leidi Date: Wed, 6 Mar 2024 21:52:42 +0100 Subject: gnu: home: dotfiles: Properly support both plain and Stow directory layouts. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes . The current implementation of the home-dotfiles-service-type contradicts the Guix manual. This patch properly implements both the plain and Stow dotfiles directory layouts. It does so by refactoring home-dotfiles-configuration adding a new packages field to support GNU Stow's users workflow and introducing a new layout field to switch between the two directory layouts. * gnu/home/services/dotfiles (home-dotfiles-configuration): Migrate to (gnu services configuration); [packages]: new field; [layout]: new field; (strip-stow-dotfile): new variable; (strip-plain-dotfile): new variable; (home-dotfiles-configuration->files): use the new fields; [directory-contents]: allow for selecting a subset of application dotfile directories; * doc/guix.texi: document the new layouts. Change-Id: I2e96037608353e360828290f055ec5271cfdfd48 Signed-off-by: Ludovic Courtès --- doc/guix.texi | 84 ++++++++++++++++++++++-------- gnu/home/services/dotfiles.scm | 115 +++++++++++++++++++++++++++++++---------- 2 files changed, 151 insertions(+), 48 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 176c92971f..858d5751bf 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -111,7 +111,7 @@ Copyright @copyright{} 2022 (@* Copyright @copyright{} 2022 John Kehayias@* Copyright @copyright{} 2022⁠–⁠2023 Bruno Victal@* Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@* -Copyright @copyright{} 2023 Giacomo Leidi@* +Copyright @copyright{} 2023-2024 Giacomo Leidi@* Copyright @copyright{} 2022 Antero Mejr@* Copyright @copyright{} 2023 Karl Hallsby@* Copyright @copyright{} 2023 Nathaniel Nicandro@* @@ -44667,17 +44667,42 @@ 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 +allowing them to point the service to their dotfiles directory 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 +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. +There are two supported dotfiles directory layouts, for now. The +@code{'plain} layout, which is structured as follows: + +@example +~$ tree -a ./dotfiles/ +dotfiles/ +├── .gitconfig +├── .gnupg +│ ├── gpg-agent.conf +│ └── gpg.conf +├── .guile +├── .config +│ ├── guix +│ │ └── channels.scm +│ └── nixpkgs +│ └── config.nix +├── .nix-channels +├── .tmux.conf +└── .vimrc +@end example + +This tree structure is installed as is to the +home directory upon @command{guix home reconfigure}. + +The @code{'stow} layout, which must +follow the layout suggested by +@uref{https://www.gnu.org/software/stow/, GNU Stow} presents an additional +application specific directory layer, just like: + @example ~$ tree -a ./dotfiles/ dotfiles/ @@ -44707,8 +44732,10 @@ dotfiles/ @end example For an informal specification please refer to the Stow manual -(@pxref{Top,,, stow, Introduction}). A suitable configuration would then -be: +(@pxref{Top,,, stow, Introduction}). This tree structure is installed following +GNU Stow's logic to the home directory upon @command{guix home reconfigure}. + +A suitable configuration with a @code{'plain} layout could be: @lisp (home-environment @@ -44716,7 +44743,7 @@ be: (services (service home-dotfiles-service-type (home-dotfiles-configuration - (directories (list "./dotfiles")))))) + (directories '("./dotfiles")))))) @end lisp The expected home directory state would then be: @@ -44743,32 +44770,47 @@ 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 +directory and have their files automatically provisioned to their home +directory, without migrating all of their dotfiles to Guix native configurations. @end defvar +@c %start of fragment + @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 +@item @code{source-directory} (default: @code{(current-source-directory)}) (type: string) +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{layout} (default: @code{'plain}) (type: symbol) +The intended layout of the specified @code{directory}. It can be either +@code{'stow} or @code{'plain}. + +@item @code{directories} (default: @code{'()}) (type: list-of-strings) +The list of dotfiles directories where @code{home-dotfiles-service-type} +will look for application dotfiles. + +@item @code{packages} (type: maybe-list-of-strings) +The names of a subset of the GNU Stow package layer directories. When provided +the @code{home-dotfiles-service-type} will only provision dotfiles from this +subset of applications. This field will be ignored if @code{layout} is set +to @code{'plain}. -@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}. +@item @code{excluded} (default: @code{'(".*~" ".*\\.swp" "\\.git" "\\.gitignore")}) (type: list-of-strings) +The list of file patterns @code{home-dotfiles-service-type} will exclude +while visiting each one of the @code{directories}. @end table @end deftp + +@c %end of fragment + @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 diff --git a/gnu/home/services/dotfiles.scm b/gnu/home/services/dotfiles.scm index 6a740c42ce..823bdb03fb 100644 --- a/gnu/home/services/dotfiles.scm +++ b/gnu/home/services/dotfiles.scm @@ -20,17 +20,25 @@ (define-module (gnu home services dotfiles) #:use-module (gnu home services) #:use-module (gnu services) + #:use-module (gnu services configuration) #:autoload (guix build utils) (find-files) + #:use-module (guix diagnostics) #:use-module (guix gexp) - #:use-module (guix records) + #:use-module (guix i18n) #:use-module ((guix utils) #:select (current-source-directory)) #:use-module (srfi srfi-1) #:use-module (ice-9 ftw) + #:use-module (ice-9 match) #:use-module (ice-9 regex) #:export (home-dotfiles-service-type + home-dotfiles-configuration->files + home-dotfiles-configuration home-dotfiles-configuration? + home-dotfiles-configuration-fields + home-dotfiles-configuration-layout home-dotfiles-configuration-source-directory + home-dotfiles-configuration-packages home-dotfiles-configuration-directories home-dotfiles-configuration-excluded)) @@ -40,26 +48,64 @@ (define %home-dotfiles-excluded "\\.git" "\\.gitignore")) -(define-record-type* - home-dotfiles-configuration make-home-dotfiles-configuration - home-dotfiles-configuration? - (source-directory home-dotfiles-configuration-source-directory - (default (current-source-directory)) - (innate)) - (directories home-dotfiles-configuration-directories ;list of strings - (default '())) - (excluded home-dotfiles-configuration-excluded ;list of strings - (default %home-dotfiles-excluded))) - -(define (import-dotfiles directory files) +(define %home-dotfiles-layouts + '(plain stow)) + +(define (sanitize-layout value) + (if (member value %home-dotfiles-layouts) + value + (raise + (formatted-message + (G_ "layout field of home-dotfiles-configuration should be either 'plain +or 'stow, but ~a was found.") + value)))) + +(define list-of-strings? + (list-of string?)) + +(define-maybe list-of-strings) + +(define-configuration/no-serialization home-dotfiles-configuration + (source-directory + (string (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.") + (layout + (symbol 'plain) + "The intended layout of the specified @code{directory}. It can be either +@code{'stow} or @code{'plain}." + (sanitizer sanitize-layout)) + (directories + (list-of-strings '()) + "The list of dotfiles directories where @code{home-dotfiles-service-type} +will look for application dotfiles.") + (packages + (maybe-list-of-strings) + "The names of a subset of the GNU Stow package layer directories. When provided +the @code{home-dotfiles-service-type} will only provision dotfiles from this +subset of applications. This field will be ignored if @code{layout} is set +to @code{'plain}.") + (excluded + (list-of-strings %home-dotfiles-excluded) + "The list of file patterns @code{home-dotfiles-service-type} will exclude +while visiting @code{directory}.")) + +(define (strip-stow-dotfile file-name directory) + (let ((dotfile-name (string-drop file-name (1+ (string-length directory))))) + (match (string-split dotfile-name #\/) + ((package parts ...) + (string-join parts "/"))))) + +(define (strip-plain-dotfile file-name directory) + (string-drop file-name (+ 1 (string-length directory)))) + +(define (import-dotfiles directory files strip) "Return a list of objects compatible with @code{home-files-service-type}'s value. Each object is a pair where the first element is the relative path of a file and the second is a gexp representing the file content. Objects are generated by recursively visiting DIRECTORY and mapping its contents to the user's home directory, excluding files that match any of the patterns in EXCLUDED." - (define (strip file) - (string-drop file (+ 1 (string-length directory)))) - (define (format file) ;; Remove from FILE characters that cannot be used in the store. (string-append @@ -73,7 +119,7 @@ (define (format file) file))) (map (lambda (file) - (let ((stripped (strip file))) + (let ((stripped (strip file directory))) (list stripped (local-file file (format stripped) #:recursive? #t)))) @@ -81,18 +127,25 @@ (define (format file) (define (home-dotfiles-configuration->files config) "Return a list of objects compatible with @code{home-files-service-type}'s -value, generated following GNU Stow's algorithm for each of the -directories in CONFIG, excluding files that match any of the patterns configured." +value, excluding files that match any of the patterns configured." + (define stow? (eq? (home-dotfiles-configuration-layout config) 'stow)) (define excluded (home-dotfiles-configuration-excluded config)) (define exclusion-rx (make-regexp (string-append "^.*(" (string-join excluded "|") ")$"))) - (define (directory-contents directory) - (find-files directory - (lambda (file stat) - (not (regexp-exec exclusion-rx - (basename file)))))) + (define* (directory-contents directory #:key (packages #f)) + (define (filter-files directory) + (find-files directory + (lambda (file stat) + (not (regexp-exec exclusion-rx + (basename file)))))) + (if (and stow? packages (maybe-value-set? packages)) + (append-map filter-files + (map (lambda (pkg) + (string-append directory "/" pkg)) + packages)) + (filter-files directory))) (define (resolve directory) ;; Resolve DIRECTORY relative to the 'source-directory' field of CONFIG. @@ -103,15 +156,23 @@ (define (resolve directory) (append-map (lambda (directory) (let* ((directory (resolve directory)) - (contents (directory-contents directory))) - (import-dotfiles directory contents))) + (packages + (home-dotfiles-configuration-packages config)) + (contents + (directory-contents directory + #:packages packages)) + (strip + (if stow? strip-stow-dotfile strip-plain-dotfile))) + (import-dotfiles directory contents strip))) (home-dotfiles-configuration-directories config))) (define-public home-dotfiles-service-type (service-type (name 'home-dotfiles) (extensions (list (service-extension home-files-service-type - home-dotfiles-configuration->files))) + (lambda (config) + (when config + (home-dotfiles-configuration->files config)))))) (default-value (home-dotfiles-configuration)) (description "Files that will be put in the user's home directory following GNU Stow's algorithm, and further processed during activation."))) -- cgit v1.2.3 From 3bd795bc5736a81adc586da80c67107dd8f64384 Mon Sep 17 00:00:00 2001 From: Fabio Natali Date: Sat, 2 Mar 2024 10:25:52 +0000 Subject: doc: Fix section on LUKS support. Only LUKS1 is supported in Guix at the time of this commit. Contrarily to what reported in previous versions of this section, LUKS2 is not supported. * doc/guix.texi (Keyboard Layout, Networking, and Partitioning)[Disk Partitioning]: Fix section on LUKS support. Signed-off-by: Christopher Baines Change-Id: Ia670963178810174d3ea4585c537defbaaeb0f25 --- doc/guix.texi | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 858d5751bf..796ac0028f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2728,20 +2728,20 @@ the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html, @code{man cryptsetup}} for more information). @quotation Warning -Note that GRUB can unlock LUKS2 devices since version 2.06, but only -supports the PBKDF2 key derivation function, which is not the default -for @command{cryptsetup luksFormat}. You can check which key derivation -function is being used by a device by running @command{cryptsetup -luksDump @var{device}}, and looking for the PBKDF field of your -keyslots. +While efforts are in progress to extend support to LUKS2, please note +that Guix only supports devices of type LUKS1 at the moment. You can +verify that your existing LUKS device is of the right type by running +@command{cryptsetup luksDump @var{device}}. Alternatively, you can +create a new LUKS1 device with @command{cryptsetup luksFormat --type +luks1 @var{device}}. @end quotation Assuming you want to store the root partition on @file{/dev/sda2}, the -command sequence to format it as a LUKS2 partition would be along these +command sequence to format it as a LUKS1 partition would be along these lines: @example -cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 /dev/sda2 +cryptsetup luksFormat --type luks1 /dev/sda2 cryptsetup open /dev/sda2 my-partition mkfs.ext4 -L my-root /dev/mapper/my-partition @end example -- cgit v1.2.3 From 999bfa0d543c539e4554797deaf2f447dddf3796 Mon Sep 17 00:00:00 2001 From: Luis Felipe Date: Fri, 15 Mar 2024 14:34:22 -0500 Subject: doc: build: Update paths to style sheets. The Guix website style sheets are now organized in themes. This change makes the documentation builder use the resources provided by a theme called "initial" (See https://issues.guix.gnu.org/69783). * doc/build.scm (syntax-highlighted-html): Update path to CSS. (html-manual-indexes): Likewise. (stylized-html): Likewise, and update path to language picker image. Change-Id: Ib2d51fcfdec42ad827add1ead1cfee4c9c4e65b7 Signed-off-by: Florian Pelz --- doc/build.scm | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/build.scm b/doc/build.scm index 2cd57b4a92..9ab2ca32d2 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -365,7 +365,7 @@ (define* (syntax-highlighted-html input #:languages languages)) (syntax-css-url - "/static/base/css/code.css")) + "/themes/initial/css/code.css")) "Return a derivation called NAME that processes all the HTML files in INPUT to (1) add them a link to SYNTAX-CSS-URL, and (2) highlight the syntax of all its 
 blocks (as produced by 'makeinfo --html')."
@@ -624,7 +624,7 @@ (define* (stylized-html source input
                         #:key
                         (languages %languages)
                         (manual %manual)
-                        (manual-css-url "/static/base/css/manual.css"))
+                        (manual-css-url "/themes/initial/css/manual.css"))
   "Process all the HTML files in INPUT; add them MANUAL-CSS-URL as a