summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2020-05-07 11:42:12 +0200
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2020-05-07 11:42:12 +0200
commit7ebe3163d655c4def54e963401de00627be4124a (patch)
treefbb665c0930a57c3d20c4f917878fffcdd1f43e7
parentf96ddb60962703eaae5433399905b9d81a99ea13 (diff)
doc: Use @env for environment variables.
* doc/guix.texi (Binary Installation): (Build Environment Setup): (Invoking guix-daemon): (Application Setup): (After System Installation): (Invoking guix package): (Proxy Settings): (Invoking guix environment): (Packages for C Development): (Package Modules): (Build Systems): (The Store): (Common Build Options): (Invoking guix download): (Invoking guix refresh): (Using the Configuration System): (Locales): (Base Services): (Networking Services): (Sound Services): (Continuous Integration): (PAM Mount Service): (X.509 Certificates): Use @env instead of @code for environment variables.
-rw-r--r--doc/guix.texi114
1 files changed, 57 insertions, 57 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 5eb7f9d645..557809f0d2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -633,7 +633,7 @@ where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
~root/.config/guix/current
@end example
-Source @file{etc/profile} to augment @code{PATH} and other relevant
+Source @file{etc/profile} to augment @env{PATH} and other relevant
environment variables:
@example
@@ -1004,15 +1004,15 @@ a writable @file{/tmp} directory.
@end itemize
You can influence the directory where the daemon stores build trees
-@i{via} the @code{TMPDIR} environment variable. However, the build tree
+@i{via} the @env{TMPDIR} environment variable. However, the build tree
within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
-This way, the value of @code{TMPDIR} does not leak inside build
+This way, the value of @env{TMPDIR} does not leak inside build
environments, which avoids discrepancies in cases where build processes
capture the name of their build tree.
@vindex http_proxy
-The daemon also honors the @code{http_proxy} environment variable for
+The daemon also honors the @env{http_proxy} environment variable for
HTTP downloads it performs, be it for fixed-output derivations
(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}).
@@ -1350,7 +1350,7 @@ etc. This helps achieve reproducible builds (@pxref{Features}).
When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
-its @code{TMPDIR} environment variable. This directory is shared with
+its @env{TMPDIR} environment variable. This directory is shared with
the container for the duration of the build, though within the container,
the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
@@ -1413,7 +1413,7 @@ The default value is @code{0}, but it may be overridden by clients, such
as the @option{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).
-The effect is to define the @code{NIX_BUILD_CORES} environment variable
+The effect is to define the @env{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
@@ -1569,8 +1569,8 @@ Listen for TCP connections on the network interface corresponding to
This option can be repeated multiple times, in which case
@command{guix-daemon} accepts connections on all the specified
endpoints. Users can tell client commands what endpoint to connect to
-by setting the @code{GUIX_DAEMON_SOCKET} environment variable
-(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).
+by setting the @env{GUIX_DAEMON_SOCKET} environment variable
+(@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).
@quotation Note
The daemon protocol is @emph{unauthenticated and unencrypted}. Using
@@ -1602,7 +1602,7 @@ get everything in place. Here are some of them.
@vindex GUIX_LOCPATH
Packages installed @i{via} Guix will not use the locale data of the
host system. Instead, you must first install one of the locale packages
-available with Guix and then define the @code{GUIX_LOCPATH} environment
+available with Guix and then define the @env{GUIX_LOCPATH} environment
variable:
@example
@@ -1615,19 +1615,19 @@ locales supported by the GNU@tie{}libc and weighs in at around
917@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
-The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
-(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
+The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
+(@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
Manual}). There are two important differences though:
@enumerate
@item
-@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
-provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
+@env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
+provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you
to make sure the programs of the foreign distro will not end up loading
incompatible locale data.
@item
-libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
+libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
@code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
should your Guix profile contain a mixture of programs linked against
different libc version, each libc version will only try to load locale
@@ -1760,7 +1760,7 @@ information.
When you install Emacs packages with Guix, the Elisp files are placed
under the @file{share/emacs/site-lisp/} directory of the profile in
which they are installed. The Elisp libraries are made available to
-Emacs through the @code{EMACSLOADPATH} environment variable, which is
+Emacs through the @env{EMACSLOADPATH} environment variable, which is
set when installing Emacs itself.
Additionally, autoload definitions are automatically evaluated at the
@@ -2456,7 +2456,7 @@ your system includes the latest security updates (@pxref{Security Updates}).
@quotation Note
@cindex sudo vs. @command{guix pull}
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
+@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
The difference matters here, because @command{guix pull} updates
@@ -2733,7 +2733,7 @@ passes it @i{via} the @option{--manifest} option
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}. This symlink always points to the
current generation of the user's default profile. Thus, users can add
-@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
+@file{$HOME/.guix-profile/bin} to their @env{PATH} environment
variable, and so on.
@cindex search paths
If you are not using Guix System, consider adding the
@@ -2977,7 +2977,7 @@ $ guix package -p bar -i guile-json
$ guix package -p foo -p bar --search-paths
@end example
-The last command above reports about the @code{GUILE_LOAD_PATH}
+The last command above reports about the @env{GUILE_LOAD_PATH}
variable, even though, taken individually, neither @file{foo} nor
@file{bar} would lead to that recommendation.
@@ -3216,7 +3216,7 @@ Options}). It also supports package transformation options, such as
@option{--with-source} (@pxref{Package Transformation Options}).
However, note that package transformations are lost when upgrading; to
preserve transformations across upgrades, you should define your own
-package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
+package variant in a Guile module and add it to @env{GUIX_PACKAGE_PATH}
(@pxref{Defining Packages}).
@node Substitutes
@@ -3377,10 +3377,10 @@ authenticating bindings between domain names and public keys.)
@vindex http_proxy
Substitutes are downloaded over HTTP or HTTPS.
-The @code{http_proxy} environment
+The @env{http_proxy} environment
variable can be set in the environment of @command{guix-daemon} and is
honored for downloads of substitutes. Note that the value of
-@code{http_proxy} in the environment where @command{guix build},
+@env{http_proxy} in the environment where @command{guix build},
@command{guix package}, and other client commands are run has
@emph{absolutely no effect}.
@@ -4802,7 +4802,7 @@ Another typical use case for containers is to run security-sensitive
applications such as a web browser. To run Eolie, we must expose and
share some files and directories; we include @code{nss-certs} and expose
@file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
-the @code{DISPLAY} environment variable since containerized graphical
+the @env{DISPLAY} environment variable since containerized graphical
applications won't display without it.
@example
@@ -4927,9 +4927,9 @@ guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
@end example
This example runs @command{mpirun} in a context where the only environment
-variables defined are @code{PATH}, environment variables whose name starts
-with @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME},
-@code{USER}, etc.)
+variables defined are @env{PATH}, environment variables whose name starts
+with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
+@env{USER}, etc.)
@item --search-paths
Display the environment variable definitions that make up the
@@ -5372,7 +5372,7 @@ The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
passed to the linker, add corresponding @code{-rpath} arguments, and
invoke the actual linker with this new set of arguments. You can instruct the
wrapper to refuse to link against libraries not in the store by setting the
-@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
+@env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
@@ -5445,7 +5445,7 @@ names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
name and module name must match. For instance, the @code{(my-packages
emacs)} module must be stored in a @file{my-packages/emacs.scm} file
relative to the load path specified with @option{--load-path} or
-@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
+@env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
these package definitions visible to the user interfaces:
@@ -5453,7 +5453,7 @@ these package definitions visible to the user interfaces:
@item
By adding the directory containing your package modules to the search path
with the @code{-L} flag of @command{guix package} and other commands
-(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
+(@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
environment variable described below.
@item
@@ -5463,7 +5463,7 @@ modules. @xref{Channels}, for more information on how to define and use
channels.
@end enumerate
-@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
+@env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
@defvr {Environment Variable} GUIX_PACKAGE_PATH
This is a colon-separated list of directories to search for additional
@@ -6418,7 +6418,7 @@ The phase @code{glib-or-gtk-wrap} ensures that programs in
@file{bin/} are able to find GLib ``schemas'' and
@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
modules}. This is achieved by wrapping the programs in launch scripts
-that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
+that appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH}
environment variables.
It is possible to exclude specific package outputs from that wrapping
@@ -6533,7 +6533,7 @@ Note that most OCaml packages assume they will be installed in the same
directory as OCaml, which is not what we want in guix. In particular, they
will install @file{.so} files in their module's directory, which is usually
fine because it is in the OCaml compiler directory. In guix though, these
-libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
+libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
@file{.so} libraries should be installed.
@end defvr
@@ -6545,7 +6545,7 @@ packages, which consists in running @code{python setup.py build} and
then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
For packages that install stand-alone Python programs under @code{bin/},
-it takes care of wrapping these programs so that their @code{PYTHONPATH}
+it takes care of wrapping these programs so that their @env{PYTHONPATH}
environment variable points to all the Python libraries they depend on.
Which Python package is used to perform the build can be specified with
@@ -6619,10 +6619,10 @@ This phase is added after the @code{install} phase.
@defvr {Scheme Variable} r-build-system
This variable is exported by @code{(guix build-system r)}. It
implements the build procedure used by @uref{https://r-project.org, R}
-packages, which essentially is little more than running @code{R CMD
+packages, which essentially is little more than running @samp{R CMD
INSTALL --library=/gnu/store/@dots{}} in an environment where
-@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
-are run after installation using the R function
+@env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
+run after installation using the R function
@code{tools::testInstalledPackage}.
@end defvr
@@ -6647,7 +6647,7 @@ with @code{#:zef} or removed by passing @code{#f} to the
@defvr {Scheme Variable} texlive-build-system
This variable is exported by @code{(guix build-system texlive)}. It is
used to build TeX packages in batch mode with a specified engine. The
-build system sets the @code{TEXINPUTS} variable to find all TeX source
+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
@@ -6900,7 +6900,7 @@ The @code{(guix store)} module provides procedures to connect to the
daemon, and to perform RPCs. These are described below. By default,
@code{open-connection}, and thus all the @command{guix} commands,
connect to the local daemon or to the URI specified by the
-@code{GUIX_DAEMON_SOCKET} environment variable.
+@env{GUIX_DAEMON_SOCKET} environment variable.
@defvr {Environment Variable} GUIX_DAEMON_SOCKET
When set, the value of this variable should be a file name or a URI
@@ -6940,7 +6940,7 @@ instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
@cindex SSH access to build daemons
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
+@command{guile} binary in @env{PATH} on the destination machine. It
supports public key and GSSAPI authentication. A typical URL might look
like this:
@@ -8302,7 +8302,7 @@ build issues.
This option implies @option{--no-offload}, and it has no effect when
connecting to a remote daemon with a @code{guix://} URI (@pxref{The
-Store, the @code{GUIX_DAEMON_SOCKET} variable}).
+Store, the @env{GUIX_DAEMON_SOCKET} variable}).
@item --keep-going
@itemx -k
@@ -8413,7 +8413,7 @@ derivations)} module.
In addition to options explicitly passed on the command line,
@command{guix build} and other @command{guix} commands that support
-building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
+building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
@defvr {Environment Variable} GUIX_BUILD_OPTIONS
Users can define this variable to a list of command line options that
@@ -8949,7 +8949,7 @@ GnuTLS-Guile}, for more information.
@command{guix download} verifies HTTPS server certificates by loading
the certificates of X.509 authorities from the directory pointed to by
-the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
+the @env{SSL_CERT_DIR} environment variable (@pxref{X.509
Certificates}), unless @option{--no-check-certificate} is used.
The following options are available:
@@ -9782,7 +9782,7 @@ GitHub will eventually refuse to answer any further API requests. By
default 60 API requests per hour are allowed, and a full refresh on all
GitHub packages in Guix requires more than this. Authentication with
GitHub through the use of an API token alleviates these limits. To use
-an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
+an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
token procured from @uref{https://github.com/settings/tokens} or
otherwise.
@@ -11098,7 +11098,7 @@ configuration options.
@vindex %base-packages
The @code{packages} field lists packages that will be globally visible
-on the system, for all user accounts---i.e., in every user's @code{PATH}
+on the system, for all user accounts---i.e., in every user's @env{PATH}
environment variable---in addition to the per-user profiles
(@pxref{Invoking guix package}). The @code{%base-packages} variable
provides all the tools one would expect for basic user and administrator
@@ -12123,8 +12123,8 @@ The compiled locale definitions are available at
@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
version, which is the default location where the GNU@tie{}libc provided
by Guix looks for locale data. This can be overridden using the
-@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
-@code{LOCPATH} and locale packages}).
+@env{LOCPATH} environment variable (@pxref{locales-and-locpath,
+@env{LOCPATH} and locale packages}).
The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module. Details are given below.
@@ -12182,7 +12182,7 @@ read locale data produced with libc 2.22; worse, that program
data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
the incompatible locale data, which is already an improvement.}.
Similarly, a program linked against libc 2.22 can read most, but not
-all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
+all, of the locale data from libc 2.21 (specifically, @env{LC_COLLATE}
data is incompatible); thus calls to @code{setlocale} may fail, but
programs will not abort.
@@ -12192,8 +12192,8 @@ be using a libc version different from the one the system administrator
used to build the system-wide locale data.
Fortunately, unprivileged users can also install their own locale data
-and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
-@code{GUIX_LOCPATH} and locale packages}).
+and define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
+@env{GUIX_LOCPATH} and locale packages}).
Still, it is best if the system-wide locale data at
@file{/run/current-system/locale} is built for all the libc versions
@@ -12480,7 +12480,7 @@ A string containing a comma-separated list of one or more baud rates, in
descending order.
@item @code{term} (default: @code{#f})
-A string containing the value used for the @code{TERM} environment
+A string containing the value used for the @env{TERM} environment
variable.
@item @code{eight-bits?} (default: @code{#f})
@@ -14313,7 +14313,7 @@ List of strings describing which environment variables may be exported.
Each string gets on its own line. See the @code{AcceptEnv} option in
@code{man sshd_config}.
-This example allows ssh-clients to export the @code{COLORTERM} variable.
+This example allows ssh-clients to export the @env{COLORTERM} variable.
It is set by terminal emulators, which support colors. You can use it in
your shell's resource file to enable colors for the prompt and commands
if this variable is set.
@@ -16405,8 +16405,8 @@ via @code{pulseaudio-configuration}, see below.
@quotation Warning
This service overrides per-user configuration files. If you want
PulseAudio to honor configuraton files in @file{~/.config/pulse} you
-have to unset the environment variables @code{PULSE_CONFIG} and
-@code{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
+have to unset the environment variables @env{PULSE_CONFIG} and
+@env{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
@end quotation
@quotation Warning
@@ -22713,7 +22713,7 @@ To add build jobs, you have to set the @code{specifications} field of the
configuration. Here is an example of a service that polls the Guix repository
and builds the packages from a manifest. Some of the packages are defined in
the @code{"custom-packages"} input, which is the equivalent of
-@code{GUIX_PACKAGE_PATH}.
+@env{GUIX_PACKAGE_PATH}.
@lisp
(define %cuirass-specs
@@ -25530,7 +25530,7 @@ for anyone at login:
Some @code{volume} elements must be added to automatically mount volumes
at login. Here's an example allowing the user @code{alice} to mount her
-encrypted @code{HOME} directory and allowing the user @code{bob} to mount
+encrypted @env{HOME} directory and allowing the user @code{bob} to mount
the partition where he stores his data:
@lisp
@@ -26181,10 +26181,10 @@ Unprivileged users, including users of Guix on a foreign distro,
can also install their own certificate package in
their profile. A number of environment variables need to be defined so
that applications and libraries know where to find them. Namely, the
-OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
+OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
variables. Some applications add their own environment variables; for
instance, the Git version control system honors the certificate bundle
-pointed to by the @code{GIT_SSL_CAINFO} environment variable. Thus, you
+pointed to by the @env{GIT_SSL_CAINFO} environment variable. Thus, you
would typically run something like:
@example
@@ -26194,7 +26194,7 @@ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
export GIT_SSL_CAINFO="$SSL_CERT_FILE"
@end example
-As another example, R requires the @code{CURL_CA_BUNDLE} environment
+As another example, R requires the @env{CURL_CA_BUNDLE} environment
variable to point to a certificate bundle, so you would have to run
something like this: