How To Program Components In C/C++
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.
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.
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
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
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
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.
A Gambas project if the component has a Gambas part. The name of the project must be the same as the component name.
Here is the contents of the
gb.dbus directory that is not generated by the autoconf/automake tools:
├── acinclude.m4 -> ../acinclude.m4 Common autoconf macros
├── AUTHORS File required by GNU tools
├── ChangeLog File required by GNU tools
├── component.am -> ../component.am Makefile.am part needed by components
├── configure.ac The autoconf configuration file
├── gambas.h -> ../main/share/gambas.h The Gambas interpreter API header
├── gb_common.h -> ../main/share/gb_common.h Some other useful common declarations
├── INSTALL -> ../INSTALL File required by GNU tools
├── m4 -> ../m4 Directory including common m4 macros used by configure.ac and acinclude.m4
├── Makefile.am The top-level automake configuration file
├── missing -> ../missing File required by GNU tools
├── NEWS File required by GNU tools
├── README README file
├── reconf -> ../reconf Link at a script that reconfigure the source package from scratch
└── src The source directory
├── gb.dbus The Gambas part of the gb.dbus component
│ ├── .project
│ └── .src
│ ├── CTest2.class
│ ├── CTest.class
│ ├── DBusApplication.class
│ ├── DBus.class
│ ├── DBusObject.class
│ ├── DBusProxy.class
│ ├── DBusSignal.class
│ └── MMain.module
├── gb.dbus.component The component description file
└── Makefile.am The automake configuration file of the "src" sub-directory
There is a
TEMPLATE directory in the sources that includes a script named
can create a component skeleton directory from a configuration file.
The configuration file must be located in the
TEMPLATE/README file for more details.