Creating bindings for C libraries/fr

From Lazarus wiki
Jump to navigationJump to search

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 fichier .h. Vous pouvez activer/désactiverles 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.