diff options
author | Andy Wingo <wingo@pobox.com> | 2011-10-12 16:20:51 +0200 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2011-10-12 17:12:34 +0200 |
commit | 24cc7832a61350f4557b6382e71940ca3c9ab060 (patch) | |
tree | 06979a8ef26cb3d9d5830ac6ff79af1bdc654f77 | |
parent | 067df233c451a68a84dc69b4a6f4d16eac837542 (diff) | |
download | guile-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.
-rw-r--r-- | doc/ref/guile.texi | 1 | ||||
-rw-r--r-- | doc/ref/scheme-using.texi | 58 | ||||
-rw-r--r-- | doc/ref/tour.texi | 7 |
3 files changed, 66 insertions, 0 deletions
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index e293325c6..6b6d8b2a4 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -227,6 +227,7 @@ on that make up Guile's application programming interface (API), see * Using Guile Interactively:: Guile's REPL features. * Using Guile in Emacs:: Guile and Emacs. * Using Guile Tools:: A guild of scheming wizards. +* Installing Site Packages:: Installing Scheme code. @end menu @include scheme-intro.texi 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: diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi index 41fafb1ba..3e612692d 100644 --- a/doc/ref/tour.texi +++ b/doc/ref/tour.texi @@ -181,6 +181,9 @@ scheme@@(guile-user)> (j0 2) $1 = 0.223890779141236 @end smallexample +For more on how to install your extension, @pxref{Installing Site +Packages}. + @node Using the Guile Module System @subsection Using the Guile Module System @@ -248,6 +251,10 @@ scheme@@(guile-user)> (frob 12) $1 = 24 @end smallexample +For more on how to install your module, @pxref{Installing Site +Packages}. + + @node Putting Extensions into Modules @subsubsection Putting Extensions into Modules |