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.
  1. Create a shared library
  2. Create a library description
  3. Import library in HBasic package manager
  4. 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.