diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 62 | ||||
| -rw-r--r-- | doc/guix.texi | 127 | ||||
| -rw-r--r-- | doc/local.mk | 6 |
3 files changed, 171 insertions, 24 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index c6586a2adf..9d45becf86 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -274,6 +274,33 @@ trigger string @code{origin...}, which can be expanded further. The @code{origin} snippet in turn may insert other trigger strings ending on @code{...}, which also can be expanded further. +@cindex insert or update copyright +@cindex @code{M-x guix-copyright} +@cindex @code{M-x copyright-update} +Additionaly we provide insertion and automatic update of a copyright in +@file{etc/copyright.el}. You may want to set your full name, mail, and +load a file. + +@lisp +(setq user-full-name "Alice Doe") +(setq user-mail-address "alice@@mail.org") +;; @r{Assuming the Guix checkout is in ~/src/guix.} +(load-file "~/src/guix/etc/copyright.el") +@end lisp + +To insert a copyright at the current line invoke @code{M-x guix-copyright}. + +To update a copyright you need to specify a @code{copyright-names-regexp}. + +@lisp +(setq copyright-names-regexp + (format "%s <%s>" user-full-name user-mail-address)) +@end lisp + +You can check if your copyright is up to date by evaluating @code{M-x +copyright-update}. If you want to do it automatically after each buffer +save then add @code{(add-hook 'after-save-hook 'copyright-update)} in +Emacs. @node Packaging Guidelines @section Packaging Guidelines @@ -347,6 +374,7 @@ needed is to review and apply the patch. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. +* Rust Crates:: Beware of oxidation. * Fonts:: Fond of fonts. @end menu @@ -685,6 +713,40 @@ dashes and prepend the prefix @code{java-}. So the class @code{java-apache-commons-cli}. +@node Rust Crates +@subsection Rust Crates + +@cindex rust +Rust programs standing for themselves are named as any other package, using the +lowercase upstream name. + +To prevent namespace collisions we prefix all other Rust packages with the +@code{rust-} prefix. The name should be changed to lowercase as appropriate and +dashes should remain in place. + +In the rust ecosystem it is common for multiple incompatible versions of a +package to be used at any given time, so all packages should have a versioned +suffix. If a package has passed version 1.0.0 then just the major version +number is sufficient (e.g.@: @code{rust-clap-2}), otherwise the version suffix +should contain both the major and minor version (e.g.@: @code{rust-rand-0.6}). + +Because of the difficulty in reusing rust packages as pre-compiled inputs for +other packages the Cargo build system (@pxref{Build Systems, +@code{cargo-build-system}}) presents the @code{#:cargo-inputs} and +@code{cargo-development-inputs} keywords as build system arguments. It would be +helpful to think of these as similar to @code{propagated-inputs} and +@code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies} +should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in +@code{#:cargo-development-inputs}. If a Rust package links to other libraries +then the standard placement in @code{inputs} and the like should be used. + +Care should be taken to ensure the correct version of dependencies are used; to +this end we try to refrain from skipping the tests or using @code{#:skip-build?} +when possible. Of course this is not always possible, as the package may be +developed for a different Operating System, depend on features from the Nightly +Rust compiler, or the test suite may have atrophied since it was released. + + @node Fonts @subsection Fonts diff --git a/doc/guix.texi b/doc/guix.texi index 282f9578bf..a66bb3d646 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -73,6 +73,7 @@ Copyright @copyright{} 2020 Leo Prikler@* Copyright @copyright{} 2019, 2020 Simon Tournier@* Copyright @copyright{} 2020 Wiktor Żelazny@* Copyright @copyright{} 2020 Damien Cassou@* +Copyright @copyright{} 2020 Jakub Kądziołka@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -771,11 +772,11 @@ The following dependencies are optional: @itemize @item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. +@c Note: We need at least 0.12.0 for 'userauth-gssapi!'. Support for build offloading (@pxref{Daemon Offload Setup}) and @command{guix copy} (@pxref{Invoking guix copy}) depends on @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, -version 0.10.2 or later. +version 0.12.0 or later. @item When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib @@ -2440,6 +2441,11 @@ your system includes the latest security updates (@pxref{Security Updates}). Note that @command{sudo guix} runs your user's @command{guix} command and @emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. + +The difference matters here, because @command{guix pull} updates +the @command{guix} command and package definitions only for the user it is ran +as. This means that if you choose to use @command{guix system reconfigure} in +root's login shell, you'll need to @command{guix pull} separately. @end quotation Join us on @code{#guix} on the Freenode IRC network or on @@ -4958,8 +4964,10 @@ shared and will change to the user's home directory within the container instead. See also @code{--user}. @item --expose=@var{source}[=@var{target}] -For containers, expose the file system @var{source} from the host system -as the read-only file system @var{target} within the container. If +@itemx --share=@var{source}[=@var{target}] +For containers, @code{--expose} (resp. @code{--share}) exposes the file +system @var{source} from the host system as the read-only +(resp. writable) file system @var{target} within the container. If @var{target} is not specified, @var{source} is used as the target mount point in the container. @@ -4971,19 +4979,6 @@ directory: guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile @end example -@item --share=@var{source}[=@var{target}] -For containers, share the file system @var{source} from the host system -as the writable file system @var{target} within the container. If -@var{target} is not specified, @var{source} is used as the target mount -point in the container. - -The example below spawns a Guile REPL in a container in which the user's -home directory is accessible for both reading and writing via the -@file{/exchange} directory: - -@example -guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile -@end example @end table @command{guix environment} @@ -6159,6 +6154,70 @@ parameters available to cargo. It will also remove an included if they are defined by the crate. @end defvr + +@defvr {Scheme Variable} copy-build-system +@cindex (copy build system) +This variable is exported by @code{(guix build-system copy)}. It +supports builds of simple packages that don't require much compiling, +mostly just moving files around. + +It adds much of the @code{gnu-build-system} packages to the set of +inputs. Because of this, the @code{copy-build-system} does not require +all the boilerplate code often needed for the +@code{trivial-build-system}. + +To further simplify the file installation process, an +@code{#:install-plan} argument is exposed to let the packager specify +which files go where. The install plan is a list of @code{(@var{source} +@var{target} [@var{filters}])}. @var{filters} are optional. + +@itemize +@item When @var{source} matches a file or directory without trailing slash, install it to @var{target}. +@itemize +@item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}. +@item Otherwise install @var{source} as @var{target}. +@end itemize + +@item When @var{source} is a directory with a trailing slash, or when @var{filters} are used, +the trailing slash of @var{target} is implied with the same meaning +as above. +@itemize +@item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}. +@item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude}, +@code{#:exclude-regexp}, only select files are installed depending on +the filters. Each filters is specified by a list of strings. +@itemize +@item With @code{#:include}, install all the files which the path suffix matches +at least one of the elements in the given list. +@item With @code{#:include-regexp}, install all the files which the +subpaths match at least one of the regular expressions in the given +list. +@item The @code{#:exclude} and @code{#:exclude-regexp} filters +are the complement of their inclusion counterpart. Without @code{#:include} flags, +install all files but those matching the exclusion filters. +If both inclusions and exclusions are specified, the exclusions are done +on top of the inclusions. +@end itemize +@end itemize +In all cases, the paths relative to @var{source} are preserved within +@var{target}. +@end itemize + +Examples: + +@itemize +@item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}. +@item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}. +@item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app}, +e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}. +@item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to +@file{share/my-app/sub/file}. +@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to +@file{share/my-app/file}. +@end itemize +@end defvr + + @cindex Clojure (programming language) @cindex simple Clojure build system @defvr {Scheme Variable} clojure-build-system @@ -6815,9 +6874,11 @@ instruct it to listen for TCP connections (@pxref{Invoking guix-daemon, @item ssh @cindex SSH access to build daemons -These URIs allow you to connect to a remote daemon over -SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}. -A typical URL might look like this: +These URIs allow you to connect to a remote daemon over SSH. This +feature requires Guile-SSH (@pxref{Requirements}) and a working +@code{guile} binary in @code{PATH} on the destination machine. It +supports public key and GSSAPI authentication. A typical URL might look +like this: @example ssh://charlie@@guix.example.org:22 @@ -14463,7 +14524,7 @@ Command to run when halting. Command to run when rebooting. @item @code{theme} (default "maldives") -Theme to use. Default themes provided by SDDM are "elarun" or "maldives". +Theme to use. Default themes provided by SDDM are "elarun", "maldives" or "maya". @item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes") Directory to look for themes. @@ -14538,7 +14599,7 @@ Relogin after logout. @cindex X11 login @defvr {Scheme Variable} sddm-service-type This is the type of the service to run the -@uref{https://github.com/sddm/sddm,SSDM display manager}. Its value +@uref{https://github.com/sddm/sddm,SDDM display manager}. Its value must be a @code{sddm-configuration} record (see below). Here's an example use: @@ -21799,6 +21860,13 @@ Defaults to @samp{#t}. @end deftypevr +@deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io? +(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to +poll/epoll/select prior to the write operation. + +Defaults to @samp{#f}. +@end deftypevr + @deftypevr {@code{openvpn-client-configuration} parameter} number verbosity Verbosity level. @@ -21814,6 +21882,14 @@ Defaults to @samp{#f}. @end deftypevr +@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass +Authenticate with server using username/password. The option is a file +containing username/password on 2 lines. Do not use a file-like object as it +would be added to the store and readable by any user. + +Defaults to @samp{'disabled}. +@end deftypevr + @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? Whether to check the server certificate has server usage extension. @@ -21935,6 +22011,13 @@ Defaults to @samp{#t}. @end deftypevr +@deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io? +(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to +poll/epoll/select prior to the write operation. + +Defaults to @samp{#f}. +@end deftypevr + @deftypevr {@code{openvpn-server-configuration} parameter} number verbosity Verbosity level. diff --git a/doc/local.mk b/doc/local.mk index a361f2388e..3805593172 100644 --- a/doc/local.mk +++ b/doc/local.mk @@ -27,7 +27,8 @@ info_TEXINFOS = %D%/guix.texi \ %D%/guix.fr.texi \ %D%/guix.ru.texi \ %D%/guix.zh_CN.texi \ - %D%/guix-cookbook.texi + %D%/guix-cookbook.texi \ + %D%/guix-cookbook.de.texi %C%_guix_TEXINFOS = \ %D%/contributing.texi \ @@ -69,7 +70,8 @@ TRANSLATED_INFO = \ %D%/contributing.es.texi \ %D%/contributing.fr.texi \ %D%/contributing.ru.texi \ - %D%/contributing.zh_CN.texi + %D%/contributing.zh_CN.texi \ + %D%/guix-cookbook.de.texi # Bundle this file so that makeinfo finds it in out-of-source-tree builds. BUILT_SOURCES += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO) |