diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 24 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 4 | ||||
| -rw-r--r-- | doc/guix.texi | 136 |
3 files changed, 138 insertions, 26 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 31b875f817..9583120742 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1187,18 +1187,38 @@ the OpenPGP key you will use to sign commits, and giving its fingerprint (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an introduction to public-key cryptography with GnuPG. +@c See <https://sha-mbles.github.io/>. +Set up GnuPG such that it never uses the SHA1 hash algorithm for digital +signatures, which is known to be unsafe since 2019, for instance by +adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG +Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}): + +@example +digest-algo sha512 +@end example + @item Maintainers ultimately decide whether to grant you commit access, usually following your referrals' recommendation. @item +@cindex OpenPGP, signed commits If and once you've been given access, please send a message to @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key you will use to sign commits (do that before pushing your first commit). That way, everyone can notice and ensure you control that OpenPGP key. -@c TODO: Add note about adding the fingerprint to the list of authorized -@c keys once that has stabilized. +@quotation Important +Before you can push for the first time, maintainers must: + +@enumerate +@item +add your OpenPGP key to the @code{keyring} branch; +@item +add your OpenPGP fingerprint to the @file{.guix-authorizations} file of +the branch(es) you will commit to. +@end enumerate +@end quotation @item Make sure to read the rest of this section and... profit! diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index f58d18d47c..2a605276e6 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -1594,7 +1594,7 @@ An example configuration can look like this: @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: +module @code{sbcl-ttf-fonts}, adding it to Guix system packages: @lisp (use-modules (gnu)) @@ -1603,7 +1603,7 @@ module @code{sbcl-stumpwm-ttf-fonts}, adding it to Guix system packages: (operating-system ;; … (packages (append (list sbcl stumpwm `(,stumpwm "lib")) - sbcl-stumpwm-ttf-fonts font-dejavu %base-packages))) + sbcl-ttf-fonts font-dejavu %base-packages))) @end lisp Then you need to add the following code to a StumpWM configuration file diff --git a/doc/guix.texi b/doc/guix.texi index 472b70e092..6c448de33b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -79,6 +79,7 @@ Copyright @copyright{} 2020 Naga Malleswari@* Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 R Veera Kumar@* Copyright @copyright{} 2020 Pierre Langlois@* +Copyright @copyright{} 2020 pinoaffe@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1768,22 +1769,11 @@ can do so by running Emacs with the @code{--no-site-file} option @subsection The GCC toolchain -@cindex GCC -@cindex ld-wrapper - -Guix offers individual compiler packages such as @code{gcc} but if you -are in need of a complete toolchain for compiling and linking source -code what you really want is the @code{gcc-toolchain} package. This -package provides a complete GCC toolchain for C/C++ development, -including GCC itself, the GNU C Library (headers and binaries, plus -debugging symbols in the @code{debug} output), Binutils, and a linker -wrapper. - -The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches -passed to the linker, add corresponding @code{-rpath} arguments, and -invoke the actual linker with this new set of arguments. You can instruct the -wrapper to refuse to link against libraries not in the store by setting the -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. +@c XXX: The contents of this section were moved under +@c ``Development'', since it makes more sense there and is not specific +@c foreign distros. Remove it from here eventually? +@xref{Packages for C Development}, for information on packages for C/C++ +development. @node Upgrading Guix @section Upgrading Guix @@ -4681,6 +4671,7 @@ easily distributed to users who do not run Guix. @menu * Invoking guix environment:: Setting up development environments. * Invoking guix pack:: Creating software bundles. +* Packages for C Development:: Working with C code with Guix. @end menu @node Invoking guix environment @@ -5344,6 +5335,27 @@ In addition, @command{guix pack} supports all the common build options (@pxref{Common Build Options}) and all the package transformation options (@pxref{Package Transformation Options}). +@node Packages for C Development +@section Packages for C Development + +@cindex GCC +@cindex ld-wrapper +@cindex linker wrapper +@cindex toolchain, for C development + +If you need a complete toolchain for compiling and linking C or C++ +source code, use the @code{gcc-toolchain} package. This package +provides a complete GCC toolchain for C/C++ development, including GCC +itself, the GNU C Library (headers and binaries, plus debugging symbols +in the @code{debug} output), Binutils, and a linker wrapper. + +The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches +passed to the linker, add corresponding @code{-rpath} arguments, and +invoke the actual linker with this new set of arguments. You can instruct the +wrapper to refuse to link against libraries not in the store by setting the +@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. + + @c ********************************************************************* @node Programming Interface @@ -14379,6 +14391,86 @@ Whether to enable password-based authentication. @end table @end deftp +@cindex AutoSSH +@deffn {Scheme Variable} autossh-service-type +This is the type for the @uref{https://www.harding.motd.ca/autossh, +AutoSSH} program that runs a copy of @command{ssh} and monitors it, +restarting it as necessary should it die or stop passing traffic. +AutoSSH can be run manually from the command-line by passing arguments +to the binary @command{autossh} from the package @code{autossh}, but it +can also be run as a Guix service. This latter use case is documented +here. + +AutoSSH can be used to forward local traffic to a remote machine using +an SSH tunnel, and it respects the @file{~/.ssh/config} of the user it +is run as. + +For example, to specify a service running autossh as the user +@code{pino} and forwarding all local connections to port @code{8081} to +@code{remote:8081} using an SSH tunnel, add this call to the operating +system's @code{services} field: + +@lisp +(service autossh-service-type + (autossh-configuration + (user "pino") + (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net")))) +@end lisp +@end deffn + +@deftp {Data Type} autossh-configuration +This data type represents the configuration of an AutoSSH service. + +@table @asis + +@item @code{user} (default @code{"autossh"}) +The user as which the AutoSSH service is to be run. +This assumes that the specified user exists. + +@item @code{poll} (default @code{600}) +Specifies the connection poll time in seconds. + +@item @code{first-poll} (default @code{#f}) +Specifies how many seconds AutoSSH waits before the first connection +test. After this first test, polling is resumed at the pace defined in +@code{poll}. When set to @code{#f}, the first poll is not treated +specially and will also use the connection poll specified in +@code{poll}. + +@item @code{gate-time} (default @code{30}) +Specifies how many seconds an SSH connection must be active before it is +considered successful. + +@item @code{log-level} (default @code{1}) +The log level, corresponding to the levels used by syslog---so @code{0} +is the most silent while @code{7} is the chattiest. + +@item @code{max-start} (default @code{#f}) +The maximum number of times SSH may be (re)started before AutoSSH exits. +When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely. + +@item @code{message} (default @code{""}) +The message to append to the echo message sent when testing connections. + +@item @code{port} (default @code{"0"}) +The ports used for monitoring the connection. When set to @code{"0"}, +monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is +a positive integer, ports @var{n} and @var{n}+1 are used for +monitoring the connection, such that port @var{n} is the base +monitoring port and @code{n+1} is the echo port. When set to +@code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive +integers, the ports @var{n} and @var{n}+1 are used for monitoring the +connection, such that port @var{n} is the base monitoring port and +@var{m} is the echo port. + +@item @code{ssh-options} (default @code{'()}) +The list of command-line arguments to pass to @command{ssh} when it is +run. Options @option{-f} and @option{-M} are reserved for AutoSSH and +may cause undefined behaviour. + +@end table +@end deftp + @defvr {Scheme Variable} %facebook-host-aliases This variable contains a string for use in @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each @@ -26074,10 +26166,10 @@ pointed to by the @code{GIT_SSL_CAINFO} environment variable. Thus, you would typically run something like: @example -$ guix install nss-certs -$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" -$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -$ export GIT_SSL_CAINFO="$SSL_CERT_FILE" +guix install nss-certs +export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" +export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" +export GIT_SSL_CAINFO="$SSL_CERT_FILE" @end example As another example, R requires the @code{CURL_CA_BUNDLE} environment @@ -26085,8 +26177,8 @@ variable to point to a certificate bundle, so you would have to run something like this: @example -$ guix install nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" +guix install nss-certs +export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" @end example For other applications you may want to look up the required environment |