224 lines
15 KiB
HTML
224 lines
15 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<!-- This manual documents Guile version 3.0.10.
|
||
|
|
|
||
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
||
|
|
Inc.
|
||
|
|
|
||
|
|
Copyright (C) 2021 Maxime Devos
|
||
|
|
|
||
|
|
Copyright (C) 2024 Tomas Volf
|
||
|
|
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with no
|
||
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
|
|
copy of the license is included in the section entitled "GNU Free
|
||
|
|
Documentation License." -->
|
||
|
|
<title>Load Paths (Guile Reference Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Load Paths (Guile Reference Manual)">
|
||
|
|
<meta name="keywords" content="Load Paths (Guile Reference Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content=".texi2any-real">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Read_002fLoad_002fEval_002fCompile.html" rel="up" title="Read/Load/Eval/Compile">
|
||
|
|
<link href="Character-Encoding-of-Source-Files.html" rel="next" title="Character Encoding of Source Files">
|
||
|
|
<link href="Loading.html" rel="prev" title="Loading">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
span:hover a.copiable-link {visibility: visible}
|
||
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="subsection-level-extent" id="Load-Paths">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Character-Encoding-of-Source-Files.html" accesskey="n" rel="next">Character Encoding of Source Files</a>, Previous: <a href="Loading.html" accesskey="p" rel="prev">Loading Scheme Code from File</a>, Up: <a href="Read_002fLoad_002fEval_002fCompile.html" accesskey="u" rel="up">Reading and Evaluating Scheme Code</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<h4 class="subsection" id="Load-Paths-1"><span>6.16.8 Load Paths<a class="copiable-link" href="#Load-Paths-1"> ¶</a></span></h4>
|
||
|
|
|
||
|
|
<p>The procedure in the previous section look for Scheme code in the file
|
||
|
|
system at specific location. Guile also has some procedures to search
|
||
|
|
the load path for code.
|
||
|
|
</p>
|
||
|
|
<dl class="first-defvr first-defvar-alias-first-defvr">
|
||
|
|
<dt class="defvr defvar-alias-defvr" id="index-_0025load_002dpath"><span class="category-def">Variable: </span><span><strong class="def-name">%load-path</strong><a class="copiable-link" href="#index-_0025load_002dpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>List of directories which should be searched for Scheme modules and
|
||
|
|
libraries. When Guile starts up, <code class="code">%load-path</code> is initialized to
|
||
|
|
the default load path <code class="code">(list (%library-dir) (%site-dir)
|
||
|
|
(%global-site-dir) (%package-data-dir))</code>. The <code class="env">GUILE_LOAD_PATH</code>
|
||
|
|
environment variable can be used to prepend or append additional
|
||
|
|
directories (see <a class="pxref" href="Environment-Variables.html">Environment Variables</a>).
|
||
|
|
</p>
|
||
|
|
<p>See <a class="xref" href="Build-Config.html">Configuration, Build and Installation</a>, for more on <code class="code">%site-dir</code> and related
|
||
|
|
procedures.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-load_002dfrom_002dpath"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">load-from-path</strong> <var class="def-var-arguments">filename</var><a class="copiable-link" href="#index-load_002dfrom_002dpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Similar to <code class="code">load</code>, but searches for <var class="var">filename</var> in the load
|
||
|
|
paths. Preferentially loads a compiled version of the file, if it is
|
||
|
|
available and up-to-date.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<p>A user can extend the load path by calling <code class="code">add-to-load-path</code>.
|
||
|
|
</p>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-add_002dto_002dload_002dpath"><span class="category-def">Scheme Syntax: </span><span><strong class="def-name">add-to-load-path</strong> <var class="def-var-arguments">dir</var><a class="copiable-link" href="#index-add_002dto_002dload_002dpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Add <var class="var">dir</var> to the load path.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<p>For example, a script might include this form to add the directory that
|
||
|
|
it is in to the load path:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(add-to-load-path (dirname (current-filename)))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>It’s better to use <code class="code">add-to-load-path</code> than to modify
|
||
|
|
<code class="code">%load-path</code> directly, because <code class="code">add-to-load-path</code> takes care
|
||
|
|
of modifying the path both at compile-time and at run-time.
|
||
|
|
</p>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-primitive_002dload_002dpath"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">primitive-load-path</strong> <var class="def-var-arguments">filename [exception-on-not-found]</var><a class="copiable-link" href="#index-primitive_002dload_002dpath"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fprimitive_005fload_005fpath"><span class="category-def">C Function: </span><span><strong class="def-name">scm_primitive_load_path</strong> <var class="def-var-arguments">(filename)</var><a class="copiable-link" href="#index-scm_005fprimitive_005fload_005fpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Search <code class="code">%load-path</code> for the file named <var class="var">filename</var> and
|
||
|
|
load it into the top-level environment. If <var class="var">filename</var> is a
|
||
|
|
relative pathname and is not found in the list of search paths,
|
||
|
|
an error is signaled. Preferentially loads a compiled version of the
|
||
|
|
file, if it is available and up-to-date.
|
||
|
|
</p>
|
||
|
|
<p>If <var class="var">filename</var> is a relative pathname and is not found in the list of
|
||
|
|
search paths, one of three things may happen, depending on the optional
|
||
|
|
second argument, <var class="var">exception-on-not-found</var>. If it is <code class="code">#f</code>,
|
||
|
|
<code class="code">#f</code> will be returned. If it is a procedure, it will be called
|
||
|
|
with no arguments. (This allows a distinction to be made between
|
||
|
|
exceptions raised by loading a file, and exceptions related to the
|
||
|
|
loader itself.) Otherwise an error is signaled.
|
||
|
|
</p>
|
||
|
|
<p>For compatibility with Guile 1.8 and earlier, the C function takes only
|
||
|
|
one argument, which can be either a string (the file name) or an
|
||
|
|
argument list.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-_0025search_002dload_002dpath"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">%search-load-path</strong> <var class="def-var-arguments">filename</var><a class="copiable-link" href="#index-_0025search_002dload_002dpath"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fsys_005fsearch_005fload_005fpath"><span class="category-def">C Function: </span><span><strong class="def-name">scm_sys_search_load_path</strong> <var class="def-var-arguments">(filename)</var><a class="copiable-link" href="#index-scm_005fsys_005fsearch_005fload_005fpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Search <code class="code">%load-path</code> for the file named <var class="var">filename</var>, which must
|
||
|
|
be readable by the current user. If <var class="var">filename</var> is found in the list
|
||
|
|
of paths to search or is an absolute pathname, return its full pathname.
|
||
|
|
Otherwise, return <code class="code">#f</code>. Filenames may have any of the optional
|
||
|
|
extensions in the <code class="code">%load-extensions</code> list; <code class="code">%search-load-path</code>
|
||
|
|
will try each extension automatically.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-defvr first-defvar-alias-first-defvr">
|
||
|
|
<dt class="defvr defvar-alias-defvr" id="index-_0025load_002dextensions"><span class="category-def">Variable: </span><span><strong class="def-name">%load-extensions</strong><a class="copiable-link" href="#index-_0025load_002dextensions"> ¶</a></span></dt>
|
||
|
|
<dd><p>A list of default file extensions for files containing Scheme code.
|
||
|
|
<code class="code">%search-load-path</code> tries each of these extensions when looking for
|
||
|
|
a file to load. By default, <code class="code">%load-extensions</code> is bound to the
|
||
|
|
list <code class="code">("" ".scm")</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<p>As mentioned above, when Guile searches the <code class="code">%load-path</code> for a
|
||
|
|
source file, it will also search the <code class="code">%load-compiled-path</code> for a
|
||
|
|
corresponding compiled file. If the compiled file is as new or newer
|
||
|
|
than the source file, it will be loaded instead of the source file,
|
||
|
|
using <code class="code">load-compiled</code>.
|
||
|
|
</p>
|
||
|
|
<dl class="first-defvr first-defvar-alias-first-defvr">
|
||
|
|
<dt class="defvr defvar-alias-defvr" id="index-_0025load_002dcompiled_002dpath"><span class="category-def">Variable: </span><span><strong class="def-name">%load-compiled-path</strong><a class="copiable-link" href="#index-_0025load_002dcompiled_002dpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Like <code class="code">%load-path</code>, but for compiled files. By default, this path
|
||
|
|
has two entries: one for compiled files from Guile itself, and one for
|
||
|
|
site packages. The <code class="env">GUILE_LOAD_COMPILED_PATH</code> environment variable
|
||
|
|
can be used to prepend or append additional directories
|
||
|
|
(see <a class="pxref" href="Environment-Variables.html">Environment Variables</a>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<p>When <code class="code">primitive-load-path</code> searches the <code class="code">%load-compiled-path</code>
|
||
|
|
for a corresponding compiled file for a relative path it does so by
|
||
|
|
appending <code class="code">.go</code> to the relative path. For example, searching for
|
||
|
|
<code class="code">ice-9/popen</code> could find
|
||
|
|
<code class="code">/usr/lib/guile/3.0/ccache/ice-9/popen.go</code>, and use it instead of
|
||
|
|
<code class="code">/usr/share/guile/3.0/ice-9/popen.scm</code>.
|
||
|
|
</p>
|
||
|
|
<p>If <code class="code">primitive-load-path</code> does not find a corresponding <code class="code">.go</code>
|
||
|
|
file in the <code class="code">%load-compiled-path</code>, or the <code class="code">.go</code> file is out of
|
||
|
|
date, it will search for a corresponding auto-compiled file in the
|
||
|
|
fallback path, possibly creating one if one does not exist.
|
||
|
|
</p>
|
||
|
|
<p>See <a class="xref" href="Installing-Site-Packages.html">Installing Site Packages</a>, for more on how to correctly install
|
||
|
|
site packages. See <a class="xref" href="Modules-and-the-File-System.html">Modules and the File System</a>, for more on the
|
||
|
|
relationship between load paths and modules. See <a class="xref" href="Compilation.html">Compiling Scheme Code</a>, for
|
||
|
|
more on the fallback path and auto-compilation.
|
||
|
|
</p>
|
||
|
|
<p>Finally, there are a couple of helper procedures for general path
|
||
|
|
manipulation.
|
||
|
|
</p>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-parse_002dpath"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">parse-path</strong> <var class="def-var-arguments">path [tail]</var><a class="copiable-link" href="#index-parse_002dpath"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fparse_005fpath"><span class="category-def">C Function: </span><span><strong class="def-name">scm_parse_path</strong> <var class="def-var-arguments">(path, tail)</var><a class="copiable-link" href="#index-scm_005fparse_005fpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Parse <var class="var">path</var>, which is expected to be a colon-separated string, into
|
||
|
|
a list and return the resulting list with <var class="var">tail</var> appended. If
|
||
|
|
<var class="var">path</var> is <code class="code">#f</code>, <var class="var">tail</var> is returned.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-parse_002dpath_002dwith_002dellipsis"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">parse-path-with-ellipsis</strong> <var class="def-var-arguments">path base</var><a class="copiable-link" href="#index-parse_002dpath_002dwith_002dellipsis"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fparse_005fpath_005fwith_005fellipsis"><span class="category-def">C Function: </span><span><strong class="def-name">scm_parse_path_with_ellipsis</strong> <var class="def-var-arguments">(path, base)</var><a class="copiable-link" href="#index-scm_005fparse_005fpath_005fwith_005fellipsis"> ¶</a></span></dt>
|
||
|
|
<dd><p>Parse <var class="var">path</var>, which is expected to be a colon-separated string, into
|
||
|
|
a list and return the resulting list with <var class="var">base</var> (a list) spliced in
|
||
|
|
place of the <code class="code">...</code> path component, if present, or else <var class="var">base</var>
|
||
|
|
is added to the end. If <var class="var">path</var> is <code class="code">#f</code>, <var class="var">base</var> is
|
||
|
|
returned.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-search_002dpath"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">search-path</strong> <var class="def-var-arguments">path filename [extensions [require-exts?]]</var><a class="copiable-link" href="#index-search_002dpath"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fsearch_005fpath"><span class="category-def">C Function: </span><span><strong class="def-name">scm_search_path</strong> <var class="def-var-arguments">(path, filename, rest)</var><a class="copiable-link" href="#index-scm_005fsearch_005fpath"> ¶</a></span></dt>
|
||
|
|
<dd><p>Search <var class="var">path</var> for a directory containing a file named
|
||
|
|
<var class="var">filename</var>. The file must be readable, and not a directory. If we
|
||
|
|
find one, return its full filename; otherwise, return <code class="code">#f</code>. If
|
||
|
|
<var class="var">filename</var> is absolute, return it unchanged. If given,
|
||
|
|
<var class="var">extensions</var> is a list of strings; for each directory in <var class="var">path</var>,
|
||
|
|
we search for <var class="var">filename</var> concatenated with each <var class="var">extension</var>. If
|
||
|
|
<var class="var">require-exts?</var> is true, require that the returned file name have
|
||
|
|
one of the given extensions; if <var class="var">require-exts?</var> is not given, it
|
||
|
|
defaults to <code class="code">#f</code>.
|
||
|
|
</p>
|
||
|
|
<p>For compatibility with Guile 1.8 and earlier, the C function takes only
|
||
|
|
three arguments.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Character-Encoding-of-Source-Files.html">Character Encoding of Source Files</a>, Previous: <a href="Loading.html">Loading Scheme Code from File</a>, Up: <a href="Read_002fLoad_002fEval_002fCompile.html">Reading and Evaluating Scheme Code</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|