Creating bindings for C libraries

Overview

This page describes how to create pascal bindings for C libraries. Normally Pascal can not use C libraries directly. You have to create for every C function, type, variable a pascal translation. There is the h2pas tool, which can automatically translate many common C things. And there is a GUI for Lazarus using h2pas and other tools to automate the creation, so that if the bindings need to be updated you don't have to restart all over.

Work flow

• Fetch the C header files you want to translate.
• Create a working directory and give your bindings a name
• Create a new h2pas project with the h2pas wizard.
• add the .h files to the project
• setup the h2pas options
• run the wizard
• fix errors by adding text tools and run the wizard again
• when h2pas runs without errors, test compilation and add optional tools to beautify the output
• write some test programs to test your bindings
• publish your bindings on lazarus-ccr or Free Pascal

Install tools

The h2pas tool comes with every normal fpc installation.

Install the h2paswizard package in the Lazarus IDE. Go to "Components -> Configure installed packages ...", select from the right list the H2PasWizard package and click 'Install selection', then 'Save and rebuild IDE'. Restart the IDE and you get a new menu entry: Tools -> h2pas

Fetch C header files

The C header files .h describes the interface of a C library. They are normally not provided with the library. You have to get the sources or the development package of the library. For example the C header files of the gtk libraries are in the package gtk+-devel.

Example: MPICH2

Download the mpich2-1.0.3.tar.gz from http://www-unix.mcs.anl.gov/mpi/mpich2/ and unpack them. The .h files are under mpich2-1.0.3/src/include.

Create a working directory and name your bindings

Create a directory with a useful name. A name should not contain special characters, like spaces, umlaute, points or commas. Copy the .h files.

Example: MPICH2

The h2p directory will be used for the pascal files. The h2p/c_sources directory will be used for the .h files.

 mkdir -p h2p/c_sources
 cp mpich2-1.0.3/src/include/*.h h2p/c_sources

Create a new h2pas project with the h2pas wizard

Open the h2pas wizard: "Tools -> h2pas". This will open a window. You can switch between this window and the other IDE windows. Your last h2pas project will be loaded automatically. To create a new project click on "Settings -> New/Clear settings". Then click on the bottom button "Save settings" and choose a filename.

Example: MPICH2

Click on "Settings -> New/Clear settings". Then click on the bottom button "Save settings" and save it as h2p/mpi2.h2p.

Add the .h files to the project

In the "C header files" page you can add/delete the .h files. You can enable/disable .h files to convert only part of the files.

Example: MPICH2

Click on "C header files -> Add .h files ..." and select "mpi.h". It will be enabled automatically.

Setup the h2pas options

Under "h2pas Options" you can set the parameters for the h2pas program.

Example: MPICH2

• Enable -e, -D, -p, -w and disable all others.
• The -l library path is "mpich".
• Output extension is ".pas"
• Output directory is h2pas/, so leave it empty

Run the wizard

Click on the bottom button "Run h2pas". This will copy the <example>.h file to a temporary <example>.tmp.h file and run the tools listed under "Before h2pas". Then it runs h2pas to convert the <example>.tmp.h into <example>.inc or <example>.pas or whatever output extension you setup on the h2pas page.

If h2pas finds a syntax error, the IDE will open the example.tmp.h file and jumps to the error line. h2pas often only reports 'syntax error'. See below for a list of common problems and possible fixes.

Example: MPICH2

The h2pas wizard already contains all tools to convert all the specials of this header file, so it runs without errors.

h2pas reports an error

Here is a list of common C structures, not recognized by h2pas and how to fix them:

h2pas problem: extern "C"

Some header files contain the C++ namespace block:

 #if defined(__cplusplus)
 extern "C" {
 #endif
 ...
 #if defined(__cplusplus)
 }
 #endif

Fix: Add the Remove C++ 'extern "C"' lines to the before h2pas tools.

h2pas problem: Empty macro

Some header files contain empty macros used for further extensions:

 #define MPI_FILE_DEFINED

Fix: Add the Remove empty C macros to the before h2pas tools.

h2pas problem: Implicit array types

C allows implicit arrays in parameter types. For example:

 int MPI_Group_range_incl(MPI_Group, int, int [][3], MPI_Group *);

The int [][3] is an implicit type, which is not allowed under Pascal. h2pas supports adding pointer types. So, it enough to replace all [] with *.

Fix: Add the Replace [] with * to the before h2pas tools.

h2pas problem: Makros for 0 pointers

Some header files contain typed 0 pointers:

 #define MPI_BOTTOM      (void *)0

Fix: Add the Replace macro values 0 pointer like (char *)0 with NULL to the before h2pas tools.

Test compilation and add tools to beautify the output

When h2pas runs without errors it has created a pascal file. The -i switch defines if it is a unit or an include file. The next step is test compilation. Setup up a test project that uses the new pascal source. Then use the 'Run h2pas and compile' button in the h2pas wizard.

Example: MPICH2

Create a new project with Project -> New Project -> Program. Save it a mpihelloworld. Change the code to

program MPIHelloWorld;

{$mode objfpc}{$H+}
{$linklib mpich}
{$linklib rt}

uses
  {$IFDEF UNIX}pthreads{$ENDIF}, MPI;

begin
  MPI_Init(@argc, @argv);
  writeln('Hello, world.');
  MPI_Finalize;
end.

Add the h2p/mpi.pas to the project. Project -> Add editor file to project.

Common compiler errors on h2pas output

Sometime h2pas does not create valid pascal code. Here are the common problems and how to fix them.

Unit name contains the file path

h2pas sometimes add the whole path to the unitname.

Fix: Add Replace "unit filename;" with "unit name;" to the After h2pas tools.

Forward type not resolved

For example: mpi.pas(26,16) Error: Forward type not resolved "PMPI_Aint" The error line is often a pointer type to a record:

 PMPI_Aint = ^MPI_Aint;

h2pas adds PMPI_Aint to give nameless C pointers like *MPI_Aint a name. It adds the pointers to the start of the file. But pascal requires, that the forward definition is in the same type section.

Fix: First check if h2pas has added the PMPI_Aint a second time. If the PMPI_Aint is defined twice, then you can delete one. The first one was added by h2pas, so delete that one.

ToDo: write a tool to delete double defined pointers.

Removing system types

h2pas adds some system types, like PLongint, which are nowadays part of the system unit.

Fix: Add Remove type redefinitons like PLongint to the After h2pas tools.

Empty type/var/const sections

After the above tools removed some variables, types, constants some setions become empty, which is not allowed in pascal.

Fix: Add Remove empty type/var/const sections to the After h2pas tools.

Publish your bindings on lazarus-ccr or Free Pascal

ToDo

Writing your own converter tools

ToDo