1. Introduction

What is a component?

Gambas components are shared libraries written in C or C++ that add new functions to the Gambas interpreter.

They act like Linux drivers towards the Linux kernel:

• The components and the interpreter communicate through the Gambas Programming Interface.

• They must be compiled inside the Gambas source package.

• They are executed in the interpreter environment, and so must not do whatever they want.

A component can contain:

• New classes that are added to the other Gambas classes. These classes are declared to the interpreter using a C structure that contains the description of each method, constant and event.

• Interpreter Hooks. These are special functions that implement important interpreter operations, like managing the event loop, reading the command-line arguments...

• An optional programming interface that enhances the Gambas Programming Interface, and that other components can use.

A component must have a name. This name is the the word gb followed by a dot-separated list of words describing the role of the component and another component it relies on, if any.

Example

• gb.qt4 is a component based on Qt4 that brings GUI programming to Gambas.

• gb.net.curl is a component based on the libcurl library. It requires the gb.net component, i.e. loading the first implies loading the second.

The Gambas Programming Interface

The Gambas Programming Interface is a set of utilities, functions and macros that allows you to:

• Describe the component.

• Define interpreter hooks.

• Allocate and free memory.

• Manipulate arrays, hash tables...

• Manipulate Gambas native datatypes.

• Create Gambas arrays and collections.

• Raise events.

• Manipulate Gambas objects.

• Load a file from the project archive.

• Load other components.

• ...

The use of this programming interface is highly recommended, as it prevents a component from doing weird things.

The Gambas Programming Interface is a C structure that contains one function pointer for each function of the interface.

This structure is declared in the main file of your component and is automatically initialized by the interpreter at component loading.

Writing Good Components

Writing good components is the difficult part! Let's suppose you want to write a SDL component, i.e. a component that lets a Gambas project use all the power of the SDL library: graphics, sound, CD-ROM...

You can be happy with just wrapping the library functions, structure and constants. It is the easy way, even if wrapping C structures and functions may not be possible in every case with Gambas.

Your component will be useful, but not very interesting for the Gambas programmer, because he will have to program in C or C++ style.

Instead, you should rack your brain to create a different interface between Gambas and the library, by trying to generalize and simplify the original interface of the library.

That is what I did with qt: it is far easier to use the gb.qt4 component than programming the Qt library directly. Moreover, the gb.gtk component use the same interface than gb.qt4, and so you can write a GUI program that can use one or the other indifferently.

Component Source Organization

The source files of a component are stored in its own directory.

• Either in a project root directory, having the same name as the component (gb.xxxx).

• Either in a sub-directory of /main/lib.

Use the first case if your component needs one or more shared library.

Use the other one if your component just needs a very basic library already used by the interpreter, like libc or libm.

A typical component directory includes:

• The autoconf/automake stuff, i.e. a Makefile.am file that describes how to compile the component.

• One source file and one header file for each main class implemented in the component.

• One main file that implements the entry points of the component.

• One component description file.