diff options
Diffstat (limited to 'doc/guix-cookbook.texi')
| -rw-r--r-- | doc/guix-cookbook.texi | 137 |
1 files changed, 120 insertions, 17 deletions
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 477b7e3dff..82700a48ad 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -11,6 +11,8 @@ Copyright @copyright{} 2019 Ricardo Wurmus@* Copyright @copyright{} 2019 Efraim Flashner@* Copyright @copyright{} 2019 Pierre Neidhardt@* +Copyright @copyright{} 2020 Oleg Pykhalov@* +Copyright @copyright{} 2020 Matthew Brooks@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -579,7 +581,7 @@ packages. Guix makes it possible to streamline the process by adding as many ``package declaration directories'' as you want. -Create a directory, say @samp{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} +Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} environment variable: @example @@ -849,7 +851,7 @@ version when packaging programs for a specific commit. @subsubsection Snippets Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching -the source. They are a Guix-y alternative to the traditional @samp{.patch} files. +the source. They are a Guix-y alternative to the traditional @file{.patch} files. Because of the quote, the code in only evaluated when passed to the Guix daemon for building. There can be as many snippets as needed. @@ -953,7 +955,7 @@ $ make CC=gcc prefix=/gnu/store/...-<out> This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage global variable pointing to the destination directory in the store (something like -@samp{/gnu/store/...-my-libgit2-20180408}). +@file{/gnu/store/...-my-libgit2-20180408}). Similarly, it's possible to set the configure flags: @@ -1078,7 +1080,7 @@ mechanism of passing code around two running processes is called @uref{https://a @subsubsection Utility functions When customizing @code{phases}, we often need to write code that mimics the -equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.) commonly used during +equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during regular ``Unix-style'' installations. Some like @code{chmod} are native to Guile. @@ -1319,7 +1321,9 @@ chapter is to demonstrate some advanced configuration concepts. reference. @menu -* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. +* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. +* Customizing a Window Manager:: Handle customization of a Window manager on Guix System. +* Setting up a bind mount:: Setting up a bind mount in the file-systems definition. @end menu @node Customizing the Kernel @@ -1562,6 +1566,105 @@ likely that you'll need to modify the initrd on a machine using a custom kernel, since certain modules which are expected to be built may not be available for inclusion into the initrd. +@node Customizing a Window Manager +@section Customizing a Window Manager +@cindex wm + +@node StumpWM +@subsection StumpWM +@cindex stumpwm + +You could install StumpWM with a Guix system by adding +@code{stumpwm-checkout} and optionally @code{`(,stumpwm-checkout "lib")} +packages to a system configuration file, e.g.@: @file{/etc/config.scm}. + +An example configuration can look like this: + +@lisp +(use-modules (gnu)) +(use-package-modules wm) + +(operating-system + ;; … + (packages (append (list sbcl stumpwm-checkout `(,stumpwm-checkout "lib")) + %base-packages))) +@end lisp + +@cindex stumpwm fonts +By default StumpWM uses X11 fonts, which could be small or pixelated on +your system. You could fix this by installing StumpWM contrib Lisp +module @code{sbcl-stumpwm-ttf-fonts}, adding it to Guix system packages: + +@lisp +(use-modules (gnu)) +(use-package-modules fonts wm) + +(operating-system + ;; … + (packages (append (list sbcl stumpwm-checkout `(,stumpwm-checkout "lib")) + sbcl-stumpwm-ttf-fonts font-dejavu %base-packages))) +@end lisp + +Then you need to add the following code to a StumpWM configuration file +@file{~/.stumpwm.d/init.lisp}: + +@lisp +(require :ttf-fonts) +(setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/")) +(setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp")) +(xft:cache-fonts) +(set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11)) +@end lisp + +@node Setting up a bind mount +@section Setting up a bind mount + +To bind mount a file system, one must first set up some definitions +before the @code{operating-system} section of the system definition. In +this example we will bind mount a folder from a spinning disk drive to +@file{/tmp}, to save wear and tear on the primary SSD, without +dedicating an entire partition to be mounted as @file{/tmp}. + +First, the source drive that hosts the folder we wish to bind mount +should be defined, so that the bind mount can depend on it. + +@lisp +(define source-drive ;; "source-drive" can be named anything you want. + (file-system + (device (uuid "UUID goes here")) + (mount-point "/path-to-spinning-disk-goes-here") + (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive. +@end lisp + +The source folder must also be defined, so that guix will know it's not +a regular block device, but a folder. +@lisp +(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name. +@end lisp + +Finally, inside the @code{file-systems} definition, we must add the +mount itself. + +@lisp +(file-systems (cons* + + ...<other drives omitted for clarity>... + + source-drive ;; Must match the name you gave the source drive in the earlier definition. + + (file-system + (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition. + (mount-point "/tmp") + (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none" + (flags '(bind-mount)) + (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive. + ) + + ...<other drives omitted for clarity>... + + )) +@end lisp + @c ********************************************************************* @node Advanced package management @chapter Advanced package management @@ -1688,8 +1791,8 @@ where we will store our profiles in the rest of this article. Placing all your profiles in a single directory, with each profile getting its own sub-directory, is somewhat cleaner. This way, each sub-directory will -contain all the symlinks for precisely one profile. Besides, "looping over -profiles" becomes obvious from any programming language (e.g. a shell script) by +contain all the symlinks for precisely one profile. Besides, ``looping over +profiles'' becomes obvious from any programming language (e.g.@: a shell script) by simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}. Note that it's also possible to loop over the output of @@ -1698,9 +1801,9 @@ Note that it's also possible to loop over the output of guix package --list-profiles @end example -although you'll probably have to filter out @samp{~/.config/guix/current}. +although you'll probably have to filter out @file{~/.config/guix/current}. -To enable all profiles on login, add this to your @samp{~/.bash_profile} (or similar): +To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar): @example for i in $GUIX_EXTRA_PROFILES/*; do @@ -1714,8 +1817,8 @@ done @end example Note to Guix System users: the above reflects how your default profile -@samp{~/.guix-profile} is activated from @samp{/etc/profile}, that latter being loaded by -@samp{~/.bashrc} by default. +@file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by +@file{~/.bashrc} by default. You can obviously choose to only enable a subset of them: @@ -1758,8 +1861,8 @@ guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/ To upgrade all profiles, it's easy enough to loop over them. For instance, assuming your manifest specifications are stored in -@samp{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name -of the profile (e.g. "project1"), you could do the following in Bourne shell: +@file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name +of the profile (e.g.@: "project1"), you could do the following in Bourne shell: @example for profile in "$GUIX_EXTRA_PROFILES"/*; do @@ -1818,12 +1921,12 @@ The same is true for @samp{INFOPATH} (you can install @samp{info-reader}), @node Default profile @subsection Default profile -What about the default profile that Guix keeps in @samp{~/.guix-profile}? +What about the default profile that Guix keeps in @file{~/.guix-profile}? You can assign it the role you want. Typically you would install the manifest of the packages you want to use all the time. -Alternatively, you could keep it "manifest-less" for throw-away packages +Alternatively, you could keep it ``manifest-less'' for throw-away packages that you would just use for a couple of days. This way makes it convenient to run @@ -1854,7 +1957,7 @@ Manifests come with multiple benefits. In particular, they ease maintenance: @itemize @item When a profile is set up from a manifest, the manifest itself is -self-sufficient to keep a "package listing" around and reinstall the profile +self-sufficient to keep a ``package listing'' around and reinstall the profile later or on a different system. For ad-hoc profiles, we would need to generate a manifest specification manually and maintain the package versions for the packages that don't use the default version. @@ -1891,7 +1994,7 @@ They can be manipulated in Scheme and passed to the various Guix @uref{https://e It's important to understand that while manifests can be used to declare profiles, they are not strictly equivalent: profiles have the side effect that -they "pin" packages in the store, which prevents them from being +they ``pin'' packages in the store, which prevents them from being garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual}) and ensures that they will still be available at any point in the future. |