Simple shared library example
In this document we want show you the four 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.
- Create a shared
library
- Create a library description
- Import library in HBasic package manager
- Access library method from HBasic
Create a shared library
Have a look at
Creating shared
libraries for a description how you can prepare a library to be used
in the following examples.
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. Start
libdesc by typing
libdesc. In the libdesc window you can
see a list of the components, global methods and constant definitions that
may be used in the library. If you didn't load or create some subitems this
list only shows the parent folders.
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 distributes library descriptions
for gcc versions >=3.2 since all current distributions already use 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.
Loading the library description in the package
manager
If you have the shared library testlib.so and the description file testlib.dso
you can tell HBasic projects to use this library in your current project.
This will be done by adding the library description to the package list
of your project. Saving the project will store this package list and reload
it with the project file later. To add the shared library description to
your project click on
Add package and select
the testlib.dso file in the file selector dialog.
Image: HBasic package manager displaying components of
example_package
You should now see a new red symbol for the library description testlib.dso
and the methods available in this shared library. Since there are no component
definitions within this shared library descriptions (all symbols are defined
global) the ListView classlist in the package manager will stay empty for
this packages.
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.