diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 145 |
1 files changed, 98 insertions, 47 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 0cdc528c1c..585baf358f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5776,7 +5776,7 @@ a package collection. This involves the following steps: @enumerate @item -Channels live in a Git repository so the first step, when creating a +A channel lives in a Git repository so the first step, when creating a channel, is to create its repository: @example @@ -5790,7 +5790,7 @@ The next step is to create files containing package modules (@pxref{Package Modules}), each of which will contain one or more package definitions (@pxref{Defining Packages}). A channel can provide things other than packages, such as build systems or services; we're -using packages as most common use case. +using packages as it's the most common use case. For example, Alice might want to provide a module called @code{(alice packages greetings)} that will provide her favorite ``hello world'' @@ -5815,7 +5815,7 @@ that. @item With this first module in place, the next step is to test the packages it provides. This can be done with @command{guix build}, which needs to -be fold to look for modules in the Git checkout. For example, assuming +be told to look for modules in the Git checkout. For example, assuming @code{(alice packages greetings)} provides a package called @code{hi-from-alice}, Alice will run this command from the Git checkout: @@ -5856,7 +5856,7 @@ example, @code{(alice packages greetings)} will automatically be found by the @command{guix} command. @end enumerate -Voilà! +Voilà! @c What follows stems from discussions at @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as @@ -10001,17 +10001,30 @@ used to build TeX packages in batch mode with a specified engine. The build system sets the @env{TEXINPUTS} variable to find all TeX source files in the inputs. -By default it runs @code{luatex} on all files ending on @code{ins}. A -different engine and format can be specified with the -@code{#:tex-format} argument. Different build targets can be specified -with the @code{#:build-targets} argument, which expects a list of file -names. The build system adds only @code{texlive-bin} and -@code{texlive-latex-base} (both from @code{(gnu packages tex}) to the -inputs. Both can be overridden with the arguments @code{#:texlive-bin} -and @code{#:texlive-latex-base}, respectively. +By default it tries to run @code{luatex} on all @file{.ins} files, and +if it fails to find any, on all @file{.dtx} files. A different engine +and format can be specified with, respectively, the @code{#:tex-engine} +and @code{#:tex-format} arguments. Different build targets can be +specified with the @code{#:build-targets} argument, which expects a list +of file names. -The @code{#:tex-directory} parameter tells the build system where to -install the built files under the texmf tree. +It also generates font metrics (i.e., @file{.tfm} files) out of Metafont +files whenever possible. Likewise, it can also create TeX formats +(i.e., @file{.fmt} files) listed in the @code{#:create-formats} +argument, and generate a symbolic link from @file{bin/} directory to any +script located in located in @file{texmf-dist/scripts/}, provided its +file name is listed in @code{#:link-scripts} argument. + +The build system adds @code{texlive-bin} from @code{(gnu packages tex)} +to the native inputs. It can be overridden with the +@code{#:texlive-bin} argument. + +The package @code{texlive-latex-bin}, from the same module, contains +most of the tools for building TeX Live packages; for convenience, it is +also added by default to the native inputs. However, this can be +troublesome when building a dependency of @code{texlive-latex-bin} +itself. In this particular situation, the @code{#:texlive-latex-bin?} +argument should be set to @code{#f}. @end defvar @defvar ruby-build-system @@ -14075,9 +14088,10 @@ TeX packages that are part of the @uref{https://www.tug.org/texlive/, TeX Live distribution}. Information about the package is obtained from the TeX Live package -database, a plain text file that is included in the @code{texlive-bin} -package. The source code is downloaded from possibly multiple locations -in the SVN repository of the Tex Live project. +database, a plain text file that is included in the +@code{texlive-scripts} package. The source code is downloaded from +possibly multiple locations in the SVN repository of the Tex Live +project. The command command below imports metadata for the @code{fontspec} TeX package: @@ -32938,12 +32952,25 @@ The IP addresses to be assigned to the above interface. @item @code{port} (default: @code{51820}) The port on which to listen for incoming connections. -@item @code{dns} (default: @code{#f}) +@item @code{dns} (default: @code{'())}) The DNS server(s) to announce to VPN clients via DHCP. +@item @code{monitor-ips?} (default: @code{#f}) +@cindex Dynamic IP, with Wireguard +@cindex dyndns, usage with Wireguard +Whether to monitor the resolved Internet addresses (IPs) of the +endpoints of the configured peers, resetting the peer endpoints using an +IP address that no longer correspond to their freshly resolved host +name. Set this to @code{#t} if one or more endpoints use host names +provided by a dynamic DNS service to keep the sessions alive. + +@item @code{monitor-ips-internal} (default: @code{'(next-minute (range 0 60 5))}) +The time interval at which the IP monitoring job should run, provided as +an mcron time specification (@pxref{Guile Syntax,,,mcron}). + @item @code{private-key} (default: @code{"/etc/wireguard/private.key"}) -The private key file for the interface. It is automatically generated if -the file does not exist. +The private key file for the interface. It is automatically generated +if the file does not exist. @item @code{peers} (default: @code{'()}) The authorized peers on this interface. This is a list of @@ -35159,9 +35186,9 @@ Its value must be a @code{virtlog-configuration}. @end lisp @end defvar -@deftypevar {@code{libvirt} parameter} package libvirt +@deftypevr {@code{libvirt} parameter} package libvirt Libvirt package. -@end deftypevar +@end deftypevr @deftypevr {@code{virtlog-configuration} parameter} integer log-level Logging level. 4 errors, 3 warnings, 2 information, 1 debug. @@ -40078,7 +40105,29 @@ For example: @item @code{multiboot-arguments} (default: @code{'()}) The list of extra command-line arguments for the multiboot-kernel. -@item @code{multiboot-modules} (default: @code{'()}) +For example, when running in QEMU it can be useful to use a text-based +console (use options @option{--nographic} @option{--serial mon:stdio}): + +@lisp +'("console=com0") +@end lisp + +To use the new and still experimental +@uref{https://darnassus.sceen.net/~hurd-web/rump_kernel/, rumpdisk +user-level disk driver} instead of GNU@tie{}Mach's in-kernel IDE driver, +set @code{kernel-arguments} to: + +@lisp +'("noide") +@end lisp + +Of course, these options can be combined: + +@lisp +'("console=com0" "noide") +@end lisp + ++@item @code{multiboot-modules} (default: @code{'()}) The list of commands for loading Multiboot modules. For example: @lisp @@ -45371,14 +45420,19 @@ single @TeX{} Live package} (more than 7,000 of them), but it is huge (more than 4@tie{}GiB for a single package!). @item -The ``modular'' @code{texlive-} packages: you install -@code{texlive-base}, which provides core functionality and the main +The ``modular'' @samp{texlive-} packages: you start off with +a combination of @TeX{} Live @dfn{collections} and +@dfn{schemes}---``meta-packages'' such as +@code{texlive-collection-fontsrecommended}, or +@code{texlive-collection-context}, that provide the set of packages +needed in this particular domain, schemes being the name for collections +of such collections. This grants you core functionality and the main commands---@command{pdflatex}, @command{dvips}, @command{luatex}, -@command{mf}, etc.---together with individual packages that provide just -the features you need---@code{texlive-listings} for the -@code{listings} package, @code{texlive-hyperref} for @code{hyperref}, -@code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ, -and so on. +@command{mf}, etc. You can then complete your selection with additional +collections or individual packages that provide just the features you +need---@code{texlive-listings} for the @code{listings} package, +@code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ, and +so on. @end itemize We recommend using the modular package set because it is much less @@ -45386,29 +45440,29 @@ resource-hungry. To build your documents, you would use commands such as: @example -guix shell texlive-base texlive-wrapfig \ - texlive-hyperref texlive-cm-super -- pdflatex doc.tex +guix shell texlive-scheme-basic texlive-cm-super -- pdflatex doc.tex @end example You can quickly end up with unreasonably long command lines though. The -solution is to instead write a manifest, for example like this one: +solution is to instead write a manifest, for example like this one, +which would probably be a reasonable starting point for a French +@LaTeX{} user: @lisp (specifications->manifest '("rubber" - "texlive-base" - "texlive-wrapfig" + "texlive-scheme-basic" + "texlive-collection-latexrecommended" + "texlive-collection-fontsrecommended" - "texlive-microtype" - "texlive-listings" "texlive-hyperref" + "texlive-babel-french" ;; PGF/TikZ "texlive-pgf" - ;; Additional fonts. - "texlive-cm-super" "texlive-amsfonts" - "texlive-times" "texlive-helvetic" "texlive-courier")) + ;; Additional font. + "texlive-kpfonts")) @end lisp You can then pass it to any command with the @option{-m} option: @@ -45417,12 +45471,9 @@ You can then pass it to any command with the @option{-m} option: guix shell -m manifest.scm -- pdflatex doc.tex @end example -@xref{Writing Manifests}, for more on -manifests. In the future, we plan to provide packages for @TeX{} Live -@dfn{collections}---``meta-packages'' such as @code{fontsrecommended}, -@code{humanities}, or @code{langarabic} that provide the set of packages -needed in this particular domain. That will allow you to list fewer -packages. +@xref{Writing Manifests}, for more on manifests. In the future, we plan +to provide more collections and schemes. That will allow you to list +fewer packages. The main difficulty here is that using the modular package set forces you to select precisely the packages that you need. You can use @@ -45458,7 +45509,7 @@ you can search the @TeX{} Live package database using the @command{tlmgr} command: @example -$ guix shell texlive-base -- tlmgr info phvr7t +$ guix shell texlive-bin -- tlmgr info phvr7t tlmgr: cannot find package phvr7t, searching for other matches: Packages containing `phvr7t' in their title/description: |