Creating And Using Libraries

Introduction

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.

Formalities

  • 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.
6. 
/usr/bin/<vendor>/<name>.gambas
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.
Top

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).

Top

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]

Top

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.
Top

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.

Top

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.
Top

See also