Go to the first, previous, next, last section, table of contents.


Usage

Linking

In order to use GNUstep-Guile, you must link the libgstep_guile library into your program along with the standard Guile library (libguile) and the GNUstep foundation library (gstep-base). You will probably also want to link in the libgg_base library (to ensure that all the Foundation classes get linked into your application) and possibly the libgg_gui and the gstep_gui libraries (to get the AppKit classes) and libgg_gdl2 and associated classes for GDL2 (EOF) support.

If you are using shared libraries (the default) then you probably don't need to link in libgg_base, libgg_gui or libgg_gdl2 explicitly, and don't even need to link libgstep_guile, as the guile software can load these libraries (and the main GNUstel libraries) automatically at runtime. If this is the case, you can ignore the instructions about linking below, and just do a `(use-modules (languages gstep-guile gstep-guile))' command to load the gstep-guile module. This will autom atomatically make the GNUstep base library available. To make the gui library and gdl2 library available you need to do `(gstep-gui)' and `(gstep-gdl2)' to load those libraries.

When you install gstep-guile, a copy of the library is put in the Guile modules directory so that you can use the guile command `(use-modules (languages gstep-guile gstep-guile))' to get it dynamically loaded rather than having to link it into your program at compile-time. This will not work if you have built the library for static linking (in which case you need to link the libraries into your program explicitly).

It is also possible for you to work with other Foundation libraries such as libFoundation. This library IS restricted to working with the gcc objc runtime - unless someone wants to add support for other runtimes. The library also depends upon an NSMethodSignature extension available in a gstep-base and in libFoundation. I don't know if Rhapsody has a similar undocumented extension.

Your program (if static linked) must call the function 'gstep_init()' to tell the guile library about the gstep_guile stuff. This should be done near the start of the 'main' function whose address is passed as the third parameter to 'gh_enter()' when you invoke the guile system. If this means nothing to you - please read the Guile documentation for information on how to call guile from within your program.

If you want to have the OpenStep foundation `C' functions and constants available (as well as all the classes in the OpenStep foundation library - rather than just those used in your Objective-C program) you will also need to call 'gstep_link_base()' immediately after calling 'gstep_init()' and link your program with the 'gg_base' library. If you do not do this then the only foundation classes available to Guile will be those that you have used in your main program (plus a few used internally by the gstep-guile library).

Similarly, if you want to have the OpenStep appkit `C' functions and constants available (as well as all the classes in the OpenStep appkit library - rather than just those used in your Objective-C program) you will also need to call 'gstep_link_gui()' and link your program with the 'gg_gui' library. If you do not do this then the only appkit classes available to Guile will be those that you have used in your main program.

Once you have a working program, you will probably want to load in some definitions of guile procedures and macros which make it easy to use the facilities in gstep_guile. This distribution includes a Guile module file ('gstep-guile.scm') which is placed in the standard modules directory so that you can use it with `(use-modules (languages gstep-guile))'.

ObjectiveC

To aid in using gstep-guile from within your Objective-C programs, some parts of the gstep-guile library are made available as external symbols so that you can call functions from C/ObjectiveC in much the same way that you would do things from within Guile.

The minimum you need to know is that you need to call `gstep_init()' before starting the Guile system, and `gstep_link_base()' if you need full access to the OpenStep foundation.

Other functions you can call from ObjectiveC (declared in gstep_guile.h) are -

Programming

Once you have linked gstep-base and gstep_guile into your program (if necessary) and have loaded the gstep-guile module (using the `(use-modules (languages gstep-guile))' command), you can start programming with GNUstep objects from within Guile.

Gstep-guile provides you with a selection of primitives, macros and procedures to perform basic Guile to Objective-C interaction, and also provides some specific facilities to help you use the OpenStep libraries.

Primitives

The GNUstep-Guile library provides the following primitives -

Macros

The scheme source file 'gstep-guile.scm' implements a Guile module which provides you with scheme procedures and macros to make better use of the primitives provided by the library -

Data

Objects

The passing of standard `C' data types is by value - so the data is actually copied from a guile data item to a `C' one as it is passed into the objc world and is copied from the `C' data item to a guile on when it is returned to the guile world.

There are two exceptions to this, the objc object - these are always passed as pointers (by reference), and other pointers such as pointers to arrays and abstract data - these are passed as `voidp' items.

Within the guile world, objc objects are first-class data items - gstep-guile adds a guile data type which encapsulates a pointer to an objc object and is the equivalent of the 'id' type in objc.

When an object is passed from the guile world to the objc world, the pointer to the objc object is unwrapped from the guile data item and passed. When an object is passed from the objc world to the guile world, a guile data item is created to wrap it.

Pointers

Gstep-guile also adds the `voidp' data type which is used to pass abstract pointers to data between the Objective-C and Guile worlds.

An Objective-C method which expects a pointer (other than a string or object) as an argument must be passed a `voidp' item.

An Objective-C method which returns a pointer (other than a string or object) will return it as a `voidp' item.

The `voidp' type is used to encapsulate arbitrary pointers to data (usually arrays of other types). Primitives are supplied to manipulate `voidp' items - conversion to/from Guile strings and lists of Guile objects.

There is essentially a single mechanism for passing data from one world to the other - the `gstep-msg-send' primitive.

Numbers

The `C' data types `char', `unsigned char', `short', `unsigned short', `int', `unsigned int', `long', and `unsigned long' all appear in the guile world as numbers.

The numeric constants used by the OpenStep API are defined as Guile variables when gstep-guile is initialised, so that you may pass them to objc methods. These constants are compiled into link_base.m and you will need to modify that file if I have missed any.

Strings

Guile strings are copied into standard `C' strings in the objc world and `C' strings are copied into guile strings when they are passed back to the guile world.

The string constants used by the OpenStep API are defined as Guile variables when gstep-guile is initialised, so that you may pass them to objc methods. These constants are compiled into link_base.m and you will need to modify that file if I have missed any.

Structures

Objc structures are represented as lists in the guile world, with nested structures being represented as lists of lists. I chose the list representation rather than guiles structure data type because guile structures seemed to offer little advantage over lists and are less obvious to someone coming from a lisp or scheme programming background, also, guile provides a richer set of primitives for manipulating lists than it does for structures.

For instance `([] str rangeOfString: sub)' invokes the `rangeOfString:' method to find the substring `sub' in the string `str' and return an NSRange structure describing the substring found. The NSRange structure consists of two integers, so the actual value returned in the guile world is a list containing two numbers. The order of the values in the list is the same as the order of the values in the structure.

Classes


Go to the first, previous, next, last section, table of contents.