diff options
-rw-r--r-- | doc/ChangeLog | 8 | ||||
-rw-r--r-- | doc/extend.texi | 33 | ||||
-rw-r--r-- | doc/gh.texi | 90 | ||||
-rw-r--r-- | doc/guile.texi | 6 |
4 files changed, 88 insertions, 49 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 553aab4f5..4482010b0 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2001-06-20 Neil Jerram <neil@ossau.uklinux.net> + + * guile.texi (Top): Move GH chapter to end of Part V. + + * extend.texi (Libguile Intro), gh.texi (GH deprecation): Explain + deprecation of GH and broad plan for documentation of scm + interface. + 2001-06-18 Martin Grabmueller <mgrabmue@cs.tu-berlin.de> * srfi-modules.texi (SRFI-1): Completed procedure documentation. diff --git a/doc/extend.texi b/doc/extend.texi index e9e7cdd0f..5cadde4e8 100644 --- a/doc/extend.texi +++ b/doc/extend.texi @@ -5,19 +5,22 @@ The chapters in this part of the manual explain how to use Guile as a powerful application extension language. -The following chapter, ``GH: A Portable C to Scheme Interface,'' shows -how to call Guile from your application's C code, and how to add new -Scheme level procedures to Guile whose behaviour is specified by -application specific code written in C. The Guile interface functions -documented in this chapter make up a high level, portable interface -which (we hope) will also someday work with other Scheme interpreters, -allowing you to write C code which will work with any of several Scheme -systems. +An important change for the 1.6.x series of Guile releases is that the +GH interface is now deprecated. For the reasoning behind this decision, +see @xref{GH deprecation}. The GH interface will continue to be +supported for the 1.6.x and 1.8.x release series, but will be dropped +thereafter, so developers are encouraged to switch progressively to the +scm interface. The last chapter in this part of the manual (@pxref{GH}) +documents both how to use GH and how to switch from GH to scm. -The portable interface is rich enough to support simple use of Guile as -an application extension language, but is limited by its own portability -where a deeper integration is desired between Guile and your -application's code. The subsequent chapters therefore present aspects -of libguile that allow you to use more of Guile's C level features, and -to extend your application in more complex ways than is possible with -the portable interface. +The documentation of the scm interface is currently a bit confused, but +the situation should improve rapidly once the 1.6.0 release is out. The +plan is to refocus the bulk of Part II, currently ``Guile Scheme'', as +the ``Guile API Reference'' so that it covers both Scheme and C +interfaces. (This makes sense because almost all of Guile's primitive +procedures on the Scheme level --- e.g. @code{memq} --- are also +available as C level primitives in the scm interface --- +e.g. @code{scm_memq}.) There will then remain a certain amount of +Scheme-specific (such as the ``Basic Ideas'' chapter) and C-specific +documentation (such as SMOB usage and interaction with the garbage +collector) to collect into corresponding chapters. diff --git a/doc/gh.texi b/doc/gh.texi index 668270cb8..999ea6331 100644 --- a/doc/gh.texi +++ b/doc/gh.texi @@ -5,40 +5,17 @@ @cindex gh @cindex gh - reference manual -The Guile interpreter is based on Aubrey Jaffer's @emph{SCM} interpreter -(@pxref{Overview, SCM: a portable Scheme interpreter, Overview, scm, -SCM: a portable Scheme interpreter}) with some modifications to make it -suitable as an embedded interpreter, and further modifications as Guile -evolves. -@cindex SCM interpreter -@cindex Jaffer, Aubrey - -Part of the modification has been to provide a restricted interface to -limit access to the SCM internals; this is called the @code{gh_} -interface, or @emph{libguile} interface. -@cindex gh_ interface -@cindex libguile interface - -If you are @emph{programming with Guile}, you should only use the C -subroutines described in this manual, which all begin with -@code{gh_}. - -If instead you are @emph{extending Guile}, you have the entire SCM -source to play with. This manual will not help you at all, but you can -consult Aubrey Jaffer's SCM manual (@pxref{Internals, SCM: a portable -Scheme interpreter, Internals, scm, SCM: a portable Scheme -interpreter}). -@cindex Guile - extending -@cindex extending Guile -@cindex SCM internals - -If you are @emph{adding a module to Guile}, I recommend that you stick -to the @code{gh_} interface: this interface is guaranteed to not -change drastically, while the SCM internals might change as Guile is -developed. +This chapter shows how to use the GH interface to call Guile from your +application's C code, and to add new Scheme level procedures to Guile +whose behaviour is specified by application specific code written in C. +Note, however, that the GH interface is now deprecated, and developers +are encouraged to switch to using the scm interface instead. Therefore, +for each GH feature, this chapter should also document how to achieve +the same result using the scm interface. @menu +* GH deprecation:: Why the GH interface is now deprecated. * gh preliminaries:: * Data types and constants defined by gh:: * Starting and controlling the interpreter:: @@ -54,6 +31,57 @@ developed. @end menu +@node GH deprecation +@section Why the GH Interface is Now Deprecated + +Historically, the GH interface was the product of a practical problem +and a neat idea. The practical problem was that the interface of the +@code{scm_} functions with which Guile itself was written (inherited +from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane) +details of the internal data representation that it was extremely +difficult to write a Guile extension using these functions. The neat +idea was to define a high level language extension interface in such a +way that other extension language projects, not just Guile, would be +able to provide an implementation of that interface; then applications +using this interface could be compiled with whichever of the various +available implementations they chose. So the GH interface was created, +and advertised both as the recommended interface for application +developers wishing to use Guile, and as a portable high level interface +that could theoretically be implemented by other extension language +projects. + +Time passed, and various things changed. Crucially, an enormous number +of improvements were made to the @code{scm_} interface that Guile itself +uses in its implementation, with the result that it is now both easy and +comfortable to write a Guile extension with this interface. At the same +time, the contents of the GH interface were somewhat neglected by the +core Guile developers, such that some key operations --- such as smob +creation and management --- are simply not possible using GH alone. +Finally, the idea of multiple implementations of the GH interface did +not really crystallize (apart, I believe, from a short lived +implementation by the MzScheme project). + +Where portability is concerned, the @code{scm_} interface is now already +portable in the sense that other projects could provide an alternative +implementation of the @code{scm_} header file. For the majority of +@code{scm_} functions, all that is needed is a definition of the +@code{SCM} type, and then those functions are automatically portable by +virtue of the fact that their signatures refer only to this @code{SCM} +type. + +For all these reasons, the Guile developers have decided to deprecate +the GH interface --- which means that support for GH will be completely +removed after the next few releases --- and to focus only on the +@code{scm_} interface, with additions to ensure that it is as easy to +use in all respects as GH was. + +It remains an open question whether deeper kinds of interface +portability would be useful for extension language-based applications, +and it may still be an interesting project to attempt to define a +corresponding GH-like interface, but the Guile developers no longer plan +to try to do this as part of the core Guile project. + + @node gh preliminaries @section gh preliminaries diff --git a/doc/guile.texi b/doc/guile.texi index 29da7b221..d42cc8ca4 100644 --- a/doc/guile.texi +++ b/doc/guile.texi @@ -80,7 +80,7 @@ by the Free Software Foundation. @sp 10 @comment The title is printed in a large font. @title Guile Reference Manual -@subtitle $Id: guile.texi,v 1.10 2001-05-23 17:24:49 mgrabmue Exp $ +@subtitle $Id: guile.texi,v 1.11 2001-06-20 22:08:19 ossau Exp $ @subtitle For use with Guile @value{VERSION} @include AUTHORS @@ -187,11 +187,11 @@ Part IV: Guile Scripting Part V: Extending Applications Using Guile * Libguile Intro:: Using Guile as an extension language. -* GH:: GH: a portable C to Scheme interface. * Data Representation:: Data representation in Guile. * Scheme Primitives:: Writing Scheme primitives in C. * I/O Extensions:: Using and extending ports in C. * Handling Errors:: How to handle errors in C code. +* GH:: The deprecated GH interface. Appendices @@ -273,9 +273,9 @@ Indices @end iftex @include extend.texi -@include gh.texi @include data-rep.texi @include scm.texi +@include gh.texi @c Appendices @iftex |