diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 205 |
1 files changed, 94 insertions, 111 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index c21235f28d..32414b6316 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -36,7 +36,7 @@ Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016, 2017 Nikita Gillmann@* -Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@* +Copyright @copyright{} 2016, 2017, 2018, 2019, 2021, 2022 Jan Nieuwenhuizen@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@* @@ -412,7 +412,7 @@ Installing Debugging Files Bootstrapping -* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU. +* Full-Source Bootstrap:: A Bootstrap worthy of GNU. * Preparing to Use the Bootstrap Binaries:: Building that what matters most. @end detailmenu @@ -9141,6 +9141,15 @@ directory, the parameter @code{#:javascript-files} can be used to specify a list of file names to feed to the minifier. @end defvr +@defvr {Scheme Variable} mozilla-build-system +This variable is exported by @code{(guix build-system mozilla)}. It +sets the @code{--target} and @code{--host} configuration flags to what +software developed by Mozilla expects -- due to historical reasons, +Mozilla software expects @code{--host} to be the system that is +cross-compiled from and @code{--target} to be the system that is +cross-compiled to, contrary to the standard Autotools conventions. +@end defvr + @defvr {Scheme Variable} ocaml-build-system This variable is exported by @code{(guix build-system ocaml)}. It implements a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists @@ -21849,10 +21858,9 @@ Defaults to @samp{#f}. @deftypevr {@code{cups-configuration} parameter} comma-separated-string-list browse-dns-sd-sub-types Specifies a list of DNS-SD sub-types to advertise for each shared printer. -For example, @samp{"_cups" "_print"} will tell network clients that both -CUPS sharing and IPP Everywhere are supported. -Defaults to @samp{"_cups"}. +The default @samp{(list "_cups" "_print" "_universal")} tells clients +that CUPS sharing, IPP Everywhere, AirPrint, and Mopria are supported. @end deftypevr @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols @@ -21873,22 +21881,6 @@ Specifies whether shared printers are advertised. Defaults to @samp{#f}. @end deftypevr -@deftypevr {@code{cups-configuration} parameter} string classification -Specifies the security classification of the server. Any valid banner -name can be used, including @samp{"classified"}, @samp{"confidential"}, -@samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the -banner can be omitted to disable secure printing functions. - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean classify-override? -Specifies whether users may override the classification (cover page) of -individual print jobs using the @code{job-sheets} option. - -Defaults to @samp{#f}. -@end deftypevr - @deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type Specifies the default type of authentication to use. @@ -22024,17 +22016,6 @@ domain sockets. The Listen directive is similar to the Port directive but allows you to restrict access to specific interfaces or networks. @end deftypevr -@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log -Specifies the number of pending connections that will be allowed. This -normally only affects very busy servers that have reached the MaxClients -limit, but can also be triggered by large numbers of simultaneous -connections. When the limit is reached, the operating system will -refuse additional connections until the scheduler can accept the pending -ones. - -Defaults to @samp{128}. -@end deftypevr - @deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls Specifies a set of additional access controls. @@ -22140,14 +22121,14 @@ Defaults to @samp{500}. @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer Specifies the maximum number of simultaneous jobs that are allowed per -printer. A value of 0 allows up to MaxJobs jobs per printer. +printer. A value of 0 allows up to @code{max-jobs} per printer. Defaults to @samp{0}. @end deftypevr @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user Specifies the maximum number of simultaneous jobs that are allowed per -user. A value of 0 allows up to MaxJobs jobs per user. +user. A value of 0 allows up to @code{max-jobs} per user. Defaults to @samp{0}. @end deftypevr @@ -22166,51 +22147,42 @@ bytes. The value 0 disables log rotation. Defaults to @samp{1048576}. @end deftypevr -@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout -Specifies the maximum amount of time to allow between files in a -multiple file print job, in seconds. +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions +Specifies the maximum number of simultaneous event subscriptions that are +allowed. Set to @samp{0} to allow an unlimited number of subscriptions. -Defaults to @samp{900}. +Defaults to @samp{0}. @end deftypevr -@deftypevr {@code{cups-configuration} parameter} string page-log-format -Specifies the format of PageLog lines. Sequences beginning with percent -(@samp{%}) characters are replaced with the corresponding information, -while all other characters are copied literally. The following percent -sequences are recognized: - -@table @samp -@item %% -insert a single percent character - -@item %@{name@} -insert the value of the specified IPP attribute - -@item %C -insert the number of copies for the current page +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-job +Specifies the maximum number of simultaneous event subscriptions that are +allowed per job. A value of @samp{0} allows up to @code{max-subscriptions} +per job. -@item %P -insert the current page number +Defaults to @samp{0}. +@end deftypevr -@item %T -insert the current date and time in common log format +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-printer +Specifies the maximum number of simultaneous event subscriptions that are +allowed per printer. A value of @samp{0} allows up to @code{max-subscriptions} +per printer. -@item %j -insert the job ID +Defaults to @samp{0}. +@end deftypevr -@item %p -insert the printer name +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-user +Specifies the maximum number of simultaneous event subscriptions that are +allowed per user. A value of @samp{0} allows up to @code{max-subscriptions} +per user. -@item %u -insert the username -@end table +Defaults to @samp{0}. +@end deftypevr -A value of the empty string disables page logging. The string @code{%p -%u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@} -%@{job-name@} %@{media@} %@{sides@}} creates a page log with the -standard items. +@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout +Specifies the maximum amount of time to allow between files in a +multiple file print job, in seconds. -Defaults to @samp{""}. +Defaults to @samp{900}. @end deftypevr @deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables @@ -22298,6 +22270,17 @@ history is preserved until the MaxJobs limit is reached. Defaults to @samp{#t}. @end deftypevr +@deftypevr {@code{cups-configuration} parameter} comma-separated-string-list-or-#f ready-paper-sizes +Specifies a list of potential paper sizes that are reported as ready, +that is: loaded. The actual list will contain only the sizes that each +printer supports. + +The default value of @code{#f} is a special case: CUPS will use +@samp{(list \"Letter\" \"Legal\" \"Tabloid\" \"4x6\" \"Env10\")} +if the default paper size is \"Letter\", and +@samp{(list \"A3\" \"A4\" \"A5\" \"A6\" \"EnvDL\")} otherwise. +@end deftypevr + @deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout Specifies the amount of time to wait for job completion before restarting the scheduler. @@ -22305,13 +22288,6 @@ restarting the scheduler. Defaults to @samp{30}. @end deftypevr -@deftypevr {@code{cups-configuration} parameter} string rip-cache -Specifies the maximum amount of memory to use when converting documents -into bitmaps for a printer. - -Defaults to @samp{"128m"}. -@end deftypevr - @deftypevr {@code{cups-configuration} parameter} string server-admin Specifies the email address of the server administrator. @@ -41616,12 +41592,12 @@ re-create them if needed (@pxref{Preparing to Use the Bootstrap Binaries}). @menu -* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU. +* Full-Source Bootstrap:: A Bootstrap worthy of GNU. * Preparing to Use the Bootstrap Binaries:: Building that what matters most. @end menu -@node Reduced Binary Seed Bootstrap -@section The Reduced Binary Seed Bootstrap +@node Full-Source Bootstrap +@section The Full-Source Bootstrap Guix---like other GNU/Linux distributions---is traditionally bootstrapped from a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU @@ -41636,28 +41612,47 @@ about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing or even inspecting these is next to impossible. For @code{i686-linux} and @code{x86_64-linux}, Guix now features a -``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full -Source Bootstrap'' and while we are working towards that goal it would -be hyperbole to use that term for what we do now.}. - -The Reduced Binary Seed bootstrap removes the most critical tools---from a -trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C -Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and -linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler -written in Scheme and the Mes C Library, built for TinyCC and for GCC). - -Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU -C Library are built from source. From here on the more traditional -bootstrap process resumes. This approach has reduced the bootstrap -binaries in size to about 145MB in Guix v1.1. - -The next step that Guix has taken is to replace the shell and all its +@dfn{full-source bootstrap}. This bootstrap is rooted in +@file{hex0-seed} from the @url{https://savannah.gnu.org/projects/stage0, +Stage0} package. The hex0 program is minimalist assembler: it reads +space-separated hexadecimal digits (nibbles) from a file, possibly +including comments, and emits on standard output the bytes corresponding +to those hexadecimal numbers. The source code of this initial hex0 +program is a file called +@c XXX TODO: udpate to savannah url, once accepted there +@url{https://github.com/oriansj/bootstrap-seeds/blob/master/POSIX/x86/hex0_x86.hex0,@file{hex0_x86.hex0}} +and is written in the @code{hex0} language. + +Hex0 is self-hosting, which means that it can build itself: + +@example +./hex0-seed hex0_x86.hex0 hex0 +@end example + +Hex0 it is the ASCII-equivalent of the binary program and can be +produced by doing something much like: + +@example +sed 's/[;#].*$//g' hex0_x86.hex0 | xxd -r -p > hex0 +chmod +x hex0 +@end example + +It is because of this ASCII-binary equivalence that we can bless this +initial 357-byte binary as source, and hence `full-source bootstrap''. + +The bootstrap then continues: @code{hex0} builds @code{hex1} and then on +to @code{M0}, @code{hex2}, @code{M1}, @code{mescc-tools} and finally +@code{M2-Planet}. Then, using @code{mescc-tools}, @code{M2-Planet} we +build Mes (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a +Scheme interpreter and C compiler in Scheme). Frome here on starts +the more traditional @code{C}-based bootstrap of the GNU System. + +Another step that Guix has taken is to replace the shell and all its utilities with implementations in Guile Scheme, the @emph{Scheme-only bootstrap}. Gash (@pxref{Gash,,, gash, The Gash manual}) is a POSIX-compatible shell that replaces Bash, and it comes with Gash Utils which has minimalist replacements for Awk, the GNU Core Utilities, Grep, -Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were -removed are now built from source. +Gzip, Sed, and Tar. Building the GNU System from source is currently only possible by adding some historical GNU packages as intermediate steps@footnote{Packages @@ -41673,22 +41668,10 @@ The graph below shows the resulting dependency graph for @code{gcc-core-mesboot0}, the bootstrap compiler used for the traditional bootstrap of the rest of the Guix System. -@c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-mescc-tools|bootstrap-mes|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot +@c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-seeds|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot @image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0} -The only significant binary bootstrap seeds that remain@footnote{ -Ignoring the 68KB @code{mescc-tools}; that will be removed later, -together with @code{mes}.} are a Scheme interpreter and a Scheme -compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the -static binaries for @file{bash}, @code{tar}, and @code{xz} that are used -to get Guile running.}. - -This further reduction has brought down the size of the binary seed to -about 60MB for @code{i686-linux} and @code{x86_64-linux}. - -Work is ongoing to remove all binary blobs from our free software -bootstrap stack, working towards a Full Source Bootstrap. Also ongoing -is work to bring these bootstraps to the @code{arm-linux} and +Work is ongoing to to bring these bootstraps to the @code{arm-linux} and @code{aarch64-linux} architectures and to the Hurd. If you are interested, join us on @samp{#bootstrappable} on the Freenode |