* Intro / Index (last modified: $Date: 2001-11-14 20:47:40 $)

This working document explains the design of the libguile API,
specifically the interface to the C programming language.
Note that this is NOT an API reference manual.

- Motivation
- History
- Decisions
  - gh_ removal
  - malloc policy
  - [add here]


* Motivation

The file goals.text says:

	Guile's primary aim is to provide a good extension language
	which is easy to add to an application written in C for the GNU
	system.  This means that it must export the features of a higher
	level language in a way that makes it easy not to break them
	from C code.

Although it may no longer be a "primary aim", creating a stable API is
important anyway since without something defined, people will take libguile
and use it in ad-hoc ways that may cause them trouble later.


* History

The initial (in ttn's memory, which only goes back to guile-1.3.4) stab at an
API was known as the "gh_ interface", which provided "high-level" abstraction
to libguile w/ the premise of supporting multiple implementations at some
future date.  In practice this approach resulted in many gh_* objects being
very slight wrappers for the underlying scm_* objects, so eventually this
maintenance burden outweighed the (as yet unrealized) hope for alternate
implementations, and the gh_ interface was deprecated starting in guile-1.5.x.

Starting w/ guile-1.7.x, in concurrence w/ an effort to make libguile
available to usloth windows platforms, the naked library was once again
dressed w/ the "SCM_API interface".


* Decisions

** gh_ removal

At some point, we need to remove gh_ entirely: guile-X.Y.Z.

** malloc policy

Here's a proposal by ela:

  I would like to propose the follow gh_() equivalents:

  gh_scm2newstr()    ->  scm_string2str() in string.[ch]
  gh_symbol2newstr() ->  scm_symbol2str() in symbol.[ch]

  Both taking the (SCM obj, char *context) and allocating memory via
  scm_must_malloc().  Thus the user can safely free the returned strings
  with scm_must_free().  The latter feature would be an improvement to the
  previous gh_() interface functions, for which the user was told to free()
  them directly.  This caused problems when libguile.so used libc malloc()
  and the calling application used its own standard free(), which might not
  be libc free().

It seems to address the general question of: How should client programs use
malloc with respect to libguile?  Some specific questions:

 * Do you like the names of the functions? Maybe they should be named
   scm_c_*() instead of scm_*().
 * Do they make sense?
 * Should we provide something like scm_c_free() for pointers returned by
   these kind of functions?