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 :

A component can contain :

A component must have a name. This name is the the word gb follow by a dot-separated list of words describing the role of the component and the other component it relies on.

For example, gb.qt.kde is a component that transforms a Gambas application into a KDE application. This component relies on the gb.qt 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 to:

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 all the difficulty ! Let's suppose you want to write a SDL component, i.e. a component that let a Gambas project use all the power of the SDL library : graphics, sound, CD-ROM...

You can content yourself 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 be obliged to program like in C or C++.

I think you should better 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 what I did with QT : it is far easier to use the QT component than programming directly the QT library. And if one day somebody writes a GTK+ component, he will be able to use the same interface because I tried to generalize the QT interface by avoiding all the QT specific stuff... Well, to be honest, I putted all useful QT specific stuff into a dedicated extended component, gb.qt.ext

Component Source Organization

The source files of a component are stored in a sub-directory of the lib directory of the source package. The path of this directory reflects the name of the component.

For example, the gb.qt.kde component sources are stored in the ./src/lib/qt/kde directory.

A typical component directory contains :

For example, here is the result of ls ./src/lib/qt/kde just before the compilation :

CApplication.cpp  CDatePicker.cpp  CDialog.cpp  lib.gb.qt.kde.component  main.h    Makefile.am
CApplication.h    CDatePicker.h    CDialog.h    main.cpp                 Makefile  Makefile.in

The component source directory structure is something like that:

-+- lib
 |
 +---+- db
 |   |
 |   +----- mysql
 |   |
 |   +----- postgresql
 |
 +----- eval
 |
 +----- example
 |
 +----- net
 |
 +---+- qt
 |   |
 |   +----- editor
 |   |
 |   +----- ext
 |   |
 |   +----- kde
 |
 +----- sdl