guile18/doc/ref/extend.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Libguile Intro
   9 @chapter Using Guile as an Extension Language
  10
  11 The chapters in this part of the manual explain how to use Guile as a
  12 powerful application extension language.
  13
  14 An important change for the 1.6.x series of Guile releases is that the
  15 GH interface is now deprecated.  For the reasoning behind this decision,
  16 see @xref{GH deprecation}.  The GH interface will continue to be
  17 supported for the 1.6.x and 1.8.x release series, but will be dropped
  18 thereafter, so developers are encouraged to switch progressively to the
  19 scm interface.  The last chapter in this part of the manual (@pxref{GH})
  20 documents both how to use GH and how to switch from GH to scm.
  21
  22 The Guile developers believe that clarification of the GH vs. scm
  23 debate, and the consequent deprecation of the GH interface, are in the
  24 long term interests of the project.  However it does create an
  25 unfortunate situation for developers who want to start a project using
  26 Guile and so read the manual to find out how to proceed.  They will
  27 discover that the GH interface, although quite well documented, is
  28 deprecated, but that there is almost no adequate documentation for its
  29 theoretical replacement, the scm interface.  Moreover, the scm interface
  30 still has the odd few rough edges which need smoothing down.
  31
  32 Therefore, although deprecated, it is quite OK to continue to use the GH
  33 interface if you feel uncomfortable with the `scm_' interface as it
  34 stands today.  By the time that support for GH is dropped, we plan to
  35 have thoroughly documented the `scm_' interface, and to have enhanced it
  36 such that conversion from GH to the `scm_' interface will be very
  37 straightforward, and probably mostly automated.
  38
  39 As far as documentation of the scm interface is concerned, the current
  40 position is that it is a bit confused, but that the situation should
  41 improve rapidly once the 1.6.0 release is out.  The plan is to refocus
  42 the bulk of Part II, currently ``Guile Scheme'', as the ``Guile API
  43 Reference'' so that it covers both Scheme and C interfaces.  (This makes
  44 sense because almost all of Guile's primitive procedures on the Scheme
  45 level --- e.g. @code{memq} --- are also available as C level primitives
  46 in the scm interface --- e.g. @code{scm_memq}.)  There will then remain
  47 a certain amount of Scheme-specific (such as the ``Basic Ideas''
  48 chapter) and C-specific documentation (such as SMOB usage and
  49 interaction with the garbage collector) to collect into corresponding
  50 chapters.