doc • arch

Architecture details

Click on the picture to get details about Gambas architecture...

A drawing is better than a long speech. And I'm fond of this kind of diagram that make people think that program design is completly clean and careful thought ;-).

The Development Environment hides this machinery behind a pretty graphical interface.


A project is a set of files stored in one directory.

A project can contain source files (forms, classes, modules) or any data files of any types:

  • The project configuration is stored in a file named ".project".

  • The source files are stored in a sub-directory named ".src".

  • Data files are stored in the project directory or in visible sub-directories.


The Archiver is a program named gba3.

It transforms your project, the compiled files included, in one sole executable file.


The Compiler is a program named gbc3.

It transforms your project's forms, classes and modules files into binary compiled files that can be understood and executed by the interpreter.

Executable Files

A Gambas executable file is an uncompressed archive of your project, the compiled files included.

The archive file is marked as a script with the #!/usr/bin/gbx3 magic header, so that Linux executes it by calling the interpreter transparently.

Compiled Files

A compiled file is a binary representation of a class, that contains every information useful to the interpreter : functions transformed to byte code, constants, variables definitions, debugging information, etc.

Using mmap System Call

If your project was compiled as an executable, i.e. as an archive, the interpreter maps the file into memory instead of loading it. It is worth doing !

Mismatched markup: </p>


The Interpreter is a program named gbx3.

It executes the byte code of the compiled file generated by the compiler.

Class Loader

The Class Loader loads compiled forms, classes and modules into the interpreter.

Execution Unit

The Execution Unit is the heart of the interpreter.

It dispatches and executes each byte-code instruction generated by the compiler.


The Debugger is a command-line tool embedded in the interpreter.

It allows the development environment to debug a Gambas program by running it step by step, watching the stack contents, evaluating any expression in the current running context...


The Subroutines are the interpreter functions associated to the corresponding Gambas functions like Sin, Left, Stat, etc. or operators like +, -, *, &, etc.

Component Interface

The Component Interface is a set of routines and services used by the components to communicate with the interpreter.

The interpreter's internals are hidden that way.

Component Loader

The Component Loader is the part of the interpreter that loads components shared libraries, gives them access to the Component Interface, and that publishes their interface to the other components.

Native classes

The Native Classes are classes that can be used without loading any component.

They are integrated in the interpreter, and can be looked upon as a part of the Gambas language.


Components are shared libraries that are loaded at run time by the interpreter.

They can contain new classes and hook routines such as event loop management, shell arguments analyze, etc. They can publish a set of routines as an interface to other components also.

Components can be written in Gambas too. The archiver generates them as Gambas executables from Gambas projects marked as "component projects".