summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-using.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2011-10-12 16:20:51 +0200
committerAndy Wingo <wingo@pobox.com>2011-10-12 17:12:34 +0200
commit24cc7832a61350f4557b6382e71940ca3c9ab060 (patch)
tree06979a8ef26cb3d9d5830ac6ff79af1bdc654f77 /doc/ref/scheme-using.texi
parent067df233c451a68a84dc69b4a6f4d16eac837542 (diff)
downloadguile-24cc7832a61350f4557b6382e71940ca3c9ab060.tar.gz
add "Installing Site Packages"
* doc/ref/scheme-using.texi (Installing Site Packages): Add a new section about where to install .scm, .go, and .so files. * doc/ref/tour.texi: Reference it here. * doc/ref/guile.texi: Add new section.
Diffstat (limited to 'doc/ref/scheme-using.texi')
-rw-r--r--doc/ref/scheme-using.texi58
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 2713fabdd..73e1a5dec 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -732,6 +732,64 @@ using a CPAN-like system.
A complete list of guild scripts can be had by invoking @code{guild
list}, or simply @code{guild}.
+
+@node Installing Site Packages
+@section Installing Site Packages
+
+@cindex site
+@cindex site path
+@cindex load path
+@findex %site-dir
+
+At some point, you will probably want to share your code with other
+people. To do so effectively, it is important to follow a set of common
+conventions, to make it easy for the user to install and use your
+package.
+
+The first thing to do is to install your Scheme files where Guile can
+find them. When Guile goes to find a Scheme file, it will search a
+@dfn{load path} to find the file: first in Guile's own path, then in
+paths for @dfn{site packages}. A site package is any Scheme code that
+is installed and not part of Guile itself. @xref{Loading}, for more on
+load paths.
+
+There are several site paths, for historical reasons, but the one that
+should generally be used can be obtained by invoking the
+@code{%site-dir} procedure. @xref{Build Config}. If Guile
+@value{EFFECTIVE-VERSION} is installed on your system in @code{/usr/},
+then @code{(%site-dir)} will be
+@code{/usr/share/guile/site/@value{EFFECTIVE-VERSION}}. Scheme files
+should be installed there.
+
+If you do not install compiled @code{.go} files, Guile will compile your
+modules and programs when they are first used, and cache them in the
+user's home directory. @xref{Compilation}, for more on
+auto-compilation. However, it is better to compile the files before
+they are installed, and to just copy the files to a place that Guile can
+find them.
+
+As with Scheme files, Guile searches a path to find compiled @code{.go}
+files, the @code{%load-compiled-path}. By default, this path has two
+entries: a path for Guile's files, and a path for site packages. You
+should install your @code{.go} files into the latter. Currently there
+is no procedure to get at this path, which is probably a bug. As in the
+previous example, if Guile @value{EFFECTIVE-VERSION} is installed on
+your system in @code{/usr/}, then the place to put compiled files for
+site packages will be
+@code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/site-ccache}.
+
+Note that a @code{.go} file will only be loaded in preference to a
+@code{.scm} file if it is newer. For that reason, you should install
+your Scheme files first, and your compiled files second.
+
+Finally, although this section is only about Scheme, sometimes you need
+to install C extensions too. Shared libraries should be installed in
+the @dfn{extensions dir}. This value can be had from the build config
+(@pxref{Build Config}). Again, if Guile @value{EFFECTIVE-VERSION} is
+installed on your system in @code{/usr/}, then the extensions dir will
+be @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/extensions}.
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: