diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.scm | 115 | ||||
| -rw-r--r-- | doc/guix.texi | 100 |
2 files changed, 197 insertions, 18 deletions
diff --git a/doc/build.scm b/doc/build.scm index 7ba9f57bc9..c99bd505fd 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -34,6 +34,7 @@ (gnu packages gawk) (gnu packages gettext) (gnu packages guile) + (gnu packages guile-xyz) (gnu packages iso-codes) (gnu packages texinfo) (gnu packages tex) @@ -164,6 +165,115 @@ as well as images, OS examples, and translations." ;; Options passed to 'makeinfo --html'. '("--css-ref=https://www.gnu.org/software/gnulib/manual.css")) +(define* (syntax-highlighted-html input + #:key + (name "highlighted-syntax") + (syntax-css-url + "/static/base/css/code.css")) + "Return a derivation called NAME that processes all the HTML files in INPUT +to (1) add them a link to SYNTAX-CSS-URL, and (2) highlight the syntax of all +its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')." + (define build + (with-extensions (list guile-lib guile-syntax-highlight) + (with-imported-modules '((guix build utils)) + #~(begin + (use-modules (htmlprag) + (syntax-highlight) + (syntax-highlight scheme) + (syntax-highlight lexers) + (guix build utils) + (ice-9 match) + (ice-9 threads)) + + (define entity->string + (match-lambda + ("rArr" "⇒") + ("hellip" "…") + ("rsquo" "’") + (e (pk 'unknown-entity e) (primitive-exit 2)))) + + (define (concatenate-snippets pieces) + ;; Concatenate PIECES, which contains strings and entities, + ;; replacing entities with their corresponding string. + (let loop ((pieces pieces) + (strings '())) + (match pieces + (() + (string-concatenate-reverse strings)) + (((? string? str) . rest) + (loop rest (cons str strings))) + ((('*ENTITY* "additional" entity) . rest) + (loop rest (cons (entity->string entity) strings))) + ((('span _ lst ...) . rest) ;for <span class="roman"> + (loop (append lst rest) strings)) + (something + (pk 'unsupported-code-snippet something) + (primitive-exit 1))))) + + (define (syntax-highlight sxml) + ;; Recurse over SXML and syntax-highlight code snippets. + (match sxml + (('*TOP* decl body ...) + `(*TOP* ,decl ,@(map syntax-highlight body))) + (('head things ...) + `(head ,@things + (link (@ (rel "stylesheet") + (type "text/css") + (href #$syntax-css-url))))) + (('pre ('@ ('class "lisp")) code-snippet ...) + `(pre (@ (class "lisp")) + ,(highlights->sxml + (highlight lex-scheme + (concatenate-snippets code-snippet))))) + ((tag ('@ attributes ...) body ...) + `(,tag (@ ,@attributes) ,@(map syntax-highlight body))) + ((tag body ...) + `(,tag ,@(map syntax-highlight body))) + ((? string? str) + str))) + + (define (process-html file) + ;; Parse FILE and perform syntax highlighting for its Scheme + ;; snippets. Install the result to #$output. + (format (current-error-port) "processing ~a...~%" file) + (let* ((shtml (call-with-input-file file html->shtml)) + (highlighted (syntax-highlight shtml)) + (base (string-drop file (string-length #$input))) + (target (string-append #$output base))) + (mkdir-p (dirname target)) + (call-with-output-file target + (lambda (port) + (write-shtml-as-html highlighted port))))) + + (define (copy-as-is file) + ;; Copy FILE as is to #$output. + (let* ((base (string-drop file (string-length #$input))) + (target (string-append #$output base))) + (mkdir-p (dirname target)) + (catch 'system-error + (lambda () + (if (eq? 'symlink (stat:type (lstat file))) + (symlink (readlink file) target) + (link file target))) + (lambda args + (let ((errno (system-error-errno args))) + (pk 'error-link file target (strerror errno)) + (primitive-exit 3)))))) + + ;; Install a UTF-8 locale so we can process UTF-8 files. + (setenv "GUIX_LOCPATH" + #+(file-append glibc-utf8-locales "/lib/locale")) + (setlocale LC_ALL "en_US.utf8") + + (n-par-for-each (parallel-job-count) + (lambda (file) + (if (string-suffix? ".html" file) + (process-html file) + (copy-as-is file))) + (find-files #$input)))))) + + (computed-file name build)) + (define* (html-manual source #:key (languages %languages) (version "0.0") (manual "guix") @@ -242,7 +352,10 @@ makeinfo OPTIONS." "/html_node/images")))) '#$languages)))) - (computed-file (string-append manual "-html-manual") build)) + (let* ((name (string-append manual "-html-manual")) + (manual (computed-file name build))) + (syntax-highlighted-html manual + #:name (string-append name "-highlighted")))) (define* (pdf-manual source #:key (languages %languages) (version "0.0") diff --git a/doc/guix.texi b/doc/guix.texi index e940a4f1c9..da84f79490 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5565,8 +5565,8 @@ specified in the @code{uri} field as a @code{git-reference} object; a @example (git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) + (url "https://git.savannah.gnu.org/git/hello.git") + (commit "v2.10")) @end example @end table @@ -6034,6 +6034,29 @@ Packages built with @code{guile-build-system} must provide a Guile package in their @code{native-inputs} field. @end defvr +@defvr {Scheme Variable} julia-build-system +This variable is exported by @code{(guix build-system julia)}. It implements +the build procedure used by @uref{https://julialang.org/, julia} packages, +which essentially is similar to running @command{julia -e 'using Pkg; +Pkg.add(package)'} in an environment where @code{JULIA_LOAD_PATH} contains the +paths to all Julia package inputs. Tests are run not run. + +Julia packages require the source @code{file-name} to be the real name of the +package, correctly capitalized. + +For packages requiring shared library dependencies, you may need to write the +@file{/deps/deps.jl} file manually. It's usually a line of @code{const +variable = /gnu/store/libary.so} for each dependency, plus a void function +@code{check_deps() = nothing}. + +Some older packages that aren't using @file{Package.toml} yet, will require +this file to be created, too. The function @code{julia-create-package-toml} +helps creating the file. You need to pass the outputs and the source of the +package, it's name (the same as the @code{file-name} parameter), the package +uuid, the package version, and a list of dependencies specified by their name +and their uuid. +@end defvr + @defvr {Scheme Variable} minify-build-system This variable is exported by @code{(guix build-system minify)}. It implements a minification procedure for simple JavaScript packages. @@ -8509,8 +8532,13 @@ guix import @var{importer} @var{options}@dots{} @var{importer} specifies the source from which to import package metadata, and @var{options} specifies a package identifier and other -options specific to @var{importer}. Currently, the available -``importers'' are: +options specific to @var{importer}. + +Some of the importers rely on the ability to run the @command{gpgv} command. +For these, GnuPG must be installed and in @code{$PATH}; run @code{guix install +gnupg} if needed. + +Currently, the available ``importers'' are: @table @code @item gnu @@ -8959,7 +8987,10 @@ update the version numbers and source tarball hashes of those package recipes (@pxref{Defining Packages}). This is achieved by downloading each package's latest source tarball and its associated OpenPGP signature, authenticating the downloaded tarball against its signature -using @command{gpg}, and finally computing its hash. When the public +using @command{gpgv}, and finally computing its hash---note that GnuPG must be +installed and in @code{$PATH}; run @code{guix install gnupg} if needed. + +When the public key used to sign the tarball is missing from the user's keyring, an attempt is made to automatically retrieve it from a public key server; when this is successful, the key is added to the user's keyring; otherwise, @@ -9241,6 +9272,31 @@ Parse the @code{source} URL to determine if a tarball from GitHub is autogenerated or if it is a release tarball. Unfortunately GitHub's autogenerated tarballs are sometimes regenerated. +@item archival +@cindex Software Heritage, source code archive +@cindex archival of source code, Software Heritage +Checks whether the package's source code is archived at +@uref{https://www.softwareheritage.org, Software Heritage}. + +When the source code that is not archived comes from a version-control system +(VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a +``save'' request so that it eventually archives it. This ensures that the +source will remain available in the long term, and that Guix can fall back to +Software Heritage should the source code disappear from its original host. +The status of recent ``save'' requests can be +@uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}. + +When source code is a tarball obtained with @code{url-fetch}, simply print a +message when it is not archived. As of this writing, Software Heritage does +not allow requests to save arbitrary tarballs; we are working on ways to +ensure that non-VCS source code is also archived. + +Software Heritage +@uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the +request rate per IP address}. When the limit is reached, @command{guix lint} +prints a message and the @code{archival} checker stops doing anything until +that limit has been reset. + @item cve @cindex security vulnerabilities @cindex CVE, Common Vulnerabilities and Exposures @@ -12620,13 +12676,14 @@ Either @code{#f} or a gexp to execute once the rotation has completed. @end deftp @defvr {Scheme Variable} %default-rotations -Specifies weekly rotation of @var{%rotated-files} and -a couple of other files. +Specifies weekly rotation of @var{%rotated-files} and of +@file{/var/log/guix-daemon.log}. @end defvr @defvr {Scheme Variable} %rotated-files The list of syslog-controlled files to be rotated. By default it is: -@code{'("/var/log/messages" "/var/log/secure")}. +@code{'("/var/log/messages" "/var/log/secure" "/var/log/debug" \ +"/var/log/maillog")}. @end defvr @node Networking Services @@ -14228,6 +14285,12 @@ programs. Defaults to @samp{"lp"}. @end deftypevr + +@deftypevr {@code{files-configuration} parameter} string set-env +Set the specified environment variable to be passed to child processes. + +Defaults to @samp{"variable value"}. +@end deftypevr @end deftypevr @deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level @@ -14248,6 +14311,14 @@ longer required for quotas. Defaults to @samp{#f}. @end deftypevr +@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"}. +@end deftypevr + @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols Specifies which protocols to use for local printer sharing. @@ -14333,7 +14404,7 @@ Defaults to @samp{30}. Specifies what to do when an error occurs. Possible values are @code{abort-job}, which will discard the failed print job; @code{retry-job}, which will retry the job at a later time; -@code{retry-this-job}, which retries the failed job immediately; and +@code{retry-current-job}, which retries the failed job immediately; and @code{stop-printer}, which stops the printer. Defaults to @samp{stop-printer}. @@ -14747,12 +14818,6 @@ the output of the @code{uname} command. @code{Full} reports @code{CUPS Defaults to @samp{Minimal}. @end deftypevr -@deftypevr {@code{cups-configuration} parameter} string set-env -Set the specified environment variable to be passed to child processes. - -Defaults to @samp{"variable value"}. -@end deftypevr - @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen Listens on the specified interfaces for encrypted connections. Valid values are of the form @var{address}:@var{port}, where @var{address} is @@ -21369,12 +21434,12 @@ the @code{"custom-packages"} input, which is the equivalent of (#:branch . "master") (#:no-compile? . #t)) ((#:name . "config") - (#:url . "git://git.example.org/config.git") + (#:url . "https://git.example.org/config.git") (#:load-path . ".") (#:branch . "master") (#:no-compile? . #t)) ((#:name . "custom-packages") - (#:url . "git://git.example.org/custom-packages.git") + (#:url . "https://git.example.org/custom-packages.git") (#:load-path . ".") (#:branch . "master") (#:no-compile? . #t))))))) @@ -25561,6 +25626,7 @@ evaluates to. As an example, @var{file} might contain a definition like this: (environment managed-host-environment-type) (configuration (machine-ssh-configuration (host-name "localhost") + (system "x86_64-linux") (user "alice") (identity "./id_rsa") (port 2222))))) |