Next: O armazém, Previous: Build Utilities, Up: Interface de programação [Contents][Index]
Many programs and libraries look for input data in a search path, a list of directories: shells like Bash look for executables in the command search path, a C compiler looks for .h files in its header search path, the Python interpreter looks for .py files in its search path, the spell checker has a search path for dictionaries, and so on.
Search paths can usually be defined or overridden via environment
variables (see Environment Variables in The GNU C Library Reference
Manual). For example, the search paths mentioned above can be changed by
defining the PATH
, C_INCLUDE_PATH
, PYTHONPATH
(or
GUIX_PYTHONPATH
), and DICPATH
environment variables—you know,
all these something-PATH variables that you need to get right or things
“won’t be found”.
You may have noticed from the command line that Guix “knows” which search
path environment variables should be defined, and how. When you install
packages in your default profile, the file
~/.guix-profile/etc/profile is created, which you can “source” from
the shell to set those variables. Likewise, if you ask guix shell
to create an environment containing Python and NumPy, a Python library, and
if you pass it the --search-paths option, it will tell you about
PATH
and GUIX_PYTHONPATH
(see Invoking guix shell
):
$ guix shell python python-numpy --pure --search-paths export PATH="/gnu/store/…-profile/bin" export GUIX_PYTHONPATH="/gnu/store/…-profile/lib/python3.9/site-packages"
When you omit --search-paths, it defines these environment variables right away, such that Python can readily find NumPy:
$ guix shell python python-numpy -- python3 Python 3.9.6 (default, Jan 1 1970, 00:00:01) [GCC 10.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import numpy >>> numpy.version.version '1.20.3'
For this to work, the definition of the python
package
declares the search path it cares about and its associated
environment variable, GUIX_PYTHONPATH
. It looks like this:
(package
(name "python")
(version "3.9.9")
;; some fields omitted...
(native-search-paths
(list (search-path-specification
(variable "GUIX_PYTHONPATH")
(files (list "lib/python/3.9/site-packages"))))))
What this native-search-paths
field says is that, when the
python
package is used, the GUIX_PYTHONPATH
environment
variable must be defined to include all the
lib/python/3.9/site-packages sub-directories encountered in its
environment. (The native-
bit means that, if we are in a
cross-compilation environment, only native inputs may be added to the search
path; see search-paths
.) In the NumPy example
above, the profile where python
appears contains exactly one such
sub-directory, and GUIX_PYTHONPATH
is set to that. When there are
several lib/python/3.9/site-packages—this is the case in package
build environments—they are all added to GUIX_PYTHONPATH
, separated
by colons (:
).
Nota: Notice that
GUIX_PYTHONPATH
is specified as part of the definition of thepython
package, and not as part of that ofpython-numpy
. This is because this environment variable “belongs” to Python, not NumPy: Python actually reads the value of that variable and honors it.Corollary: if you create a profile that does not contain
python
,GUIX_PYTHONPATH
will not be defined, even if it contains packages that provide .py files:$ guix shell python-numpy --search-paths --pure export PATH="/gnu/store/…-profile/bin"This makes a lot of sense if we look at this profile in isolation: no software in this profile would read
GUIX_PYTHONPATH
.
Of course, there are many variations on that theme: some packages honor more
than one search path, some use separators other than colon, some accumulate
several directories in their search path, and so on. A more complex example
is the search path of libxml2: the value of the XML_CATALOG_FILES
environment variable is space-separated, it must contain a list of
catalog.xml files (not directories), which are to be found in
xml sub-directories—nothing less. The search path specification
looks like this:
(package
(name "libxml2")
;; some fields omitted
(native-search-paths
(list (search-path-specification
(variable "XML_CATALOG_FILES")
(separator " ")
(files '("xml"))
(file-pattern "^catalog\\.xml$")
(file-type 'regular)))))
Worry not, search path specifications are usually not this tricky.
The (guix search-paths)
module defines the data type of search path
specifications and a number of helper procedures. Below is the reference of
search path specifications.
The data type for search path specifications.
variable
The name of the environment variable for this search path (a string).
files
The list of sub-directories (strings) that should be added to the search path.
separator
(default: ":"
)The string used to separate search path components.
As a special case, a separator
value of #f
specifies a
“single-component search path”—in other words, a search path that cannot
contain more than one element. This is useful in some cases, such as the
SSL_CERT_DIR
variable (honored by OpenSSL, cURL, and a few other
packages) or the ASPELL_DICT_DIR
variable (honored by the GNU Aspell
spell checker), both of which must point to a single directory.
file-type
(default: 'directory
)The type of file being matched—'directory
or 'regular
,
though it can be any symbol returned by stat:type
(see stat
in GNU Guile Reference Manual).
In the libxml2 example above, we would match regular files; in the Python example, we would match directories.
file-pattern
(default: #f
)This must be either #f
or a regular expression specifying files to be
matched within the sub-directories specified by the files
field.
Again, the libxml2 example shows a situation where this is needed.
Some search paths are not tied by a single package but to many packages. To
reduce duplications, some of them are pre-defined in (guix
search-paths)
.
These two search paths indicate where X.509 certificates can be found (see Certificados X.509).
These pre-defined search paths can be used as in the following example:
(package
(name "curl")
;; some fields omitted ...
(native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))
How do you turn search path specifications on one hand and a bunch of
directories on the other hand in a set of environment variable definitions?
That’s the job of evaluate-search-paths
.
search-path specifications, for directories, a list of directory names, and return a list of specification/value pairs. Use getenv to determine the current settings and report only settings not already effective.
The (guix profiles)
provides a higher-level helper procedure,
load-profile
, that sets the environment variables of a profile.
Next: O armazém, Previous: Build Utilities, Up: Interface de programação [Contents][Index]