From b5eb901ab508e13a10d8c11fe0c9d0d06dddce96 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Mon, 7 Sep 2020 23:12:27 +0200 Subject: Remove (guix json) and require Guile-JSON 4.3.0+. This is a followup to 4071879c86d059ee087c8986915ea72b8c742b72. * guix/json.scm: Remove. * Makefile.am (MODULES): Adjust accordingly. * m4/guix.m4 (GUIX_CHECK_GUILE_JSON): Check for 'define-json-mapping'. * doc/guix.texi (Requirements): Require Guile-JSON 4.3.0+. * guix/ci.scm, guix/cve.scm, guix/import/cpan.scm, guix/import/crate.scm, guix/swh.scm: Remove (guix json) import. * guix/import/gem.scm, guix/import/pypi.scm: Likewise, and import (json). * guix/self.scm (specification->package): Switch to GUILE-JSON-4. * guix/git-download.scm (git-fetch): Likewise. --- doc/guix.texi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index f224e356bc..4e9e5581c3 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -790,7 +790,8 @@ or later; @c FIXME: Specify a version number once a release has been made. @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 or later; -@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} 3.x; +@item @uref{https://savannah.nongnu.org/projects/guile-json/, +Guile-JSON} 4.3.0 or later; @item @url{https://www.gnu.org/software/make/, GNU Make}. @end itemize -- cgit v1.2.3 From 4678767a160f26052a2adf487aee0610040ddc2e Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Tue, 8 Sep 2020 09:11:36 +0200 Subject: doc: Tweak .texi to avoid po4a-translate infinite loop. * doc/guix.texi (Requirements): Keep @uref on one line as splitting it would lead po4a-translate to enter an infinite loop. --- doc/guix.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 4e9e5581c3..1d6782e6fa 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -790,8 +790,8 @@ or later; @c FIXME: Specify a version number once a release has been made. @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 or later; -@item @uref{https://savannah.nongnu.org/projects/guile-json/, -Guile-JSON} 4.3.0 or later; +@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} +4.3.0 or later; @item @url{https://www.gnu.org/software/make/, GNU Make}. @end itemize -- cgit v1.2.3 From 191e79dab2f90fff1f308bfaa06bbf25775bfc86 Mon Sep 17 00:00:00 2001 From: Joshua Branson Date: Tue, 8 Sep 2020 10:31:26 -0400 Subject: doc: cookbook: Adding a section "Running Guix on a Linode Server" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix-cookbook.texi (Running Guix on a Linode Server): I added a section that explains how to run guix on a linode server. Thanks Chris Webber! Signed-off-by: Ludovic Courtès --- doc/guix-cookbook.texi | 242 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) (limited to 'doc') diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 8a9d075a3d..a783c0ae4c 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -16,6 +16,7 @@ Copyright @copyright{} 2020 Matthew Brooks@* Copyright @copyright{} 2020 Marcin Karpezo@* Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 André Batista@* +Copyright @copyright{} 2020 Christopher Lemmer Webber Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1348,6 +1349,7 @@ reference. * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. +* Running Guix on a Linode Server:: Running Guix on a Linode Server * Setting up a bind mount:: Setting up a bind mount in the file-systems definition. * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor. @end menu @@ -1760,6 +1762,246 @@ your screen but not suspend it, it's a good idea to notify xss-lock about this s confusion occurs. This can be done by executing @code{xset s activate} immediately before you execute slock. +@node Running Guix on a Linode Server +@section Running Guix on a Linode Server +@cindex linode, Linode + +To run Guix on a server hosted by @uref{https://www.linode.com, Linode}, +start with a recommended Debian server. We recommend using the default +distro as a way to bootstrap Guix. Create your SSH keys. + +@example +ssh-keygen +@end example + +Be sure to add your SSH key for easy login to the remote server. +This is trivially done via Linode's graphical interface for adding +SSH keys. Go to your profile and click add SSH Key. +Copy into it the output of: + +@example +cat ~/.ssh/_rsa.pub +@end example + +Power the Linode down. In the Linode's Disks/Configurations tab, resize +the Debian disk to be smaller. 30 GB is recommended. + +In the Linode settings, "Add a disk", with the following: +@itemize @bullet +@item +Label: "Guix" + +@item +Filesystem: ext4 + +@item +Set it to the remaining size +@end itemize + +On the "configuration" field that comes with the default image, press +"..." and select "Edit", then on that menu add to @file{/dev/sdc} the "Guix" +label. + +Now "Add a Configuration", with the following: +@itemize @bullet +@item +Label: Guix + +@item +Kernel:GRUB 2 (it's at the bottom! This step is @b{IMPORTANT!}) + +@item +Block device assignment: + +@item +@file{/dev/sda}: Guix + +@item +@file{/dev/sdb}: swap + +@item +Root device: @file{/dev/sda} + +@item +Turn off all the filesystem/boot helpers +@end itemize + +Now power it back up, picking the Debian configuration. Once it's +booted up, ssh in your server via @code{ssh +root@@@var{}}. (You can find your server IP address in +your Linode Summary section.) Now you can run the "install guix from +@pxref{Binary Installation,,, guix, GNU Guix}" steps: + +@example +sudo apt-get install gpg +wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 -qO - | gpg --import - +wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh +chmod +x guix-install.sh +./guix-install.sh +guix pull +@end example + +Now it's time to write out a config for the server. The key information +is below. Save the resulting file as @file{guix-config.scm}. + +@lisp +(use-modules (gnu) + (guix modules)) +(use-service-modules networking + ssh) +(use-package-modules admin + certs + package-management + ssh + tls) + +(operating-system + (host-name "my-server") + (timezone "America/New_York") + (locale "en_US.UTF-8") + ;; This goofy code will generate the grub.cfg + ;; without installing the grub bootloader on disk. + (bootloader (bootloader-configuration + (bootloader + (bootloader + (inherit grub-bootloader) + (installer #~(const #t)))))) + (file-systems (cons (file-system + (device "/dev/sda") + (mount-point "/") + (type "ext4")) + %base-file-systems)) + + + (swap-devices (list "/dev/sdb")) + + + (initrd-modules (cons "virtio_scsi" ; Needed to find the disk + %base-initrd-modules)) + + (users (cons (user-account + (name "janedoe") + (group "users") + ;; Adding the account to the "wheel" group + ;; makes it a sudoer. + (supplementary-groups '("wheel")) + (home-directory "/home/janedoe")) + %base-user-accounts)) + + (packages (cons* nss-certs ;for HTTPS access + openssh-sans-x + %base-packages)) + + (services (cons* + (service dhcp-client-service-type) + (service openssh-service-type + (openssh-configuration + (openssh openssh-sans-x) + (password-authentication? #f) + (authorized-keys + `(("janedoe" ,(local-file "janedoe_rsa.pub")) + ("root" ,(local-file "janedoe_rsa.pub")))))) + %base-services))) +@end lisp + +Replace the following fields in the above configuration: +@lisp +(host-name "my-server") ; replace with your server name +; if you chose a linode server outside the U.S., then +; use tzselect to find a correct timezone string +(timezone "America/New_York") ; if needed replace timezone +(name "janedoe") ; replace with your username +("janedoe" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key +("root" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key +@end lisp + +The last line in the above example lets you log into the server as root +and set the initial root password. After you have done this, you may +delete that line from your configuration and reconfigure to prevent root +login. + +Save your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as +@file{@var{}_rsa.pub} and your +@file{guix-config.scm} in the same directory. In a new terminal run +these commands. + +@example +sftp root@@ +put /home//ssh/id_rsa.pub . +put /path/to/linode/guix-config.scm . +@end example + +In your first terminal, mount the guix drive: + +@example +mkdir /mnt/guix +mount /dev/sdc /mnt/guix +@end example + +Due to the way we set things up above, we do not install GRUB +completely. Instead we install only our grub configuration file. So we +need to copy over some of the other GRUB stuff that is already there: + +@example +mkdir -p /mnt/guix/boot/grub +cp -r /boot/grub/* /mnt/guix/boot/grub/ +@end example + +Now initialize the Guix installation: + +@example +guix system init guix-config.scm /mnt/guix +@end example + +Ok, power it down! +Now from the Linode console, select boot and select "Guix". + +Once it boots, you should be able to log in via SSH! (The server config +will have changed though.) You may encounter an error like: + +@example +$ ssh root@@ +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! +Someone could be eavesdropping on you right now (man-in-the-middle attack)! +It is also possible that a host key has just been changed. +The fingerprint for the ECDSA key sent by the remote host is +SHA256:0B+wp33w57AnKQuHCvQP0+ZdKaqYrI/kyU7CfVbS7R4. +Please contact your system administrator. +Add correct host key in /home/joshua/.ssh/known_hosts to get rid of this message. +Offending ECDSA key in /home/joshua/.ssh/known_hosts:3 +ECDSA host key for 198.58.98.76 has changed and you have requested strict checking. +Host key verification failed. +@end example + +Either delete @file{~/.ssh/known_hosts} file, or delete the offending line +starting with your server IP address. + +Be sure to set your password and root's password. + +@example +ssh root@@ +passwd ; for the root password +passwd ; for the user password +@end example + +You may not be able to run the above commands at this point. If you +have issues remotely logging into your linode box via SSH, then you may +still need to set your root and user password initially by clicking on +the ``Launch Console'' option in your linode. Choose the ``Glish'' +instead of ``Weblish''. Now you should be able to ssh into the machine. + +Horray! At this point you can shut down the server, delete the +Debian disk, and resize the Guix to the rest of the size. +Congratulations! + +By the way, if you save it as a disk image right at this point, you'll +have an easy time spinning up new Guix images! You may need to +down-size the Guix image to 6144MB, to save it as an image. Then you +can resize it again to the max size. + @node Setting up a bind mount @section Setting up a bind mount -- cgit v1.2.3 From bcfe0f0c1e9a2b91049d7c6c591c7f0c6a002c14 Mon Sep 17 00:00:00 2001 From: Alexey Abramov Date: Tue, 8 Sep 2020 15:53:42 +0200 Subject: services: dovecot: Use modules via symlink to system profile. * gnu/services/mail.scm (%dovecot-activation): Link the location with multiple plugins (dovecot-pigeonhole, etc), to a place where dovecot can find them. * gnu/services/mail.scm (dovecot-configuration): Use the symlink. Signed-off-by: Tobias Geerinckx-Rice --- doc/guix.texi | 3 ++- gnu/services/mail.scm | 13 ++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 1d6782e6fa..cfd90471f7 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18615,7 +18615,8 @@ Defaults to @samp{"/var/run/dovecot/auth-userdb"}. @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir Directory where to look up mail plugins. -Defaults to @samp{"/usr/lib/dovecot"}. +Defaults to @samp{"/etc/dovecot/modules"}, a union of all enabled mail +plugins. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins diff --git a/gnu/services/mail.scm b/gnu/services/mail.scm index cfcaf4601b..c3ecbb394b 100644 --- a/gnu/services/mail.scm +++ b/gnu/services/mail.scm @@ -1044,8 +1044,10 @@ directories are prefixed with the chroot directory, append \"/.\" to This is used by imap (for shared users) and lda.") (mail-plugin-dir - (file-name "/usr/lib/dovecot") - "Directory where to look up mail plugins.") + (file-name "/etc/dovecot/modules") + "Directory where to look up mail plugins. +Defaults to @samp{\"/etc/dovecot/modules\"}, a union of all enabled mail +plugins.") (mail-plugins (space-separated-string-list '()) @@ -1519,13 +1521,18 @@ greyed out, instead of only later giving \"not selectable\" popup error. (else (format (current-error-port) "Failed to create public key at ~a.\n" public-key))))) - (let ((user (getpwnam "dovecot"))) + (let ((user (getpwnam "dovecot")) + ;; This is Dovecot's term for the base directory for + ;; dynamically loadable modules. It supports only one. + (moduledir "/etc/dovecot/modules")) (mkdir-p/perms "/var/run/dovecot" user #o755) (mkdir-p/perms "/var/lib/dovecot" user #o755) (mkdir-p/perms "/etc/dovecot" user #o755) (copy-file #$(plain-file "dovecot.conf" config-str) "/etc/dovecot/dovecot.conf") (mkdir-p/perms "/etc/dovecot/private" user #o700) + (unless (file-exists? moduledir) + (symlink "/run/current-system/profile/lib/dovecot" moduledir)) (create-self-signed-certificate-if-absent #:private-key "/etc/dovecot/private/default.pem" #:public-key "/etc/dovecot/default.pem" -- cgit v1.2.3 From bba0533115df9a31b696ee3782c8054174b955b1 Mon Sep 17 00:00:00 2001 From: Jelle Licht Date: Mon, 25 May 2020 20:58:46 +0200 Subject: services: php-fpm: Add 'php-ini-file' configuration. * gnu/services/web.scm: ()[php-ini-file]: New record field. (php-fpm-shepherd-service): Use it. * doc/guix.texi (Web Services): Document it. --- doc/guix.texi | 25 +++++++++++++++++++++++++ gnu/services/web.scm | 10 ++++++++-- 2 files changed, 33 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index cfd90471f7..bad2d36e42 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -22191,6 +22191,31 @@ Can be set to @code{#f} to disable logging. @item @code{file} (default @code{#f}) An optional override of the whole configuration. You can use the @code{mixed-text-file} function or an absolute filepath for it. +@item @code{php-ini-file} (default @code{#f}) +An optional override of the default php settings. +It may be any ``file-like'' object (@pxref{G-Expressions, file-like objects}). +You can use the @code{mixed-text-file} function or an absolute filepath for it. + +For local development it is useful to set a higher timeout and memory +limit for spawned php processes. This be accomplished with the +following operating system configuration snippet: +@lisp +(define %local-php-ini + (plain-file "php.ini" + "memory_limit = 2G +max_execution_time = 1800")) + +(operating-system + ;; @dots{} + (services (cons (service php-fpm-service-type + (php-fpm-configuration + (php-ini-file %local-php-ini))) + %base-services))) +@end lisp + +Consult the @url{https://www.php.net/manual/en/ini.core.php,core php.ini +directives} for comprehensive documentation on the acceptable +@file{php.ini} directives. @end table @end deftp diff --git a/gnu/services/web.scm b/gnu/services/web.scm index d11a1c0545..c8ffc19d83 100644 --- a/gnu/services/web.scm +++ b/gnu/services/web.scm @@ -152,6 +152,7 @@ php-fpm-configuration-timezone php-fpm-configuration-workers-log-file php-fpm-configuration-file + php-fpm-configuration-php-ini-file php-fpm-dynamic-process-manager-configuration make-php-fpm-dynamic-process-manager-configuration @@ -856,6 +857,8 @@ of index files." (version-major (package-version php)) "-fpm.www.log"))) (file php-fpm-configuration-file ;#f | file-like + (default #f)) + (php-ini-file php-fpm-configuration-php-ini-file ;#f | file-like (default #f))) (define-record-type* @@ -962,7 +965,7 @@ of index files." (match-lambda (($ php socket user group socket-user socket-group pid-file log-file pm display-errors - timezone workers-log-file file) + timezone workers-log-file file php-ini-file) (list (shepherd-service (provision '(php-fpm)) (documentation "Run the php-fpm daemon.") @@ -973,7 +976,10 @@ of index files." #$(or file (default-php-fpm-config socket user group socket-user socket-group pid-file log-file - pm display-errors timezone workers-log-file))) + pm display-errors timezone workers-log-file)) + #$@(if php-ini-file + `("-c" ,php-ini-file) + '())) #:pid-file #$pid-file)) (stop #~(make-kill-destructor))))))) -- cgit v1.2.3 From 7a68d3ccadc7391b97e94582301f3dfaf51a3179 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Tue, 8 Sep 2020 14:59:01 +0200 Subject: doc: Distinguish the "nar bundle" format from "nar". * doc/guix.texi (Invoking guix archive): Introduce the term "nar bundle" and clarify what the output of "guix archive --export" really is. * guix/nar.scm (restore-one-item, restore-file-set): Use the term "nar bundle" in docstrings. --- doc/guix.texi | 12 +++++++++++- guix/nar.scm | 15 ++++++++------- 2 files changed, 19 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index bad2d36e42..db2013c16b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -4990,7 +4990,13 @@ what you should use in this case (@pxref{Invoking guix copy}). @cindex nar, archive format @cindex normalized archive (nar) -Archives are stored in the ``normalized archive'' or ``nar'' format, which is +@cindex nar bundle, archive format +Each store item is written in the @dfn{normalized archive} or @dfn{nar} +format (described below), and the output of @command{guix archive +--export} (and input of @command{guix archive --import}) is a @dfn{nar +bundle}. + +The nar format is comparable in spirit to `tar', but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions @@ -5000,6 +5006,10 @@ entries are stored always follows the order of file names according to the C locale collation order. This makes archive production fully deterministic. +That nar bundle format is essentially the concatenation of zero or more +nars along with metadata for each store item it contains: its file name, +references, corresponding derivation, and a digital signature. + When exporting, the daemon digitally signs the contents of the archive, and that digital signature is appended. When importing, the daemon verifies the signature and rejects the import in case of an invalid diff --git a/guix/nar.scm b/guix/nar.scm index 6bb2ea5b96..a23af2e5de 100644 --- a/guix/nar.scm +++ b/guix/nar.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2012, 2013, 2014, 2015, 2016, 2018, 2019 Ludovic Courtès +;;; Copyright © 2012, 2013, 2014, 2015, 2016, 2018, 2019, 2020 Ludovic Courtès ;;; Copyright © 2014 Mark H Weaver ;;; ;;; This file is part of GNU Guix. @@ -156,7 +156,8 @@ protected from GC." (define* (restore-one-item port #:key acl (verify-signature? #t) (lock? #t) (log-port (current-error-port))) - "Restore one store item from PORT; return its file name on success." + "Restore one store item of a nar bundle read from PORT; return its file name +on success." (define (assert-valid-signature signature hash file) ;; Bail out if SIGNATURE, which must be a string as produced by @@ -251,11 +252,11 @@ a signature")) (define* (restore-file-set port #:key (verify-signature? #t) (lock? #t) (log-port (current-error-port))) - "Restore the file set read from PORT to the store. The format of the data -on PORT must be as created by 'export-paths'---i.e., a series of Nar-formatted -archives with interspersed meta-data joining them together, possibly with a -digital signature at the end. Log progress to LOG-PORT. Return the list of -files restored. + "Restore the file set (\"nar bundle\") read from PORT to the store. The +format of the data on PORT must be as created by 'export-paths'---i.e., a +series of Nar-formatted archives with interspersed meta-data joining them +together, possibly with a digital signature at the end. Log progress to +LOG-PORT. Return the list of files restored. When LOCK? is #f, assume locks for the files to be restored are already held. This is the case when the daemon calls a build hook. -- cgit v1.2.3 From d9d88c2ff0d367599d0a851ccf9377c4e21079d6 Mon Sep 17 00:00:00 2001 From: Tobias Geerinckx-Rice Date: Fri, 11 Sep 2020 22:19:02 +0200 Subject: Revert "services: dovecot: Use modules via symlink to system profile." This reverts commit bcfe0f0c1e9a2b91049d7c6c591c7f0c6a002c14 for now. It breaks most current use(r)s of the Dovecot service and needs to be combined with an extra modules configuration field of some kind. See . --- doc/guix.texi | 3 +-- gnu/services/mail.scm | 13 +++---------- 2 files changed, 4 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index db2013c16b..a6e14ea177 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18625,8 +18625,7 @@ Defaults to @samp{"/var/run/dovecot/auth-userdb"}. @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir Directory where to look up mail plugins. -Defaults to @samp{"/etc/dovecot/modules"}, a union of all enabled mail -plugins. +Defaults to @samp{"/usr/lib/dovecot"}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins diff --git a/gnu/services/mail.scm b/gnu/services/mail.scm index 291a2db8e1..71fa975b5d 100644 --- a/gnu/services/mail.scm +++ b/gnu/services/mail.scm @@ -988,10 +988,8 @@ directories are prefixed with the chroot directory, append \"/.\" to This is used by imap (for shared users) and lda.") (mail-plugin-dir - (file-name "/etc/dovecot/modules") - "Directory where to look up mail plugins. -Defaults to @samp{\"/etc/dovecot/modules\"}, a union of all enabled mail -plugins.") + (file-name "/usr/lib/dovecot") + "Directory where to look up mail plugins.") (mail-plugins (space-separated-string-list '()) @@ -1523,18 +1521,13 @@ greyed out, instead of only later giving \"not selectable\" popup error. (else (format (current-error-port) "Failed to create public key at ~a.\n" public-key))))) - (let ((user (getpwnam "dovecot")) - ;; This is Dovecot's term for the base directory for - ;; dynamically loadable modules. It supports only one. - (moduledir "/etc/dovecot/modules")) + (let ((user (getpwnam "dovecot"))) (mkdir-p/perms "/var/run/dovecot" user #o755) (mkdir-p/perms "/var/lib/dovecot" user #o755) (mkdir-p/perms "/etc/dovecot" user #o755) (copy-file #$(plain-file "dovecot.conf" config-str) "/etc/dovecot/dovecot.conf") (mkdir-p/perms "/etc/dovecot/private" user #o700) - (unless (file-exists? moduledir) - (symlink "/run/current-system/profile/lib/dovecot" moduledir)) (create-self-signed-certificate-if-absent #:private-key "/etc/dovecot/private/default.pem" #:public-key "/etc/dovecot/default.pem" -- cgit v1.2.3 From 71e746cc63a932afea0d41652c8c297d796bccf7 Mon Sep 17 00:00:00 2001 From: Maxim Cournoyer Date: Fri, 11 Sep 2020 14:08:34 -0400 Subject: doc: Document the use of snippets vs phases. * doc/contributing.texi (Snippets versus phases): New section. --- doc/contributing.texi | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'doc') diff --git a/doc/contributing.texi b/doc/contributing.texi index aedcb334c4..b18ffa1e57 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -369,6 +369,7 @@ needed is to review and apply the patch. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. +* Snippets versus Phases:: Whether to use a snippet, or a build phase. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. @@ -599,6 +600,20 @@ Gettext}): for the X11 resize-and-rotate (RandR) extension. @dots{}") @end example +@node Snippets versus Phases +@subsection Snippets versus Phases + +@cindex snippets, when to use +The boundary between using an origin snippet versus a build phase to +modify the sources of a package can be elusive. Origin snippets are +typically used to remove unwanted files such as bundled libraries, +nonfree sources, or to apply simple substitutions. The source derived +from an origin should produce a source that can be used to build the +package on any system that the upstream package supports (i.e., act as +the corresponding source). In particular, origin snippets must not +embed store items in the sources; such patching should rather be done +using build phases. Refer to the @code{origin} record documentation for +more information (@pxref{origin Reference}). @node Python Modules @subsection Python Modules -- cgit v1.2.3