Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
About The Best Formula In The World
Architecture details
By Reference Argument Passing
Compatibility between versions
Creating And Using Libraries
Database Datatype Mapping
Database Request Quoting
Date & time management
Dates and calendars
DBus and Gambas
Differences Between Shell And Exec
Differences From Visual Basic
Distributions & Operating Systems
Drag & Drop
DrawingArea Internal Behaviour
External functions datatype mapping
Frequently Asked Questions
Gambas Farm Server Protocol
Gambas Mailing List Netiquette
Gambas Markdown Syntax
Gambas Naming Conventions
Gambas Object Model
Gambas Scripting
Gambas Server Pages
Gambas Unit Testing
Gambas Wiki Markup Syntax
Getting Started With Gambas
Hall Of Fame
Image Management In Gambas
Including Help Comments in Source Code
Interpreter limits
Just In Time Compiler
Just In Time Compiler (old version)
Localisation and Internationalization
Mailing Lists & Forums
Naming Conventions
Network Programming
ODBC Component Documentation
PCRE Pattern Syntax
Porting from Gambas 2 to Gambas 3
Previous News
Project Directory Structure
Release Notes
Reporting a problem, a bug or a crash
Rich Text Syntax
Text highlighting definition file syntax
The Program has stopped unexpectedly by raising signal #11
Variable Naming Convention
WebPage Syntax
Web site home page
What Is Gambas?
Window & Form Management
Window Activation & Deactivation
Window Life Cycle
Error Messages
Gambas Playground
How To's
Language Index
Language Overviews
Last Changes
Search the wiki
To Do
Wiki License
Wiki Manual

Creating And Using Libraries


Gambas libraries allow you to share code among your projects. This is extremely useful, as soon as you write larger projects or a even a couple of projects that have some functionality or objects in common.

Libraries are Gambas executables that can be used in another project, rather than Components that are extensions to the Gambas language.


  • Should always make libraries for own code sharing needs rather than components, and should/could be distributed with the projects

  • Components are like extensions to the Gambas language, and should/could be distributed with the Gambas source code.

Library Search Paths

When a project that depends on a library is executed, the library executable is searched for in the following paths, in the following order:
Order Path Comment
1. <project executable directory>/<name>.gambas for backward-compatibility.
2. $XDG_DATA_HOME/gambas3/lib/<vendor>/<name>:<version>.gambas if $XDG_DATA_HOME is defined.
3. ~/.local/share/gambas3/lib/<vendor>/<name>:<version>.gambas if $XDG_DATA_HOME is NOT defined.
4. <project extra archive directory>/<vendor>/<name>:<version>.gambas the project extra archive directory is a project property defined in the library tab of the project property dialog.
5. /usr/lib[/multiarch]/gambas3/<vendor>/<name>:<version>.gambas Binary library packages (created by the Gambas IDE packager) are installed there by default and are available system-wide (important for multi-user computers). The multiarch depends on distribution, in Debian based depends on implementation level, see Debian Multiarch
Currently, (as at 19-Jun-2017), the Gambas autotools packager does not implicitly support this rule. It installs libraries according to the local distibution's settings for the automake utilities.
The use of /usr/lib (regardless of qualifier subdirectories) for the installation of NON-distro software contravenes the LSB File System Heirarchy (FSH) standard. In particular, re-installation or upgrades from the distro may, and in all probability will overwrite the /usr/lib directory. The FHS (ver 3.0), at section 4.9 specifically addresses the issue of locally installed software and recommends the use of the usr/local heirarchy.
because standard programs written in Gambas can be used as libraries.
As above the use of the /usr/bin path (regardless of qualification) contravenes the FSH. Locally installed software may be overwritten or deleted by system upgrades.

The first and last are mainly only there for backward-compatibility.

The 2. & 3 locations are there for installation of libraries for the current user. Libraries are installed automatically on this "single-user-wide" basis when you make an executable from their source project, or when you install a library from the Gambas farm.
This "single-user-wide basis is actually quite handy as it lets you (the developer and/or tester) use the latest i.e. your "unstable" version instead of having to clobber the system wide "stable" version.

How to make a library from a project?

Just create a normal Gambas project. In the project properties dialog, choose 'Library' as type of the project. Fill in the vendor name (important!).

Only the classes marked with the EXPORT keyword will be exported and visible to the project using that library.

Note that main.module will always be invisible, you can use main.module for testing or as a class to share commands internally with the other classes in your library but nothing in main.module will be exported.

Then make the project executable. The executable will be installed in (3).


How to use a library in a project?

Open another project. Open the project's property dialog and go to the 'Libraries' tab. Here you can add all libraries installed. If you use a library that depends on another library you will have to define the right order the libraries will be loaded from top (first) to bottom (last).

[This needs more explanation]


How to install a library system-wide on this or another computer?

Create an installation package from your library (Ctrl-Alt-I). Install this package on the target computer. If you install this package on the other computer the library will there be installed in (5).

Note that the search order will always prefer the version in your user home directory over the system one. So, when you are finished testing, make sure you remove the local i.e. single-user-wide copy.

How to test a library

You can implement tests for your library within itself. Remember, only classes marked as EXPORT are visible (exposed) to the project using the library (excluding main.module). So within the library project itself you can include unexposed classes or modules to test the features of your library. A projects default main.module is ideal for testing as it will not be exposed and can be set as a startup class in the IDE to run your tests.


More advanced topics

Accessing files using relative paths

Sometimes you may wish to access a file using a relative path. But in which executable? The library executable or the executable for the project using the library. To access a file in the library executable itself, just start the relative path with the ./ sequence. if you need to access a file located in the main project you must start your relative path by the ../ sequence.

Library dependencies

[To be written]

"Initialising" a library

Occasionally, you might require your library to do some automatic "start up" processing when it is loaded as the main project executes. That is, your library needs to do something even before your main project tries to use one of its' exposed features.

One way to achieve this is to expose a callable routine (say a "StartUp" method in an exported module) so that the main program can call that method before it uses any more useful features. Once you have done this a few times it can become apparent that this is painful ... you have to make that call in anything in your main project that could be the "first" user of the library and further you will probably have to keep track inside the library as to whether the start up has been done or not, etc etc.

There is a better way. It will happen automatically and independently of your main project execution logic.[More to come...]

Distributing libraries

Should you distribute your software and associated libraries to users on other systems take special note of the warnings above about non-conformance to the FSH standard.

See also