Difference between revisions of "Creating bindings for C libraries/fr"

From Free Pascal wiki
Jump to navigationJump to search
(New page: {{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...)
 
 
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{Creating bindings for C libraries}}
 
{{Creating bindings for C libraries}}
  
−
=Overview=
+
=Introduction=
 +
Cette page décrit comment créer des '''liaisons Pascal bindings''' pour des '''bibliothèques C'''.
 +
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
  
−
This page describes how to create '''pascal bindings''' for '''C libraries'''. Normally Pascal can not use C libraries directly. You have to create a pascal translation for every C function, type and variable. 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. And the GUI helps to create a rule set, that can be used to update the bindings. So the next version of the c library can be converted far more easier.
+
=Vue générale=
 +
 
 +
[NdT: Je laisse le terme de bindings, plus parlant que commissionaire ou intermédiaire]
 +
Cette page décrit comment créer des '''pascal bindings''' pour les '''bibliothèques C'''. Normalement Pascal ne peut pas utiliser directement des bibliothèques C. Vous devez créer une traduction Pascal pour chaque fonction, type et variable C. Il y a l'outil [[H2Pas/fr|H2Pas]] qui peut traduire automatiquement les choses les plus courantes en C. Et il existe une GUI pour Lazarus utilisant h2pas et autres outils pour automatiser leur création. Et la GUI aide a créer un ensemble de règles qui permet de mettre à jour les bindings. Donc la version suivante de la bibliothèque C peut être convertie plus facilement. Une caractéristique sympa de l'assistant h2pas est qu'il utilise automatiquement des fichiers temporaires, donc les fichiers header C ne seront jamais changés automatiquement.  
  
 
==Work flow==
 
==Work flow==
  
−
*Fetch the C header files you want to translate.
+
*Trouvez les fichiers header C que vous voulez traduire.
−
*Create a working directory and give your bindings a name
+
*Créez un dossier de travail et donnez un nom à vos liaisons
−
*Create a new h2pas project with the h2pas wizard.
+
*Créez uun nouveau projet h2pas à l'aide de l'assistant de h2pas.
−
*add the .h files to the project
+
*ajoutez les fichiers .h au projet
−
*setup the h2pas options
+
*configurez les options de h2pas
−
*run the wizard
+
*lancez l'assistant (pas trop fort)
−
*fix errors by adding text tools and run the wizard again
+
*solutionnez les erreurs en ajoutant les outils de texte et en lançant à nouveau l'assistant
−
*when h2pas runs without errors, test compilation and add optional tools to beautify the output
+
*lorsque h2pas se lance sans erreurs, testez la compilation et ajoutez des outils optionnels pour enjoliver la sortie
−
*write some test programs to test your bindings
+
*écrivez quelques programmes de test pour essayer votre bindings
−
*publish your bindings on lazarus-ccr or the Free Pascal website
+
*publiez votre bindings sur lazarus-ccr ou le site du Free Pascal
  
−
=Install tools=
+
=Installation des outils=
  
−
The h2pas tool comes with every normal fpc installation.
+
L'outil h2pas est livré avec toutes les installations normales des FPC.
  
−
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'.
+
Installez le package h2paswizard dans l'IDE de Lazarus. Allez dans "Composants -> Configurer les paquets installés...", sélectionnez dans la liste de droitele package H2PasWizard et cliquez sur 'Installer la sélection', puisn 'Sauver et reconstruire l'IDE'.
−
Restart the IDE and you get a new menu entry: Tools -> h2pas
+
Relancez l'IDE et vous aurez une nouvelle entrée de menu: Outils -> h2pas
  
−
=Fetch C header files=
+
=Trouvez les fichiers header C=
  
−
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.
+
Les fichiers header C .h décrivent l'interface d'une bibliothèque C. Ils ne sont normalement pas livrés avec la bibliothèque. Vous devez avoir les sources ou le package de développement de la bibliothèque. Par exemple, les fichiers header C de la bibliothèque GTK se trouve dans le paquet gtk+-devel.
  
−
===Example: MPICH2===
+
===Exemple: 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.
+
Téléchargez mpich2-1.0.3.tar.gz depuis http://www-unix.mcs.anl.gov/mpi/mpich2/ et décompressez le. Les fichier .h se trouvent sous mpich2-1.0.3/src/include.
  
−
=Create a working directory and name your bindings=
+
=Créez un dossier de travail et nommez votre  bindings=
  
−
Create a directory with a useful name. A name should not contain special characters, like spaces, umlaute, points or commas.
+
Créez un dossier avec un nom pratique. Un nom ne doit pas contenir de caractères spéciaux comme des espaces, des tréma allemands, des points ou des virgules.
−
Copy the .h files.
+
Copiez les fichiers .h.
  
−
===Example: MPICH2===
+
===Exemple: MPICH2===
  
−
The h2p directory will be used for the pascal files.
+
Le dossier h2p sera utilisé par les fichiers pascal.
−
The h2p/c_sources directory will be used for the .h files.
+
Le dossier h2p/c_sources sera utilisé par les fichiers .h.
  
 
   mkdir -p h2p/c_sources
 
   mkdir -p h2p/c_sources
 
   cp mpich2-1.0.3/src/include/*.h h2p/c_sources/
 
   cp mpich2-1.0.3/src/include/*.h h2p/c_sources/
  
−
=Create a new h2pas project with the h2pas wizard=
+
=Créez un nouveau projet h2pas avec l'assistant de h2pas=
−
 
 
−
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/, 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.
 
−
 
 
−
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 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 h2pas runs without errors. But the created unit is not yet ready. Read further.
 
−
 
 
−
=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
 
−
 
 
−
<pre>
 
−
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.
 
−
</pre>
 
−
 
 
−
Add the h2p/mpi.pas to the project. Project -> Add editor file to project.
 
−
 
 
−
=Common compiler errors on h2pas output=
 
−
 
 
−
Sometimes 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.
 
−
 
 
−
==Missing include files==
 
−
 
 
−
h2pas converts #include directives to pascal {$i } directives. If you create a unit for wach header file, then you can remove all include directives with the tool '''Remove includes'''.
 
  
−
==Forward type not resolved==
+
Ouvrez l'assistant de h2pas: "Outils -> h2pas". Cela va ouvrir une fenêtre. Vous pouvez alterner entre cette fenêtre et les autres fenêtres de l'IDE. Votre dernier projet h2pas sera chargé automatiquement. Pour créer un nouveau projet, cliquez sur "Configuration -> Nouveau/Effacer Configuration". Cliquez alors sur le bouton du bas "Sauver la configuration" et choisissez un nom de fichier.
  
−
For example: '''mpi.pas(26,16) Error: Forward type not resolved "PMPI_Aint"'''
+
Note: Si vous utilisez l'assistant h2Pas pour la première fois, vous aurez besoin de passer par l'onglet "Settings" pour dire à l'assistant où trouver le programme de conversion h2pas.exe. Le convertisseur h2pas.exe réside dans le même répertoire que le compilateur FreePascal fpc.exe - si vous avez téléchargé FPC comme une partie de Lazarus, il sera dans ...\Lazarus\fpc\''version''\bin. Ensuite enregistrez la configuration ainsi vous n'aurez pas à la refaire.
−
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.
 
−
Sometimes h2pas adds a pointer type, although it already exists.
 
  
−
Fix:  
+
===Exemple: MPICH2===
−
Add the tool '''Remove redefined pointer types''' to the '''After h2pas''' tools.
 
  
−
==Removing system types==
+
Cliquez sur "Configuration -> Nouveau/Effacer Configuration". Cliquez alors sur le bouton du bas "Sauver la configuration" et sauvez la en tant que h2p/mpi2.h2p.
  
−
h2pas adds some system types, like PLongint, which are nowadays part of the system unit.
+
=Ajoutez les fichiers .h au projet h2pas=
  
−
Fix: Add '''Remove type redefinitons like PLongint''' to the '''After h2pas''' tools.
+
Dans la page "C header files" vous pouvez ajouter/supprimer les fichiers .h. Vous pouvez activer/désactiver les fichiers .h afin de convertir seulement certains de ces fichiers.
  
−
==Empty type/var/const sections==
+
===Exemple: MPICH2===
  
−
After the above tools removed some variables, types, constants some setions become empty, which is not allowed in pascal.
+
Cliquez sur "C header files -> Add .h files ..." et selectionnez "mpi.h" et "mpio.h". Ils seront activés automatiquement. Sélectionnez le fichier mpi.h et cliquez sur "Merge all but this", comme ça l'assistant combine tous les fichiers d'entête en une unique unité (pléonasme !) mpi.pas.
  
−
Fix: Add '''Remove empty type/var/const sections''' to the '''After h2pas''' tools.
+
=Configurez les options de h2pas=
  
−
==Implicit Types==
+
Sous "Options de h2pas" vous pouvez configurer les paramètres du programme h2pas.
  
−
C allows implicits types in parameters. For example: ''int [][3]''. Pascal does not allow this, so you must give it a name and declare a type. But h2pas does not do this automatically and adds instead the implicit type in a quasi pascal syntax. For example:
+
===Exemple: MPICH2===
  
−
  int some_func(int [][3]);
+
*Activez -e, -D, -p, -w et désactivez tous les autres.
 +
*Le chemin de bibliothèque de -l  est "mpich".
 +
*L'extension de sortie est ".pas"
 +
*Le dossier de sortie est h2pas/, qui est par défaut, donc laissez le vide
  
−
becomes
+
=Lancez l'assistant=
  
−
  function some_func(_para1:array[0..2] of Plongint):longint;cdecl;external;
+
Cliquez sur le bouton du bas "Lancer h2pas".
 +
Cela va copier le fichier <example>.h dans un dossier temporaire <example>.tmp.h et lancer les outils listés sous "Avant h2pas". Il lance alors h2pas pour convertir <example>.tmp.h en <example>.inc ou <example>.pas ou autre extension de sortie que vous avez configuré dans la page h2pas. Ensuite il lance les outils listés sous "Après h2pas" sur les fichiers de sortie.
  
−
Fix: Luckily there is now a tool to remove these implicit types and add explicit types, it's called '''Replace implicit types'''. Add it to the ''after'' tool list.
+
Si h2pas trouve une erreur de syntaxe, l'IDE va ouvrir le fichier example.tmp.h et sauter à la ligne de l'erreur. h2pas rapporter souvent seulement des 'syntax error', qui son vraiment non spécifiques. Voir [[Common problems when converting C header files]].
  
−
==Array of nothing==
+
===Exemple: MPICH2===
  
−
Sometimes h2pas converts the C ellipsis parameter type '...' wrongly to 'array of )'. It should be 'array of const)'.
+
L'assistant de h2pas contient déjà tous les outils pour convertir tout ce qui est spécial dans ce fichier header, donc h2pas se lance sans erreur. Mais l'unité crée n'est toujours pas prête. Lisez plus loin.
  
−
Fix: Add the tool '''Fix open arrays''' to the after tools.
+
Ajoutez ceci à la propriété''Undefines'':
 +
  MPI_INCLUDED
 +
  MPIO_INCLUDE
 +
  NEEDS_MPI_FINT
 +
  MPI_BUILD_PROFILING
 +
  MPICH_SUPPRESS_PROTOTYPES
 +
  MPI_Wtime
 +
  HAVE_MPICH2G2
 +
  FOO
 +
  HAVE_PRAGMA_HP_SEC_DEF
  
−
==Identifier not found==
 
  
−
There are three cases:
+
Et ceci à la propriété ''Defines'':
 +
  MPICH2
 +
  MPICH_NEW_MPIIO
  
−
*[[#The identifier is defined in the unit, but after it is used|The identifier is defined in the unit, but after it is used]]
+
=Publiez votre bindings sur lazarus-ccr ou Free Pascal=
−
*[[#The identifier is defined in another unit (another .h file)|The identifier is defined in another unit (another .h file)]].
 
−
*[[#The identifier is not defined anywhere|The identifier is not defined anywhere]].
 
−
 
 
−
===The identifier is defined in the unit, but after it is used===
 
−
 
 
−
In pascal forward defined types are only allowed in a type section. For example:
 
−
  type
 
−
    TMyRecord = record
 
−
      Next: PMyRecord; // using the forward definition
 
−
    end;
 
−
    PMyRecord = ^TMyRecord;
 
−
 
 
−
The below is not allowed, because the forward definition is in another type section:
 
−
  type
 
−
    TMyRecord = record
 
−
      Next: PMyRecord; // using the forward definition
 
−
    end;
 
−
  type
 
−
    PMyRecord = ^TMyRecord;
 
−
 
 
−
Solution: The code must be reordered. There is no tool yet, to do this automatically.
 
−
 
 
−
===The identifier is defined in another unit (another .h file)===
 
−
 
 
−
Solution: Add the unit to the uses section.
 
−
 
 
−
If the other unit is already using this unit, then you have a circle. A circle dependency is allowed between .h files, but not between pascal units. In this case you must move code between both units or use IFDEFs like the gtk2 bindings. There is no tool yet to do that automatically.
 
−
 
 
−
====Proposal====
 
−
 
 
−
A tool to fix most of the above issues could work this way:
 
−
Gather all constants of all units of the bindings and put them into one big constant section.
 
−
Do the same for all types and put them all into one big type section behind the constant section.
 
−
 
 
−
Disdadvantage: You can no longer see, which identifier belongs to which .h file. At least some comments should be added.
 
−
 
 
−
===The identifier is not defined anywhere===
 
−
 
 
−
Probably you are missing a header file or you are using one with the wrong version.
 
−
 
 
−
Solution: Search the header file or comment the identifier. There is no tool yet to comment missing identifiers.
 
−
 
 
−
=Publish your bindings on lazarus-ccr or Free Pascal=
 
  
 
ToDo
 
ToDo
  
−
=Writing your own converter tools=
+
=Ecrivez vos propres outils de conversion=
  
−
==Using the tool "Search and replace"==
+
==Utilisez l'outil "Recherche et remplacement"==
  
−
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.
+
Bien des choses come le renommage d'une variable peuvent être effectuées par l'outil '''Rechercher et remplacer'''. Ajoutez l'outil via le bouton '''Ajouter un nouvel outil''' sur l'une des pages 'Avant h2pas' ou 'Après h2pas'.
−
Then set the '''SearchFor''', '''ReplaceWith''', '''Options''' and '''Caption''' property.
+
Configurez alors les propriétés '''SearchFor''', '''ReplaceWith''', '''Options''' et '''Caption'''.
  
−
===Example: rename an identifier Tguint to guint===
+
===Exemple: renommer un identifiant Tguint en guint===
  
 
{| BORDER="1" CELLSPACING="0"
 
{| BORDER="1" CELLSPACING="0"
Line 283: Line 133:
 
|}
 
|}
  
−
===Example: rename several identifiers===
+
===Exemple: renommer plusieurs identifiants===
  
−
Rename Tguint to guint, Tgulong to gulong, Tgint to gint:
+
Renommer Tguint en guint, Tgulong en gulong, Tgint en gint:
  
 
{| BORDER="1" CELLSPACING="0"
 
{| BORDER="1" CELLSPACING="0"
Line 300: Line 150:
 
|}
 
|}
  
−
==Improving an existing tool==
+
==Améliorer un outils existant==
  
−
You found a bug and want to fix it or you want to extend one of the above tools. Great!
+
Vous pouvez trouver un bug et vouloir le solutionner ou vouloir étendre un des outils ci-dessus. Super!
  
−
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.
+
La plupart des outils ci-dessus sont définis dans l'unité h2pasconvert qui fait partie du package h2paswizard. Basiquement un outil nécessite une classname, une description et une méthode '''Execute'''.
−
To test/debug a tool outside the IDE and save a lot of compilation time, see the project components/simpleideintf/examples/testh2pastool.lpi.
+
Pour tester/debugger un outil en dehors de l'IDE et sauver beaucoup de temps de compilation, regardez le projet 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:
+
Compilez-le et lancez-le dans une console/terminal avec un nom de fichier .h comme premier paramètre. Par exemple:
 
   ./testh2pastool files/h2pastest.pas
 
   ./testh2pastool files/h2pastest.pas
  
  
−
==Writing a custom tool==
+
==Ecrire un outil personnalisé==
  
−
You can write your own conversion tools and register them in the IDE easily.
+
Vous pouvez écrire vos propres outils de conversion et les enregistrer facilement dans l'IDE.
−
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.
+
Démarrez un package et ajoutez une nouvelle unité (disons unit1) pour votre nouvelle classe. Regardes les outils existant comme exemple et lisez la section précédente.
−
When you wrote a new tool and tested it with the above simpleideintf project, then register it in the IDE:
+
Lorsque vous avez écrit et testé votre nouvel outil avec le projet simpleideintf project, enregistrez-le dans l'IDE:
−
Add a '''register''' procedure to your unit (unit1), like the following (pseudo code):
+
Ajoutez une procedure '''register''' à votre unité (unit1), comme suivant (pseudo code):
  
 
<pre>
 
<pre>
Line 338: Line 188:
 
</pre>
 
</pre>
  
−
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.
+
Ne pas oublier d'activer la case a cocher '''register''' de l'unité dans l'éditeur de package, autrement la procédure Register procedure ne sera pas appellée par l'IDE.
−
Then install your package in the IDE.
+
Installez alors votre package dans l'IDE.
 +
 
 +
=travail futur / fonctions manquantes=
 +
 
 +
*Un outil pour réordonner une unité pour solutionner les définitions forward. Cela requiert un outil pour retirer les IFDEFs non nécessaires.
 +
*Un outil pour solutionner les fonctions sans noms de paramètres en cherchant les fichiers .c. Cela pourrait également ajouter en commentaire dans quel fichier C se trouve la fonction.
 +
*Trouver des identifiants manquants et laisser l'utilisateur checker lesquels commenter ou remplacer avec les types de base.
 +
*Créer une liste de fonctions macro qui ont été seulement à moitié traduites.
  
−
=Future work / Missing stuff=
 
  
−
*Extend the wizard to convert a set of .h files into one unit. This would solve many circle definitions automatically.
+
{{AutoCategory}}
−
*Find missing identifiers and let the user check which one to comment.
 
−
*Create a list of macros, which were half translated.
 

Latest revision as of 00:16, 21 April 2022

│ English (en) │ español (es) │ français (fr) │ 日本語 (ja) │ русский (ru) │

Introduction

Cette page décrit comment créer des liaisons Pascal bindings pour des bibliothèques C. 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

Vue générale

[NdT: Je laisse le terme de bindings, plus parlant que commissionaire ou intermédiaire] Cette page décrit comment créer des pascal bindings pour les bibliothèques C. Normalement Pascal ne peut pas utiliser directement des bibliothèques C. Vous devez créer une traduction Pascal pour chaque fonction, type et variable C. Il y a l'outil H2Pas qui peut traduire automatiquement les choses les plus courantes en C. Et il existe une GUI pour Lazarus utilisant h2pas et autres outils pour automatiser leur création. Et la GUI aide a créer un ensemble de règles qui permet de mettre à jour les bindings. Donc la version suivante de la bibliothèque C peut être convertie plus facilement. Une caractéristique sympa de l'assistant h2pas est qu'il utilise automatiquement des fichiers temporaires, donc les fichiers header C ne seront jamais changés automatiquement.

Work flow

  • Trouvez les fichiers header C que vous voulez traduire.
  • Créez un dossier de travail et donnez un nom à vos liaisons
  • Créez uun nouveau projet h2pas à l'aide de l'assistant de h2pas.
  • ajoutez les fichiers .h au projet
  • configurez les options de h2pas
  • lancez l'assistant (pas trop fort)
  • solutionnez les erreurs en ajoutant les outils de texte et en lançant à nouveau l'assistant
  • lorsque h2pas se lance sans erreurs, testez la compilation et ajoutez des outils optionnels pour enjoliver la sortie
  • écrivez quelques programmes de test pour essayer votre bindings
  • publiez votre bindings sur lazarus-ccr ou le site du Free Pascal

Installation des outils

L'outil h2pas est livré avec toutes les installations normales des FPC.

Installez le package h2paswizard dans l'IDE de Lazarus. Allez dans "Composants -> Configurer les paquets installés...", sélectionnez dans la liste de droitele package H2PasWizard et cliquez sur 'Installer la sélection', puisn 'Sauver et reconstruire l'IDE'. Relancez l'IDE et vous aurez une nouvelle entrée de menu: Outils -> h2pas

Trouvez les fichiers header C

Les fichiers header C .h décrivent l'interface d'une bibliothèque C. Ils ne sont normalement pas livrés avec la bibliothèque. Vous devez avoir les sources ou le package de développement de la bibliothèque. Par exemple, les fichiers header C de la bibliothèque GTK se trouve dans le paquet gtk+-devel.

Exemple: MPICH2

Téléchargez mpich2-1.0.3.tar.gz depuis http://www-unix.mcs.anl.gov/mpi/mpich2/ et décompressez le. Les fichier .h se trouvent sous mpich2-1.0.3/src/include.

Créez un dossier de travail et nommez votre bindings

Créez un dossier avec un nom pratique. Un nom ne doit pas contenir de caractères spéciaux comme des espaces, des tréma allemands, des points ou des virgules. Copiez les fichiers .h.

Exemple: MPICH2

Le dossier h2p sera utilisé par les fichiers pascal. Le dossier h2p/c_sources sera utilisé par les fichiers .h. 

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

Créez un nouveau projet h2pas avec l'assistant de h2pas

Ouvrez l'assistant de h2pas: "Outils -> h2pas". Cela va ouvrir une fenêtre. Vous pouvez alterner entre cette fenêtre et les autres fenêtres de l'IDE. Votre dernier projet h2pas sera chargé automatiquement. Pour créer un nouveau projet, cliquez sur "Configuration -> Nouveau/Effacer Configuration". Cliquez alors sur le bouton du bas "Sauver la configuration" et choisissez un nom de fichier.

Note: Si vous utilisez l'assistant h2Pas pour la première fois, vous aurez besoin de passer par l'onglet "Settings" pour dire à l'assistant où trouver le programme de conversion h2pas.exe. Le convertisseur h2pas.exe réside dans le même répertoire que le compilateur FreePascal fpc.exe - si vous avez téléchargé FPC comme une partie de Lazarus, il sera dans ...\Lazarus\fpc\version\bin. Ensuite enregistrez la configuration ainsi vous n'aurez pas à la refaire.

Exemple: MPICH2

Cliquez sur "Configuration -> Nouveau/Effacer Configuration". Cliquez alors sur le bouton du bas "Sauver la configuration" et sauvez la en tant que h2p/mpi2.h2p.

Ajoutez les fichiers .h au projet h2pas

Dans la page "C header files" vous pouvez ajouter/supprimer les fichiers .h. Vous pouvez activer/désactiver les fichiers .h afin de convertir seulement certains de ces fichiers.

Exemple: MPICH2

Cliquez sur "C header files -> Add .h files ..." et selectionnez "mpi.h" et "mpio.h". Ils seront activés automatiquement. Sélectionnez le fichier mpi.h et cliquez sur "Merge all but this", comme ça l'assistant combine tous les fichiers d'entête en une unique unité (pléonasme !) mpi.pas.

Configurez les options de h2pas

Sous "Options de h2pas" vous pouvez configurer les paramètres du programme h2pas.

Exemple: MPICH2

  • Activez -e, -D, -p, -w et désactivez tous les autres.
  • Le chemin de bibliothèque de -l est "mpich".
  • L'extension de sortie est ".pas"
  • Le dossier de sortie est h2pas/, qui est par défaut, donc laissez le vide

Lancez l'assistant

Cliquez sur le bouton du bas "Lancer h2pas". Cela va copier le fichier <example>.h dans un dossier temporaire <example>.tmp.h et lancer les outils listés sous "Avant h2pas". Il lance alors h2pas pour convertir <example>.tmp.h en <example>.inc ou <example>.pas ou autre extension de sortie que vous avez configuré dans la page h2pas. Ensuite il lance les outils listés sous "Après h2pas" sur les fichiers de sortie.

Si h2pas trouve une erreur de syntaxe, l'IDE va ouvrir le fichier example.tmp.h et sauter à la ligne de l'erreur. h2pas rapporter souvent seulement des 'syntax error', qui son vraiment non spécifiques. Voir Common problems when converting C header files.

Exemple: MPICH2

L'assistant de h2pas contient déjà tous les outils pour convertir tout ce qui est spécial dans ce fichier header, donc h2pas se lance sans erreur. Mais l'unité crée n'est toujours pas prête. Lisez plus loin.

Ajoutez ceci à la propriétéUndefines: 

 MPI_INCLUDED
 MPIO_INCLUDE
 NEEDS_MPI_FINT
 MPI_BUILD_PROFILING
 MPICH_SUPPRESS_PROTOTYPES
 MPI_Wtime
 HAVE_MPICH2G2
 FOO
 HAVE_PRAGMA_HP_SEC_DEF


Et ceci à la propriété Defines: 

 MPICH2
 MPICH_NEW_MPIIO

Publiez votre bindings sur lazarus-ccr ou Free Pascal

ToDo

Ecrivez vos propres outils de conversion

Utilisez l'outil "Recherche et remplacement"

Bien des choses come le renommage d'une variable peuvent être effectuées par l'outil Rechercher et remplacer. Ajoutez l'outil via le bouton Ajouter un nouvel outil sur l'une des pages 'Avant h2pas' ou 'Après h2pas'. Configurez alors les propriétés SearchFor, ReplaceWith, Options et Caption.

Exemple: renommer un identifiant Tguint en guint

Property Value
Caption Rename Tguint to guint
SearchFor Tguint
ReplaceWith guint
Options [trtMatchCase,trtWholeWord]

Exemple: renommer plusieurs identifiants

Renommer Tguint en guint, Tgulong en gulong, Tgint en gint:

Property Value
Caption Rename Tguint to guint
SearchFor gint|gulong)
ReplaceWith $1
Options [trtMatchCase,trtWholeWord,trtRegExpr]

Améliorer un outils existant

Vous pouvez trouver un bug et vouloir le solutionner ou vouloir étendre un des outils ci-dessus. Super!

La plupart des outils ci-dessus sont définis dans l'unité h2pasconvert qui fait partie du package h2paswizard. Basiquement un outil nécessite une classname, une description et une méthode Execute. Pour tester/debugger un outil en dehors de l'IDE et sauver beaucoup de temps de compilation, regardez le projet components/simpleideintf/examples/testh2pastool.lpi. Compilez-le et lancez-le dans une console/terminal avec un nom de fichier .h comme premier paramètre. Par exemple: 

 ./testh2pastool files/h2pastest.pas


Ecrire un outil personnalisé

Vous pouvez écrire vos propres outils de conversion et les enregistrer facilement dans l'IDE. Démarrez un package et ajoutez une nouvelle unité (disons unit1) pour votre nouvelle classe. Regardes les outils existant comme exemple et lisez la section précédente. Lorsque vous avez écrit et testé votre nouvel outil avec le projet simpleideintf project, enregistrez-le dans l'IDE: Ajoutez une procedure register à votre unité (unit1), comme suivant (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;

Ne pas oublier d'activer la case a cocher register de l'unité dans l'éditeur de package, autrement la procédure Register procedure ne sera pas appellée par l'IDE. Installez alors votre package dans l'IDE.

travail futur / fonctions manquantes

  • Un outil pour réordonner une unité pour solutionner les définitions forward. Cela requiert un outil pour retirer les IFDEFs non nécessaires.
  • Un outil pour solutionner les fonctions sans noms de paramètres en cherchant les fichiers .c. Cela pourrait également ajouter en commentaire dans quel fichier C se trouve la fonction.
  • Trouver des identifiants manquants et laisser l'utilisateur checker lesquels commenter ou remplacer avec les types de base.
  • Créer une liste de fonctions macro qui ont été seulement à moitié traduites.
Retrieved from "http://wiki.freepascal.org/index.php?title=Creating_bindings_for_C_libraries/fr&oldid=151813"