summaryrefslogtreecommitdiff
path: root/doc/ref/libguile-parallel.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/libguile-parallel.texi')
-rw-r--r--doc/ref/libguile-parallel.texi84
1 files changed, 84 insertions, 0 deletions
diff --git a/doc/ref/libguile-parallel.texi b/doc/ref/libguile-parallel.texi
new file mode 100644
index 000000000..75fcd88ba
--- /dev/null
+++ b/doc/ref/libguile-parallel.texi
@@ -0,0 +1,84 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011,
+@c 2013-2014 Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Parallel Installations
+@section Parallel Installations
+
+@cindex pkg-config
+@cindex effective version
+
+Guile provides strong API and ABI stability guarantees during stable
+series, so that if a user writes a program against Guile version 2.2.3,
+it will be compatible with some future version 2.2.7. We say in this
+case that 2.2 is the @dfn{effective version}, composed of the major and
+minor versions, in this case 2 and 2.
+
+Users may install multiple effective versions of Guile, with each
+version's headers, libraries, and Scheme files under their own
+directories. This provides the necessary stability guarantee for users,
+while also allowing Guile developers to evolve the language and its
+implementation.
+
+However, parallel installability does have a down-side, in that users
+need to know which version of Guile to ask for, when they build against
+Guile. Guile solves this problem by installing a file to be read by the
+@code{pkg-config} utility, a tool to query installed packages by name.
+Guile encodes the version into its pkg-config name, so that users can
+ask for @code{guile-2.2} or @code{guile-3.0}, as appropriate.
+
+For effective version @value{EFFECTIVE-VERSION}, for example, you would
+invoke @code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}}
+to get the compilation and linking flags necessary to link to version
+@value{EFFECTIVE-VERSION} of Guile. You would typically run
+@code{pkg-config} during the configuration phase of your program and use
+the obtained information in the Makefile.
+
+Guile's @code{pkg-config} file,
+@file{guile-@value{EFFECTIVE-VERSION}.pc}, defines additional useful
+variables:
+
+@table @code
+@item sitedir
+@cindex @code{sitedir}
+The default directory where Guile looks for Scheme source and compiled
+files (@pxref{Installing Site Packages, %site-dir}). Run
+@command{pkg-config guile-@value{EFFECTIVE-VERSION} --variable=sitedir}
+to see its value. @xref{Autoconf Macros, GUILE_SITE_DIR}, for more on
+how to use it from Autoconf.
+
+@item extensiondir
+@cindex @code{extensiondir}
+The default directory where Guile looks for extensions---i.e., shared
+libraries providing additional features (@pxref{Modules and
+Extensions}). Run @command{pkg-config guile-@value{EFFECTIVE-VERSION}
+--variable=extensiondir} to see its value.
+
+@item guile
+@itemx guild
+@cindex program name transformations, dealing with
+The absolute file name of the @command{guile} and @command{guild}
+commands@footnote{The @code{guile} and @code{guild} variables defined
+starting from Guile version 2.0.12.}. Run @command{pkg-config
+guile-@value{EFFECTIVE-VERSION} --variable=guile} or
+@code{--variable=guild} to see their value.
+
+These variables allow users to deal with program name transformations
+that may be specified when configuring Guile with
+@code{--program-transform-name}, @code{--program-suffix}, or
+@code{--program-prefix} (@pxref{Transformation Options,,, autoconf, GNU
+Autoconf Manual}).
+@end table
+
+@noindent
+See the @code{pkg-config} man page, for more information, or its web
+site, @url{http://pkg-config.freedesktop.org/}.
+@xref{Autoconf Support}, for more on checking for Guile from within a
+@code{configure.ac} file.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: