Creating bindings for C libraries
│
English (en) │
español (es) │
français (fr) │
日本語 (ja) │
русский (ru) │
Introduction
This page describes how to create Pascal bindings for C libraries. In order to use C libraries in Pascal, you have to create a pascal translation for every C function, type and variable. To do that one can either utilized an automated tool, like h2pas or do a manual headers conversion
H2PAS
Overview
The H2Pas tool that automatically translates many common C things. A GUI for Lazarus using h2pas and other tools additionally automates the creation. It helps to create a rule set, which can be used to update the bindings. So the next version of the c library can be converted far more easier. A nice feature of the h2pas wizard is that it uses temporary files, so the c header files remain unchanged.
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 the FreePascal website
Install tools
The h2pas tool comes with every normal fpc installation.
Install the h2paswizard package in the Lazarus IDE. Go to "Package->Install/Uninstall 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.
You can find more information about MPICH for FPC here.
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.
Note: If this is the first time you have used the h2pas wizard, you need to use the wizard's "Settings" tab to tell the wizard where to find the h2pas.exe converter program. The h2pas.exe converter lives in the same directory as the FreePascal compiler fpc.exe - if you downloaded FPC as part of Lazarus it will be in ...\Lazarus\fpc\version\bin. Then save the settings so you don't have to do this again.
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 h2pas-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" and "mpio.h". They will be enabled automatically. Select the mpi.h file and click "Merge all but this", so that the wizard combines all header files into one unit (mpi.pas).
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/, which is the default, 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. Then it runs the tools listed under "After h2pas" on the output files.
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', which is very unspecific. See Common problems when converting C header files.
Example: MPICH2
The h2pas wizard already contains all tools to convert all the specials of this header file, so h2pas runs without errors. But the created unit is not yet ready. Read further.
Add the following to the Undefines property:
MPI_INCLUDED MPIO_INCLUDE NEEDS_MPI_FINT MPI_BUILD_PROFILING MPICH_SUPPRESS_PROTOTYPES MPI_Wtime HAVE_MPICH2G2 FOO HAVE_PRAGMA_HP_SEC_DEF
Add the following to the Defines property:
MPICH2 MPICH_NEW_MPIIO
Writing your own converter tools
Using the tool "Search and replace"
Many things like renaming a variable can be done by the Search and replace tool. Add the tool via the Add new tool button on either the 'Before h2pas' or the 'After h2pas' page. Then set the SearchFor, ReplaceWith, Options and Caption property.
Example: rename an identifier Tguint to guint
Property | Value |
---|---|
Caption | Rename Tguint to guint |
SearchFor | Tguint |
ReplaceWith | guint |
Options | [trtMatchCase,trtWholeWord] |
Example: rename several identifiers
Rename Tguint to guint, Tgulong to gulong, Tgint to gint:
Property | Value |
---|---|
Caption | Rename Tguint to guint |
SearchFor | T(guint|gint|gulong) |
ReplaceWith | $1 |
Options | [trtMatchCase,trtWholeWord,trtRegExpr] |
Example: MPICH2
Removing Makro MPI_DUP_FN
The MPI_DUP_FN is defined two times in the mpi C headers. Once as a macro to something that does not exist, and later to a real function. So, the first should be deleted.
Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
Property | Value |
---|---|
Caption | Remove dummy define MPI_DUP_FN |
Name | RemoveDummyDefineMPI_DUP_FN |
SearchFor | ^#define\s+MPI_DUP_FN\s+MPIR_Dup_fn |
ReplaceWith | |
Options | [trtMatchCase,trtRegExpr] |
Removing typecasts to MPI_DUP_FN
Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
Property | Value |
---|---|
Caption | Remove MPI_DUP_FN Makros |
Name | Remove_MPI_DUP_Func |
SearchFor | ^#define .*MPI_DUP_FN\).*$ |
ReplaceWith | |
Options | [trtMatchCase,trtRegExpr] |
Removing functions MPIO_Test, PMPIO_Test, MPIO_Wait and PMPIO_Wait
The MPIO_Test, PMPIO_Test, MPIO_Wait and PMPIO_Wait functions are defined twice and redefined via macro. So, the functions can be removed:
Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
Property | Value |
---|---|
Caption | Remove Func P?MPIO_(Test|Wait) |
Name | RemoveFuncP_MPIO_Test_Wait |
SearchFor | ^int P?MPIO_(Test|Wait).*$ |
ReplaceWith | |
Options | [trtMatchCase,trtRegExpr] |
Improving an existing tool
You found a bug and want to fix it or you want to extend one of the above tools. Great!
Most of the above tools are defined in the h2pasconvert unit, which is part of the h2paswizard package. Basically a tool needs a classname, a description and an Execute method. To test/debug a tool outside the IDE and save a lot of compilation time, see the project components/simpleideintf/examples/testh2pastool.lpi. Compile it and start it on a console/terminal with the filename of a .h file as first command parameter. For example:
./testh2pastool files/h2pastest.pas
Writing a custom tool
You can write your own conversion tools and register them in the IDE easily. Start a package and a add a new unit (say unit1) for your new class. See the existing tools as example and read the prior section. When you wrote a new tool and tested it with the above simpleideintf project, then register it in the IDE: Add a register procedure to your unit (unit1), like the following (pseudo code):
uses
Classes, ..., IDETextConverter;
type
TYourToolClass = class(TCustomTextConverterTool)
public
class function ClassDescription: string; override;
function Execute(aText: TIDETextConverter): TModalResult; override;
end;
procedure Register;
implementation
procedure Register;
begin
TextConverterToolClasses.RegisterClass(TYourToolClass);
end;
Do not forget to enable the register checkbox of the unit in the package editor, otherwise the Register procedure will not be called by the IDE. Then install your package in the IDE.
Future work / Missing stuff
- A tool to convert static linked procedures to dynamic linked procedure variables
- A tool to fix functions without parameter names by searching the .c files. This could also add a comment, in which c file it found the function.
- Find missing identifiers and let the user check which one to comment or replace with base types.
- Create a list of macro functions, which were half translated.
C:
typedef struct page
{
u32int present : 1; // Page present in memory
u32int rw : 1; // Read-only if clear, readwrite if set
u32int user : 1; // Supervisor level only if clear
u32int accessed : 1; // Has the page been accessed since last refresh?
u32int dirty : 1; // Has the page been written to since last refresh?
u32int unused : 7; // Amalgamation of unused and reserved bits
u32int frame : 20; // Frame address (shifted right 12 bits)
} page_t;
pascal:
type
Unsigned_7 = 0 .. (1 shl 7) - 1;
Unsigned_20 = 0 .. (1 shl 20) - 1;
type
page_t = bitpacked record
present : boolean;
rw : boolean;
user : boolean;
accessed : boolean;
dirty : boolean;
unused : Unsigned_7;
frame : Unsigned_20;
end;
Manual conversion of C headers to Pascal
In this case one should utilize ones knowledge of C and Pascal together to make the headers. One can learn how to do the conversion by looking at examples.
Converting constants
C:
#define SOME_CONSTANT 5
#define ANOTHER_CONSTANT 6
pascal:
const
SOME_CONSTANT = 5;
ANOTHER_CONSTANT = 6;
Converting exported routines
The most basic routines can be translated like this:
C:
int somekind_of_method(int* param_first, int* param_second)
void another_method(char*)
pascal:
uses ctypes;
const
MyLib = 'mylib';
function somekind_of_method(param_first, param_second: pcint): cint; external name MyLib;
procedure another_method(param1: PChar); external name MyLib;
Note that one should use the ctypes unit together with the types that it declares to convert C headers instead of trying to use the basic Pascal types directly. This ensures that the bindings are correct in all platforms, as the C types might have different sizes in different architectures and operating systems.
Also note that pointers to basic C types can be converted to types declared in ctypes, for example int* is a pointer to a C int, so we can use the type pcint for it. The C type int can be converted to cint and note that in Pascal we can merge the declaration of parameters which are declared one after the other like in "param_first, param_second: pcint" which is something that C does not have and makes the declaration shorter and easier to read.
Finally, note the return value: if it is void, then we should use procedure instead of function.
Publish your bindings on Lazarus-CCR or Free Pascal
You can submit your binding code to the Lazarus CCR repository (see e.g. Using_the_Lazarus-ccr_SVN_repository) so others can use (and maintain) it, too. If the bindings are useful for general, cross-platform work, they could be included in the FreePascal distribution as well.
See also
- [1] Short tutorial that describes the process of using C and C++ code in FreePascal, including writing of wrapper code
- Common problems when converting C header files
- Pascal for C users
- Lazarus/FPC Libraries
- SWIG