Firebird for Linux is distributed by http://www.firebirdsql.org as a tar archive that including installation script, or as an rpm. Linux Distributions such as Ubuntu, also distribute Firebird as deb packages that are downloaded and installed from their own repositories.
Prior to installing IBX in the Lazarus IDE, you should install Firebird either using the standard tar archive or rpm or (for example under Ubuntu) by using the Debian Package manager to install the Firebird client and server. There are two Firebird architectures – Superserver and Classic. If in doubt, install the Super Server.
For example, to install Firebird under Ubuntu 10.4, enter at the command line:
sudo apt-get install firebird2.1-super
By default, IBX for Lazarus will dynamically load the Firebird 2.x client library. This is regardless of whether it is being run as part of the IDE or in a user program. Provided that this is installed then IBX for Lazarus should run “out of the box”. If IBX cannot find the client library then the IDE will have empty or missing “Firebird” and “Firebird Admin” tabs on the component palette. A user program will terminate with an error message.
The Example Database
In order to use the example application, you will also need to install the example “employee” database. This is installed by default when using the http://www.firebirdsql.org distribution. However, if installing from debian packages, you must also install the Firebird examples package (e.g. firebird2.1-examples), and then install the employee database in its correct location.
Enter the following at the command line to download and install the examples database:
for Firebird 2.1:
sudo apt-get install firebird2.1-examples
sudo gunzip /usr/share/doc/firebird2.1-examples/examples/empbuild/employee.fdb.gz
sudo chown firebird.firebird /usr/share/doc/firebird2.1-examples/examples/empbuild/employee.fdb
sudo chmod 660 /usr/share/doc/firebird2.1-examples/examples/empbuild/employee.fdb
For Firebird 2.5:
sudo apt-get install firebird2.5-examples
sudo gunzip /usr/share/doc/firebird2.5-common-doc/examples/empbuild/employee.fdb.gz
sudo chown firebird: /usr/share/doc/firebird2.5-common-doc/examples/empbuild/employee.fdb
sudo chmod 660 /usr/share/doc/firebird2.5-common-doc/examples/empbuild/employee.fdb
The employee database should now be ready for use and accessible using the alias "employee".
Distributing the Firebird Client Shared Object with your Applications
If you are distributing your application using the Debian Package Manager, then all you need to do is to include “libfbclient2” in your list of package dependencies. The Debian Package Manager will then ensure that the Firebird Client Shared Object is correctly installed.
Otherwise, you will either need to require your users to install the standard Firebird distribution, or package and install the firebird client shared object and support files with your application. As the location of these files will depend on how they were built, if you intend to package the Firebird files with your application, then you need to consult the release notes provided with the original source of these files for instructions on how and where to install them.
Using a Personal Database
Whilst client/server use of Firebird is typical and allows multi-user access to a shared database, it is also possible to use the Firebird classic library to support the use of a Personal Database, where the database is in a file owned by the user account, is accessible by a single user only and without needing to manage user passwords. This mode of use is similar to the use of the Firebird Embedded server under Windows – but does require more careful configuration. It is best described by an example:
|
1. |
Download a recent version of Firebird classic (e.g. 2.5) as a tar archive from http://www.firebirdsql.org. Open this archive and then extract the inner archive “buildroot.tar.gz” into your home directory. This should extract as a single directory with subdirectories. |
|
2. |
The extracted directory contains the default Firebird root directory files, such as “firebird.conf” and “security2.fdb”, various utilities in the “bin” directory and the libfbemded shared object in the “lib” subdirectory. |
|
3. |
Your program should contain an IBDatabase component with its properties set as follows:
|
|
4. |
If a Service API component is being used (these are on the Firebird Admin tab) then the properties of this component should be set as follows:
|
|
5. |
The program should now be compiled. |
|
6. |
Now open a command line terminal and enter the following: export FIREBIRD=$HOME/opt/firebird export LD_LIBRARY_PATH=$HOME/opt/firebird/lib <path to your program> The program should now run and load the libfbembed.so.2.5 shared object from where it was extracted. When the database is opened it is opened directly and must have its permissions set to that it is read/write to the current user account. As the default security2.fdb database is used, there is no need to prompt the user for login parameters as these defaults are known in advance. Note: the FIREBIRD environment variable tells the embedded server where it can find its support files, and the LD_LIBRARY_PATH environment variable tells the Linux loader where it can find the shared object library |
What has been achieved is the direct use of a Personal database without needing the Firebird Server to be installed on the system. Access controls are normal file controls and the database is typically private to the owning user. There is no shared access.
You could deploy your program with the contents of the “lib” directory and, as a minimum, the firebird.conf, firebird.msg and security2.fdb files, and start it with a startup script that is a variation on the above. The location of these files is not important as long as the above environment variable correctly identify where they are located and the directory containing the firebird.conf file is read/write to the current user.
Alternatively, you may prefer to use standard Firebird packages from your distribution. In which case read this.
Using a Different Firebird shared object library
There are alternative Firebird libraries that can be used. The Firebird 1.x client should work with IBX for Lazarus; you may want to experiment with a later version of Firebird. You could also use the Firebird Classic library (libfbembed.so.x).
The easiest way to make IBX for Lazarus to load a different library is to use the FBLIB environment variable (see above example). This can be set before running the Lazarus IDE (to make IBX load a different Firebird library when running in the IDE) or before running a user program. For example, entering the following commands into a command line shell, will run the Lazarus IDE with the Firebird 1.5 client library.
export FBLIB=libfbclient.so.1.5
startlazarus
Note that if you are using a Firebird library that is not in a standard location, then you may also want to set the LD_LIBRARY_PATH environment variable to the directory in which the Firebird library is located.
Alternatively, the name of an alternative library can be compiled into a user program. The “IBINTF” unit contains a callback function OnGetLibraryName. If this is set then it is called by the library loader before loading the Firebird Library and is expected to return the name of a shared object library. This function needs to be defined in the initialization section of a unit loaded before IBX i.e. early on in the initialization sequence. This can be achieved by placing the name of the unit in the “uses” clause of the progam's .lpr file immediately after the “interfaces” unit.
How IBX for Lazarus located and loads the Firebird Shared Object Library
By default, IBX will look for and dynamically load the libfbclient.so.2 shared object. This is typically deployed as a soft link to the most recent version of the Firebird 2.x library. As long as this has been installed in a location known to the Linux loader then IBX will work “out of the box”. However, if this library is in a non-standard location then you may need to set the LD_LIBRARY_PATH environment variable prior to running the Lazarus IDE or your program.
IBX will also recognise the FBLIB environment variable. If present, then this overrides the default name for the shared object library and can be used to point IBX at any different version of the Firebird Library including the embedded server. For example, to use the embedded server, enter the command:
export FBLIB=libfbembed.so.2
before running the IDE or your program. Note, as above, if the shared library is not in a standard location then you may need to set the LD_LIBRARY_PATH.
In your program, you can also create an event handler for the OnGetLibraryName event defined in the IBIntf Unit. The event handler should be set in an initialization section and has the type:
procedure(var libname: string)
If present, then it is called prior to loading the shared object library and is expected to return the library name in its var parameter. This overrides the default library name, but can still be overridden by the FBLIB environment variable. A typical use for this event handler is to dynamically determine whether the Firebird Client library or the Embedded Server is to be used..