summaryrefslogtreecommitdiff
path: root/doc/ref/api-evaluation.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2012-01-27 13:11:58 +0100
committerAndy Wingo <wingo@pobox.com>2012-01-27 16:33:11 +0100
commit0740cb49d1509c56184fc6802b4347ed8fc80a28 (patch)
treee3e6380f45c6850db0797b4ed210a7440684cdda /doc/ref/api-evaluation.texi
parent40e92f09fc3330aa33a169ad1aa6bf458633984c (diff)
downloadguile-0740cb49d1509c56184fc6802b4347ed8fc80a28.tar.gz
more documentation on the process of loading source and compiled files
* doc/ref/api-evaluation.texi (Load Paths): Move documentation of %load-path and related procedures here, from Build Config. Add docs for %load-compiled-path. * doc/ref/api-foreign.texi: * doc/ref/api-modules.texi: * doc/ref/api-options.texi: * doc/ref/scheme-using.texi: Update xrefs.
Diffstat (limited to 'doc/ref/api-evaluation.texi')
-rw-r--r--doc/ref/api-evaluation.texi78
1 files changed, 70 insertions, 8 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index f2b539e8f..ebd8771df 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -808,7 +808,15 @@ 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.
-For more on the @code{%load-path} variable, @xref{Build Config}.
+@cindex @env{GUILE_LOAD_PATH}
+@defvar %load-path
+List of directories which should be searched for Scheme modules and
+libraries. @code{%load-path} is initialized when Guile starts up to
+@code{(list (%site-dir) (%library-dir) (%package-data-dir))}, prepended
+with the contents of the @env{GUILE_LOAD_PATH} environment variable, if
+it is set. @xref{Build Config}, for more on @code{%site-dir} and
+related procedures.
+@end defvar
@deffn {Scheme Procedure} load-from-path filename
Similar to @code{load}, but searches for @var{filename} in the load
@@ -820,6 +828,7 @@ A user can extend the load path by calling @code{add-to-load-path}.
@deffn {Scheme Syntax} add-to-load-path dir
Add @var{dir} to the load path.
+@end deffn
For example, a script might include this form to add the directory that
it is in to the load path:
@@ -827,7 +836,6 @@ it is in to the load path:
@example
(add-to-load-path (dirname (current-filename)))
@end example
-@end deffn
It's better to use @code{add-to-load-path} than to modify
@code{%load-path} directly, because @code{add-to-load-path} takes care
@@ -851,12 +859,11 @@ the C function takes only one argument, which can be either a string
@deffn {Scheme Procedure} %search-load-path filename
@deffnx {C Function} scm_sys_search_load_path (filename)
-Search @code{%load-path} for the file named @var{filename},
-which must be readable by the current user. If @var{filename}
-is found in the list of paths to search or is an absolute
-pathname, return its full pathname. Otherwise, return
-@code{#f}. Filenames may have any of the optional extensions
-in the @code{%load-extensions} list; @code{%search-load-path}
+Search @code{%load-path} for the file named @var{filename}, which must
+be readable by the current user. If @var{filename} is found in the list
+of paths to search or is an absolute pathname, return its full pathname.
+Otherwise, return @code{#f}. Filenames may have any of the optional
+extensions in the @code{%load-extensions} list; @code{%search-load-path}
will try each extension automatically.
@end deffn
@@ -867,6 +874,61 @@ a file to load. By default, @code{%load-extensions} is bound to the
list @code{("" ".scm")}.
@end defvar
+As mentioned above, when Guile searches the @code{%load-path} for a
+source file, it will also search the @code{%load-compiled-path} 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{load-compiled}.
+
+@defvar %load-compiled-path
+Like @code{%load-path}, but for compiled files. By default, this path
+has two entries: one for compiled files from Guile itself, and one for
+site packages.
+@end defvar
+
+When @code{primitive-load-path} searches the @code{%load-compiled-path}
+for a corresponding compiled file for a relative path it does so by
+appending @code{.go} to the relative path. For example, searching for
+@code{ice-9/popen} could find
+@code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
+@code{/usr/share/guile/2.0/ice-9/popen.scm}.
+
+If @code{primitive-load-path} does not find a corresponding @code{.go}
+file in the @code{%load-compiled-path}, or the @code{.go} 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.
+
+@xref{Installing Site Packages}, for more on how to correctly install
+site packages. @xref{Modules and the File System}, for more on the
+relationship between load paths and modules. @xref{Compilation}, for
+more on the fallback path and auto-compilation.
+
+Finally, there are a couple of helper procedures for general path
+manipulation.
+
+@deffn {Scheme Procedure} parse-path path [tail]
+@deffnx {C Function} scm_parse_path (path, tail)
+Parse @var{path}, which is expected to be a colon-separated string, into
+a list and return the resulting list with @var{tail} appended. If
+@var{path} is @code{#f}, @var{tail} is returned.
+@end deffn
+
+@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
+@deffnx {C Function} scm_search_path (path, filename, rest)
+Search @var{path} for a directory containing a file named
+@var{filename}. The file must be readable, and not a directory. If we
+find one, return its full filename; otherwise, return @code{#f}. If
+@var{filename} is absolute, return it unchanged. If given,
+@var{extensions} is a list of strings; for each directory in @var{path},
+we search for @var{filename} concatenated with each @var{extension}. If
+@var{require-exts?} is true, require that the returned file name have
+one of the given extensions; if @var{require-exts?} is not given, it
+defaults to @code{#f}.
+
+For compatibility with Guile 1.8 and earlier, the C function takes only
+three arguments.
+@end deffn
+
@node Character Encoding of Source Files
@subsection Character Encoding of Source Files