Anatomie d'un fichier unité
Les fichiers de description d'unité (appelés ci-après fichiers PPU en abrégé) sont utilisés pour déterminer si le code de l'unité doit être recompilé ou non. En d'autres termes, les fichiers PPU agissent comme des mini-makefiles, utilisés pour vérifier les dépendances des différents modules de code, ainsi que pour vérifier si les modules sont à jour ou non. De plus, il contient tous les symboles publics définis pour un module.
Pour lire ou écrire le ppufile, l'unité ppu, nommé ppu.pas, peut être utilisée, possédant un objet appelé tppufile contenant toutes les routines traitant de la gestion du ppufile. Tout en décrivant la disposition d'un ppufile, les méthodes pouvant être utilisées pour celui-ci sont également présentées.
Un fichier unitaire se compose essentiellement de cinq ou six parties :
- Un entête d'unité.
- Une partie d'informations générales (section interface mal nommée dans le code).
- Une partie définition. Contient toutes les définitions de types et de procédures.
- Une partie symbole. Contient tous les noms de symboles et les références à leurs définitions.
- Une partie navigateur. Contient toutes les références de cette unité aux autres unités et à l'intérieur de cette unité. Disponible uniquement lorsque le drapeau uf_has_browser est défini dans les drapeaux d'unité.
- Une partie d'implémentation du fichier (actuellement inutilisée).
Lecture de fichiers PPU
Nous allons d'abord créer un objet ppufile étant utilisé ci-dessous. Nous ouvrons unit test.ppu à titre d'exemple.
- Uses PPU;
-
- {$mode objfpc}
-
- Var
- PPUFile:TPPUFile;
-
- BEGIN
- { Initialiser l'objet }
- PPUFile:=TPPUFile.Create('test.ppu');
- { Ouvrez l'unité et lisez l'entête, renvoie false en cas d'échec }
- If Not PPUFile.OpenFile Then Writeln('Erreur lors de l''ouverture de l''unité test.ppu');
- { Ici on peut lire l'unité }
- { Fermer l'unité }
- PPUFile.CloseFile;
- { Libérer un objet }
- PPUFile.Free;
- END.
Remarque : Lorsqu'une fonction échoue (par exemple, il ne reste pas assez d'octets dans une entrée), elle définit la variable ppufile.error.
L'entête
L'entête est constitué d'un enregistrement (tppuheader) contenant plusieurs informations à recompiler. Ceci est indiqué dans le tableau suivant (l'entête est toujours entreposé au format petit-boutiste) :
| Déplacement | Taille (octets) | Description |
|---|---|---|
| 00h | 3 | Signature : 'PPU' en ASCII |
| 03h | 3 | Version du format de fichier PPU (exemple : '021' en ASCII) |
| 06h | 2 | Version du compilateur utilisée pour compiler ce module (majeure, mineure) |
| 08h | 2 | Processeur cible du code de microprocesseur |
| 0Ah | 2 | Système d'exploitation cible du module de code |
| 0Ch | 4 | Drapeaux pour le fichier PPU |
| 10h | 4 | Taille du fichier PPU (sans entête) |
| 14h | 4 | CRC-32 de l'intégralité du fichier PPU |
| 18h | 4 | CRC-32 de données partielles du fichier PPU (données publiques principalement) |
| 1Ch | 8 | Réservé |
L'entête est déjà lu par la commande du fichier profile.open. Vous pouvez accéder à tous les champs en utilisant profile.header contenant l'enregistrement d'entête actuel. Valeurs des champs de code du microprocesseur PPU :
| Valeur | Description |
|---|---|
| 0 | Inconnu |
| 1 | Intel 80x86 ou compatible |
| 2 | Motorola 680x0 ou compatible |
| 3 | Alpha AXP ou compatible |
| 4 | PowerPC ou compatible |
Certains des drapeaux possibles dans l'entête sont décrits dans le tableau suivant. Tous les drapeaux ne sont pas décrits, pour plus d'informations, lisez le code source de ppu.pas. Valeurs des drapeaux de l'entête PPU :
| Nom des drapeaux de bit symbolique | Description |
|---|---|
| uf_init | Le module a une section d'initialisation (style Delphi ou TP). |
| uf_finalize | Le module comporte une section de finalisation. |
| uf_big_endian | Toutes les données entreposées dans les morceaux sont au format big-endian. |
| uf_has_browser | L'unité contient des informations sur le navigateur de symboles. |
| uf_smart_linked | Le module de code a été connecté de manière intelligente. |
| uf_static_linked | Le code est lié statiquement. |
| uf_has_resources | L'unité a une section de ressources. |
Les sections
Hormis la section d'entête, toutes les données du fichier PPU sont séparées en blocs de données, ce qui permet d'ajouter facilement des blocs de données supplémentaires, sans compromettre la compatibilité ascendante. Ceci est similaire au format de bloc IFF d'Electronic Arts et au format de bloc RIFF de Microsoft.
Chaque «morceau» (tppuentry) a le format suivant et peut être imbriqué :
| Déplacement | Taille (octets) | Description |
|---|---|---|
| 00h | 1 | Type de bloc (imbriqué (2) ou principal (1)) |
| 01h | 1 | Identifiant du bloc |
| 02h | 4 | Taille de ce bloc de données |
| 06h+ | variable | Données pour ce bloc |
Chaque morceau de section principale doit se terminer par un morceau de fin. Les morceaux imbriqués sont utilisés pour les champs d'enregistrement, de classe ou d'objet.
Pour lire une entrée, vous pouvez simplement appeler ppufile.readentry:byte, il renvoie le champ tppuentry.nr, contenant le type de l'entrée. Cela fonctionne couramment (par exemple pour les symboles) :
Les types d'entrée possibles se trouvent dans PPU.PAS, mais une brève description des plus courants est présentée dans le tableau :
| Nom symbolique | Emplacement | Description |
|---|---|---|
| ibmodulename | Général | Nom de cette unité. |
| ibsourcefiles | Général | Nom des fichiers sources. |
| ibusedmacros | General | Nom et état des macros utilisées. |
| ibloadunit | Général | Modules utilisés par ces unités. |
| inlinkunitofiles | Général | Fichiers objets associés à cette unité. |
| iblinkunitstaticlibs | Général | Bibliothèques statiques associées à cette unité. |
| iblinkunitsharedlibs | Général | Bibliothèques partagées associées à cette unité. |
| ibendinterface | Général | Fin de la section Informations générales. |
| ibstartdefs | Interface | Début des définitions. |
| ibenddefs | Interface | Fin des définitions. |
| ibstartsyms | Interface | Début des données de symbole. |
| ibendsyms | Interface | Fin des données du symbole. |
| ibendimplementation | Mise en oeuvre | Données de fin de mise en oeuvre. |
| ibendbrowser | Navigateur | Fin de la section du navigateur. |
| ibend | Général | Fin du fichier unité. |
Ensuite, vous pouvez analyser vous-même chaque type d'entrée. ppufile.readentry se chargera de sauter les octets non lus dans l'entrée et lira correctement l'entrée suivante ! Une fonction spéciale est skipuntilentry(untilb:byte):boolean lisant le ppufile jusqu'à ce qu'il trouve l'entrée jusqu'à b dans les entrées principales.
L'analyse d'une entrée peut être effectuée avec les fonctions ppufile.getxxx. Les fonctions disponibles sont :
Pour vérifier si vous êtes à la fin d'une entrée vous pouvez utiliser la fonction suivante :
Remarques
- PPUReal est le meilleur réel existant pour le processeur pour lequel l'unité est créée. Actuellement, il est étendu pour i386 et unique pour m68k.
- ibobjectdef et ibrecorddef ont entreposé une section de définition et de symboles pour eux-mêmes. Vous aurez donc besoin d'un appel récursif. Voir ppudump.pp pour une implémentation correcte.
Une liste complète des entrées et de ce que contiennent leurs champs peut être trouvée dans ppudump.pp.
Création de fichiers PPU
Créer un nouveau fichier PPUFile fonctionne presque de la même manière que en lire un. Vous devez d'abord initialiser l'objet et appeler create :
- PPUFile:=New(PPPUFile,init('output.ppu'));
- PPUFile.CreateFile;
Après cela, vous pouvez simplement écrire toutes les entrées nécessaires. Vous devrez veiller à rédiger au moins les entrées de base pour les sections :
- ibendinterface
- ibenddefs
- ibendsyms
- ibendbrowser (seulement lorsque vous avez défini uf_has_browser !)
- ibendimplementation
- ibend
Écrire une entrée est un peu différent de la lire. Vous devez d'abord tout mettre dans l'entrée avec ppufile.putxxx :
Après avoir mis tous les éléments dans l'entrée, vous devez appeler ppufile.writeentry(ibnr:byte) où ibnr est le numéro d'entrée que vous écrivez.
À la fin du fichier, vous devez appeler ppufile.writeheader pour écrire le nouvel en-tête dans le fichier. Cela prend automatiquement en compte la nouvelle taille du fichier ppufile. Lorsque cela est également fait, vous pouvez appeler ppufile.closefile et supprimer l'objet.
Les fonctions/variables supplémentaires disponibles pour l'écriture sont :
- PPUFile.NewHeader;
- PPUFile.NewEntry;
Cela vous donnera un entête ou une entrée propre. Normalement, cela est appelé automatiquement dans PPUFile.WriteEntry, il ne devrait donc pas être nécessaire d'appeler ces méthodes. Tu peux appeler :
- PPUFile.Flush;
pour vider les tampons actuels sur le disque, et vous pouvez définir :
- PPUFile.do_crc:Boolean;
sur False si vous ne souhaitez pas que le CRC soit mis à jour lors de l'écriture sur le disque. Cela est nécessaire si vous écrivez par exemple les données du navigateur.
Code source
Voici des exemples de code source d'utilitaires pour manipuler les PPU de Free Pascal :
| Lien | Langage de programmation | Description | Projet |
|---|---|---|---|
| PPUINFO.PAS | Free Pascal, Turbo Pascal | Cette commande permet de retourner les informations de version d'une unité Free Pascal. | DEV-COOLS |