aboutsummaryrefslogtreecommitdiff
path: root/doc/guix.texi
diff options
context:
space:
mode:
authorMarius Bakke <mbakke@fastmail.com>2020-05-05 20:43:21 +0200
committerMarius Bakke <mbakke@fastmail.com>2020-05-05 20:43:21 +0200
commit87a40d7203a813921b3ef0805c2b46c0026d6c31 (patch)
treecebad70c1df30969005c18c4d9faa39d7d80cbf6 /doc/guix.texi
parentba151b7e1a9cc0baf932b5c5e0c916e54d2e27f4 (diff)
parent751d1f01e4f0607d41e4c859d944753b18466652 (diff)
downloadguix-87a40d7203a813921b3ef0805c2b46c0026d6c31.tar
guix-87a40d7203a813921b3ef0805c2b46c0026d6c31.tar.gz
Merge branch 'master' into core-updates
Diffstat (limited to 'doc/guix.texi')
-rw-r--r--doc/guix.texi136
1 files changed, 114 insertions, 22 deletions
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