[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
guile/guile-core/doc ChangeLog extend.texi gh.t...
From: |
Neil Jerram |
Subject: |
guile/guile-core/doc ChangeLog extend.texi gh.t... |
Date: |
Wed, 20 Jun 2001 15:08:19 -0700 |
CVSROOT: /cvs
Module name: guile
Changes by: Neil Jerram <address@hidden> 01/06/20 15:08:19
Modified files:
guile-core/doc : ChangeLog extend.texi gh.texi guile.texi
Log message:
* Explain GH deprecation & plan for scm documentation.
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.97&tr2=1.98&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/extend.texi.diff?cvsroot=OldCVS&tr1=1.1&tr2=1.2&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/gh.texi.diff?cvsroot=OldCVS&tr1=1.4&tr2=1.5&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/guile.texi.diff?cvsroot=OldCVS&tr1=1.10&tr2=1.11&r1=text&r2=text
Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.97 guile/guile-core/doc/ChangeLog:1.98
--- guile/guile-core/doc/ChangeLog:1.97 Mon Jun 18 12:08:31 2001
+++ guile/guile-core/doc/ChangeLog Wed Jun 20 15:08:19 2001
@@ -1,3 +1,11 @@
+2001-06-20 Neil Jerram <address@hidden>
+
+ * 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 <address@hidden>
* srfi-modules.texi (SRFI-1): Completed procedure documentation.
Index: guile/guile-core/doc/extend.texi
diff -u guile/guile-core/doc/extend.texi:1.1
guile/guile-core/doc/extend.texi:1.2
--- guile/guile-core/doc/extend.texi:1.1 Fri Mar 9 00:21:59 2001
+++ guile/guile-core/doc/extend.texi Wed Jun 20 15:08:19 2001
@@ -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.
Index: guile/guile-core/doc/gh.texi
diff -u guile/guile-core/doc/gh.texi:1.4 guile/guile-core/doc/gh.texi:1.5
--- guile/guile-core/doc/gh.texi:1.4 Sun Apr 22 07:56:52 2001
+++ guile/guile-core/doc/gh.texi Wed Jun 20 15:08:19 2001
@@ -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.
address@hidden SCM interpreter
address@hidden 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.
address@hidden gh_ interface
address@hidden libguile interface
-
-If you are @emph{programming with Guile}, you should only use the C
-subroutines described in this manual, which all begin with
address@hidden
-
-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}).
address@hidden Guile - extending
address@hidden extending Guile
address@hidden 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::
@@ -52,6 +29,57 @@
* Calling Scheme procedures from C::
* Mixing gh and scm APIs::
@end menu
+
+
address@hidden GH deprecation
address@hidden 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
address@hidden 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
address@hidden functions, all that is needed is a definition of the
address@hidden 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
address@hidden 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
Index: guile/guile-core/doc/guile.texi
diff -u guile/guile-core/doc/guile.texi:1.10
guile/guile-core/doc/guile.texi:1.11
--- guile/guile-core/doc/guile.texi:1.10 Wed May 23 10:24:49 2001
+++ guile/guile-core/doc/guile.texi Wed Jun 20 15:08:19 2001
@@ -80,7 +80,7 @@
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
address@hidden $Id: guile.texi,v 1.10 2001/05/23 17:24:49 mgrabmue Exp $
address@hidden $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 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 @@
@end iftex
@include extend.texi
address@hidden gh.texi
@include data-rep.texi
@include scm.texi
address@hidden gh.texi
@c Appendices
@iftex
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- guile/guile-core/doc ChangeLog extend.texi gh.t...,
Neil Jerram <=