diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 7 | ||||
| -rw-r--r-- | doc/guix.texi | 243 | ||||
| -rw-r--r-- | doc/local.mk | 8 |
3 files changed, 228 insertions, 30 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 01f8aad9fb..d8929fa2e4 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -110,10 +110,13 @@ actually installing them. So that you can distinguish between your To that end, all the command-line tools can be used even if you have not run @code{make install}. To do that, prefix each command with @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the -top build tree of Guix), as in: +top build tree of Guix), as in@footnote{The @option{-E} flag to +@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set +such that @command{guix-daemon} and the tools it uses can find the Guile +modules they need.}: @example -$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild +$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild $ ./pre-inst-env guix build hello @end example diff --git a/doc/guix.texi b/doc/guix.texi index 6245d54e8d..1ecdcd2182 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2659,6 +2659,12 @@ lucky enough to be using Guix. You'd tell them to run @command{guix package -i @var{something}}, but that's not possible in this case. This is where @command{guix pack} comes in. +@quotation Note +If you are looking for ways to exchange binaries among machines that +already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix +publish}, and @ref{Invoking guix archive}. +@end quotation + @cindex pack @cindex bundle @cindex application bundle @@ -2794,10 +2800,16 @@ options (@pxref{Package Transformation Options}). @cindex @command{guix archive} @cindex archive The @command{guix archive} command allows users to @dfn{export} files -from the store into a single archive, and to later @dfn{import} them. +from the store into a single archive, and to later @dfn{import} them on +a machine that runs Guix. In particular, it allows store files to be transferred from one machine to the store on another machine. +@quotation Note +If you're looking for a way to produce archives in a format suitable for +tools other than Guix, @pxref{Invoking guix pack}. +@end quotation + @cindex exporting store items To export store files as an archive to standard output, run: @@ -3683,10 +3695,10 @@ Go build mechanisms}. The user is expected to provide a value for the key @code{#:import-path} and, in some cases, @code{#:unpack-path}. The @url{https://golang.org/doc/code.html#ImportPaths, import path} -corresponds to the filesystem path expected by the package's build +corresponds to the file system path expected by the package's build scripts and any referring packages, and provides a unique way to refer to a Go package. It is typically based on a combination of the -package source code's remote URI and filesystem hierarchy structure. In +package source code's remote URI and file system hierarchy structure. In some cases, you will need to unpack the package's source code to a different directory structure than the one indicated by the import path, and @code{#:unpack-path} should be used in such cases. @@ -10689,21 +10701,6 @@ See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor project's documentation} for more information. @end deffn -@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @ - [#:interface "127.0.0.1"] [#:port 6667] @ - [#:extra-settings ""] -Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that -acts as a gateway between IRC and chat networks. - -The daemon will listen to the interface corresponding to the IP address -specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only -local clients can connect, whereas @code{0.0.0.0} means that connections can -come from any networking interface. - -In addition, @var{extra-settings} specifies a string to append to the -configuration file. -@end deffn - The @code{(gnu services rsync)} module provides the following services: You might want an rsync daemon if you have files that you want available @@ -14425,6 +14422,47 @@ string, you could instantiate a prosody service like this: (prosody.cfg.lua ""))) @end example +@subsubheading BitlBee Service + +@cindex IRC (Internet Relay Chat) +@cindex IRC gateway +@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC +interface to a variety of messaging protocols such as XMPP. + +@defvr {Scheme Variable} bitlbee-service-type +This is the service type for the @url{http://bitlbee.org,BitlBee} IRC +gateway daemon. Its value is a @code{bitlbee-configuration} (see +below). + +To have BitlBee listen on port 6667 on localhost, add this line to your +services: + +@example +(service bitlbee-service-type) +@end example +@end defvr + +@deftp {Data Type} bitlbee-configuration +This is the configuration for BitlBee, with the following fields: + +@table @asis +@item @code{interface} (default: @code{"127.0.0.1"}) +@itemx @code{port} (default: @code{6667}) +Listen on the network interface corresponding to the IP address +specified in @var{interface}, on @var{port}. + +When @var{interface} is @code{127.0.0.1}, only local clients can +connect; when it is @code{0.0.0.0}, connections can come from any +networking interface. + +@item @code{package} (default: @code{bitlbee}) +The BitlBee package to use. + +@item @code{extra-settings} (default: @code{""}) +Configuration snippet added as-is to the BitlBee configuration file. +@end table +@end deftp + @node Telephony Services @subsubsection Telephony Services @@ -14916,8 +14954,162 @@ Local accounts with lower values will silently fail to authenticate. @cindex web @cindex www @cindex HTTP -The @code{(gnu services web)} module provides the nginx web server and -also a fastcgi wrapper daemon. +The @code{(gnu services web)} module provides the Apache HTTP Server, +the nginx web server, and also a fastcgi wrapper daemon. + +@subsubheading Apache HTTP Server + +@deffn {Scheme Variable} httpd-service-type +Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server +(@dfn{httpd}). The value for this service type is a +@code{https-configuration} record. + +A simple example configuration is given below. + +@example +(service httpd-service-type + (httpd-configuration + (config + (httpd-config-file + (server-name "www.example.com") + (document-root "/srv/http/www.example.com"))))) +@end example + +Other services can also extend the @code{httpd-service-type} to add to +the configuration. + +@example +(simple-service 'my-extra-server httpd-service-type + (list + (httpd-virtualhost + "*:80" + (list (string-append + "ServerName "www.example.com + DocumentRoot \"/srv/http/www.example.com\""))))) +@end example +@end deffn + +The details for the @code{httpd-configuration}, @code{httpd-module}, +@code{httpd-config-file} and @code{httpd-virtualhost} record types are +given below. + +@deffn {Data Type} httpd-configuration +This data type represents the configuration for the httpd service. + +@table @asis +@item @code{package} (default: @code{httpd}) +The httpd package to use. + +@item @code{pid-file} (default: @code{"/var/run/httpd"}) +The pid file used by the shepherd-service. + +@item @code{config} (default: @code{(httpd-config-file)}) +The configuration file to use with the httpd service. The default value +is a @code{httpd-config-file} record, but this can also be a different +G-expression that generates a file, for example a @code{plain-file}. A +file outside of the store can also be specified through a string. + +@end table +@end deffn + +@deffn {Data Type} httpd-module +This data type represents a module for the httpd service. + +@table @asis +@item @code{name} +The name of the module. + +@item @code{file} +The file for the module. This can be relative to the httpd package being +used, the absolute location of a file, or a G-expression for a file +within the store, for example @code{(file-append mod-wsgi +"/modules/mod_wsgi.so")}. + +@end table +@end deffn + +@deffn {Data Type} httpd-config-file +This data type represents a configuration file for the httpd service. + +@table @asis +@item @code{modules} (default: @code{%default-httpd-modules}) +The modules to load. Additional modules can be added here, or loaded by +additional configuration. + +@item @code{server-root} (default: @code{httpd}) +The @code{ServerRoot} in the configuration file, defaults to the httpd +package. Directives including @code{Include} and @code{LoadModule} are +taken as relative to the server root. + +@item @code{server-name} (default: @code{#f}) +The @code{ServerName} in the configuration file, used to specify the +request scheme, hostname and port that the server uses to identify +itself. + +This doesn't need to be set in the server config, and can be specifyed +in virtual hosts. The default is @code{#f} to not specify a +@code{ServerName}. + +@item @code{document-root} (default: @code{"/srv/http"}) +The @code{DocumentRoot} from which files will be served. + +@item @code{listen} (default: @code{'("80")}) +The list of values for the @code{Listen} directives in the config +file. The value should be a list of strings, when each string can +specify the port number to listen on, and optionally the IP address and +protocol to use. + +@item @code{pid-file} (default: @code{"/var/run/httpd"}) +The @code{PidFile} to use. This should match the @code{pid-file} set in +the @code{httpd-configuration} so that the Shepherd service is +configured correctly. + +@item @code{error-log} (default: @code{"/var/log/httpd/error_log"}) +The @code{ErrorLog} to which the server will log errors. + +@item @code{user} (default: @code{"httpd"}) +The @code{User} which the server will answer requests as. + +@item @code{group} (default: @code{"httpd"}) +The @code{Group} which the server will answer requests as. + +@item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")}) +A flat list of strings and G-expressions which will be added to the end +of the configuration file. + +Any values which the service is extended with will be appended to this +list. + +@end table +@end deffn + +@deffn {Data Type} httpd-virtualhost +This data type represents a virtualhost configuration block for the httpd service. + +These should be added to the extra-config for the httpd-service. + +@example +(simple-service 'my-extra-server httpd-service-type + (list + (httpd-virtualhost + "*:80" + (list (string-append + "ServerName "www.example.com + DocumentRoot \"/srv/http/www.example.com\""))))) +@end example + +@table @asis +@item @code{addresses-and-ports} +The addresses and ports for the @code{VirtualHost} directive. + +@item @code{contents} +The contents of the @code{VirtualHost} directive, this should be a list +of strings and G-expressions. + +@end table +@end deffn + +@subsubheading NGINX @deffn {Scheme Variable} nginx-service-type Service type for the @uref{https://nginx.org/,NGinx} web server. The @@ -15122,11 +15314,12 @@ URI which this location block matches. @anchor{nginx-location-configuration body} @item @code{body} -Body of the location block, specified as a string. This can contain many +Body of the location block, specified as a list of strings. This can contain +many configuration directives. For example, to pass requests to a upstream server group defined using an @code{nginx-upstream-configuration} block, -the following directive would be specified in the body @samp{proxy_pass -http://upstream-name;}. +the following directive would be specified in the body @samp{(list "proxy_pass +http://upstream-name;")}. @end table @end deftp @@ -15655,7 +15848,7 @@ The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}. @item @code{config} (default: @code{"/var/lib/knot/keys/keys"}) The configuration string of the backend. An example for the PKCS#11 is: @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}. -For the pem backend, the string reprensents a path in the filesystem. +For the pem backend, the string reprensents a path in the file system. @end table @end deftp @@ -17727,7 +17920,7 @@ service: (service qemu-binfmt-service-type (qemu-binfmt-configuration (platforms (lookup-qemu-platforms "arm")) - (qemu-support? #t))) + (guix-support? #t))) @end example You can run: diff --git a/doc/local.mk b/doc/local.mk index dc48fc22bf..397ade050e 100644 --- a/doc/local.mk +++ b/doc/local.mk @@ -3,7 +3,7 @@ # Copyright © 2012, 2013, 2014, 2015, 2016, 2017 Ludovic Courtès <ludo@gnu.org> # Copyright © 2013 Andreas Enge <andreas@enge.fr> # Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com> -# Copyright © 2016 Mathieu Lirzin <mthl@gnu.org> +# Copyright © 2016, 2018 Mathieu Lirzin <mthl@gnu.org> # # This file is part of GNU Guix. # @@ -22,6 +22,10 @@ info_TEXINFOS = %D%/guix.texi +%C%_guix_TEXINFOS = \ + %D%/contributing.texi \ + %D%/fdl-1.3.texi + DOT_FILES = \ %D%/images/bootstrap-graph.dot \ %D%/images/bootstrap-packages.dot \ @@ -36,8 +40,6 @@ DOT_VECTOR_GRAPHICS = \ EXTRA_DIST += \ %D%/htmlxref.cnf \ - %D%/contributing.texi \ - %D%/fdl-1.3.texi \ $(DOT_FILES) \ $(DOT_VECTOR_GRAPHICS) \ %D%/images/coreutils-size-map.eps \ |