In this document we want show you the three steps to create and access
a shared library from HBasic. After that you should know how to call
methods that have been implemented in C or C++ from a HBasic program.
The three steps needed to do this are:
To show you how simple it is to set up a shared object library for
HBasic we start with a single method. This method should do nothing more
than receive a value from HBasic and return a changed value. Create a
new file called testlib.cpp
with the following code in your favourite editor:
int add_two( int in_par ) { return( in_par + 2 ); }
Example: Simple method example for shared library.
To compile this source code to a library call gcc in the following way:
gcc -o testlib.so -shared -g testlib.cpp
This will create a new shared library testlib.so which exports our
method definition. Compiling the program with debuggin support will help
us to set up the library description in the following step. Since
HBasic tries to find libraries in /usr/local/hbasic/packages you may
copy the library to this directory but you can also keep it in any other
directory.
Create a library description with
libdesc
As mentioned above HBasic needs a library description to handle the
libraries imported at runtime. In this first step we create a library
description for the shared library that we have created in the last
step. To do this go to the libdesc directory of HBasic, compile the
libdesc program with make if you haven't done this already. Start
libdesc in the current directory by typing ./libdesc. In the libdesc window
you can see a list of the classes, global methods and constant
definitions that may be used in the library. Currently this list only
shows the parent folders for the empty list.
To create the description for our example select Find debug symbols
in the Library menu. A fileselect dialog will pop up where you can
select the name of the library testlib.so from our last example. The
fileselect dialog always starts with the contents of the directory
/usr/local/hbasic/packages. After you have selected the library file you
can find a new entry in the methods folder. In the left column the
method entry displays the method name add_two
with it's parameters and return value and in the right column you can
see the name of the method-symbol in the library file. This symbol
varies depending on the compiler version you use. If you compile a *.c
file the symbol name is the same than the method name. For *.cpp file
the gcc compiler encodes the method parameters in the symbol name.
Starting with gcc 3.2 the method names will be encrypted in another way
than before. This is a problem for shared library description because if
you set up a library description for a library compiled with gcc 3.1
and recompile the library later with gcc 3.2 the library description has
to be recreated with other names. Currently HBasic contains library
descriptions for gcc versions <= 3.1. Later I also will also
distribute versions for the gcc 3.2 compiler.
If you click on the button "Edit
libdesc" you will see a new dialog window where you can edit
the path of the library file and a short text description for the
library that may be displayed in the HBasic library manager later for
this library. For our example we do not need to change anything here.
We want to create the library description file now. Click on Save description in the library menu. This will pop up a new
fileselect dialog where you should select the name of the library
description file. HBasic normally searches for *.dso files when
searching for library description so you should save this file as
testlib.dso.
You can leave the libdesc program with a mouseclick on Library/Quit
libdesc application. We now want to call our library method from HBasic.
Access a shared library from HBasic
Before you can use extensions set up as a shared library you have to
tell HBasic that the library should be loaded with your project. This
can be done in the package manager. Start HBasic and click on the menu View/Package Manager to open the
package manager window. In the package manager dialog click on the
button Add package to select
the package name. A fileselect dialog appears where you can select the
name of the package description testlib.dso.
This will display the name of the file in the package list ListView
widget of the package manager together with an empty check box. Click on
this check box to load this library and insert it into your current
HBasic project. You can now see the methods exported by the library in
the package manager on the right side. Leave the package manager with a
mouseclick on the OK button. We will now create a small program to call
our library method.
Insert a new button widget in the formdesigner window, switch to the
sourcecode window and type in the following program.
Sub button1_clicked() Print add_two( 11 ) End Sub
Example: Call method from shared library.
When you start this program and click on the button the program should
display the 13 on the screen. This shows that the method has been called
and displays the correct value 11+2.