Fichiers de définition de module

Remonter à Détails techniques concernant ILINK32 et ILINK64

Utilisez les fichiers de définition de module avec ILINK32. Un fichier de définition de module est un fichier texte ASCII qui fournit des informations à ILINK32 sur le contenu et les exigences système d'une application Windows. Utilisez IMPDEF pour créer un fichier de définition de module.

Le fichier de définition de module nomme les fichiers .EXE ou .DLL, identifie le type d'application, énumère les fonctions importées et exportées, décrit les attributs des segments de données et des sections de code, vous permet de spécifier les attributs des segments de données et des sections de code supplémentaires, spécifie la taille de la pile et permet l'inclusion d'un programme stub.

Instruction CODE

Définit les attributs par défaut des sections de code. Les sections de code peuvent prendre n'importe quel nom, mais doivent appartenir à des classes de sections dont le nom se termine par CODE (par exemple CODE ou MYCODE).

CODE [PRELOAD | LOADONCALL]
      [EXECUTEONLY | EXECUTEREAD]

• PRELOAD signifie que le code est chargé lors du chargement du programme appelant.
• LOADONCALL (valeur par défaut) signifie que le code est chargé quand il est appelé par le programme.
• EXECUTEONLY signifie qu'une section de code peut uniquement être exécutée.
• EXECUTEREAD (valeur par défaut) signifie que la section de code peut être lue et exécutée.
• FIXED (valeur par défaut) signifie que la section reste toujours au même emplacement mémoire.
• MOVEABLE signifie que la section peut être déplacée.
• DISCARDABLE signifie que la section peut être supprimée si elle n'est plus utile (implique qu'elle soit MOVEABLE).
• NONDISCARDABLE (valeur par défaut) signifie que la section ne peut pas être supprimée.

Instruction DATA

Définit les attributs des segments de données :

DATA [NONE | SINGLE | MULTIPLE]
     [READONLY | READWRITE]
     [PRELOAD | LOADONCALL]
     [SHARED | NONSHARED]

• NONE signifie qu'aucune section de données n'a été créée. Cette option n'est disponible que pour les bibliothèques.
• SINGLE (valeur par défaut pour les .DLL) signifie qu'une seule section de données est créée et partagée par tous les processus.
• MULTIPLE (valeur par défaut pour les .EXE) signifie qu'une section de données est créée pour chaque processus.
• READONLY signifie que la section de données peut être uniquement lue.
• READWRITE (valeur par défaut) signifie que la section de données est accessible en lecture et en écriture.
• PRELOAD signifie que la section de données est chargée lors du premier chargement d'un module utilisant cette section.
• LOADONCALL (valeur par défaut) signifie que la section de données est chargée quand on y accède pour la première fois. LOADONCALL est ignoré pour les applications 32 bits.
• SHARED signifie qu'un exemplaire de la section de données est partagé par tous les processus.
• NONSHARED (valeur par défaut pour les programmes et DLL) signifie qu'un exemplaire de la section de données est chargé pour chaque processus qui a besoin d'utiliser la section.

Instruction DESCRIPTION (facultative)

Insère du texte dans le module d'application ; cette instruction est en principe utilisée pour inclure le nom de l'auteur, la date ou des informations de copyright :

DESCRIPTION 'Text'

Texte est une chaîne ASCII délimitée par des guillemets.

Instruction EXETYPE

Définit le type d'en-tête par défaut du fichier exécutable (.EXE) pour les applications. Vous pouvez laisser cette section pour les applications 32 bits, pour des raisons de compatibilité descendante, mais si vous devez modifier EXETYPE, reportez-vous à l'instruction NAME.

EXETYPE  [WINDOWAPI] | [WINDOWCOMPAT]

• WINDOWAPI est un exécutable Windows ; équivaut à l'option -aa de ILINK32.
• WINDOWCOMPAT est un exécutable en mode caractère compatible Windows ; équivaut à l'option -ap de ILINK32.

Instruction EXPORTS

Définit le nom et les attributs des fonctions à exporter. Le mot réservé EXPORTS indique le début des définitions. Il peut être suivi d'un nombre quelconque de définitions d'exportation, chacune sur une ligne distincte.

EXPORTS
   <ExportName> [<Ordinal>]
   [RESIDENTNAME] [<Parameter>]

• <NomExport> désigne une chaîne ASCII définissant le symbole à exporter comme suit :

<NomEntrée> [=<NomInterne>]

<NomEntrée> est le nom qui figure dans la table des entrées du fichier exécutable, visible de l'extérieur.

<NomInterne> est le nom utilisé à l'intérieur de l'application pour faire référence à cette entrée.

• <Ordinal> définit la valeur ordinale de la fonction, comme suit :

@<ordinal>

où <ordinal> est un nombre entier désignant la valeur ordinale de la fonction. Quand un module d'application ou de DLL appelle une fonction exportée d'une DLL, le module appelant peut désigner la fonction par son nom ou par sa valeur ordinale. Il est plus rapide d'appeler la fonction par sa valeur ordinale car cela évite les comparaisons de chaînes pour localiser la fonction. Pour économiser la mémoire, exportez une fonction par sa valeur ordinale (du point de vue de la DLL de la fonction) et importez/appelez une fonction par sa valeur ordinale (du point de vue du module appelant).

Quand une fonction est exportée par sa valeur ordinale, son nom se trouve dans la table des noms non résidents. Quand elle est exportée par son nom, le nom se trouve dans la table des noms résidents. La table des noms résidents d'un module donné est en mémoire chaque fois que ce module est chargé ; la table des noms non résidents ne l'est pas.

• RESIDENTNAME indique que le nom de la fonction doit être en permanence résident. Cela n'est utile que pour les exportations par valeur ordinale (où le nom n'est pas forcément résident par défaut).
• <Paramètre> est un entier facultatif qui spécifie le nombre de mots que la fonction veut transmettre comme paramètres.

Instruction HEAPSIZE

Définit le nombre d'octets requis par l'application pour son tas local. Une application utilise le tas local quand elle alloue de la mémoire locale.

HEAPSIZE <Reserve>[, <Commit>]

• <Réserve> peut être une valeur décimale ou hexadécimale, et la valeur par défaut est 1 Mo. Pour vous aider à assurer la compatibilité avec les applications 16 bits et les ports 32 bits, le lieur utilise la valeur par défaut de 1 Mo si vous spécifiez une valeur inférieure à 64 Ko dans le fichier .DEF.
• <Commit> peut être une valeur décimale ou hexadécimale. Cette valeur, facultative, est par défaut de 4 Ko. La valeur minimale de commit est 0. En outre, la valeur de commit, spécifiée ou par défaut, doit toujours être inférieure ou égale à la taille de réserve.

La mémoire réservée est la quantité maximale de mémoire pouvant être allouée soit en mémoire physique, soit dans le fichier de pagination. En d'autres termes, la mémoire réservée indique la taille maximale du tas. Le système d'exploitation garantit que cette quantité de mémoire sera réservée et, si nécessaire, allouée.

La signification de la mémoire dédiée varie selon le système d'exploitation. Sous Windows NT, la mémoire dédiée est la quantité de mémoire physique allouée au tas au chargement ou à l'initialisation de l'application. La mémoire dédiée est allouée soit en mémoire physique, soit dans le fichier de pagination. Une valeur élevée permet de gagner du temps lorsque l'application nécessite un tas plus important, mais augmente les besoins en mémoire et parfois la durée du démarrage.

Vous pouvez outrepasser les tailles de réserve ou de commit du tas spécifiées dans le fichier .DEF, en utilisant les options -H ou -Hc sur la ligne de commande ILINK32. -H vous permet de spécifier une taille de réserve pour le tas inférieure au minimum de 64 Ko autorisé dans le fichier .DEF.

Instruction IMPORTS

Définit le nom et les attributs des fonctions à importer des DLL. Le mot réservé IMPORTS signale le début des définitions ; il est suivi d'un nombre quelconque de définitions d'importation, chacune sur une ligne distincte.

IMPORTS
[<InternalName>=]<ModuleName>.<Entry>

• <NomInterne> est une chaîne ASCII qui précise le nom unique utilisé par l'application pour appeler la fonction.
• <NomModule> indique un ou plusieurs caractères ASCII majuscules qui définissent le nom du module exécutable contenant la fonction. Ce nom doit être le même que celui du fichier exécutable. Par exemple, le fichier EXEMPLE.DLL a pour nom de module EXEMPLE.
• <Entrée> désigne la fonction à importer : il s'agit soit d'une chaîne ASCII désignant la fonction, soit d'un entier correspondant à la valeur ordinale de la fonction.

Au lieu d'énumérer dans l'instruction IMPORTS les fonctions DLL importées, vous pouvez spécifier une bibliothèque d'importation pour la DLL dans l'interface de ligne de commande ILINK32 ou inclure la bibliothèque d'importation pour la DLL dans le Gestionnaire de projets de RAD Studio.

Vous devez utiliser __declspec(dllimport) ou __import pour importer toute fonction, classe ou données. __declspec(dllimport) constitue la méthode préférée.

Le mot réservé IMPORTS peut également être appliqué aux variables (globales), comme suit :

[ in the dll source file (dll.cpp) ] int sample = 100;

[ dll.def ]     EXPORTS       _sample

[ in application source file (app.cpp) ]
int _declspec(dllimport) sample;

[ app.def ]
  IMPORTS
    dll._sample

Instruction LIBRARY

Définit le nom d'un module DLL. Un fichier de définition de module peut contenir soit une instruction LIBRARY pour désigner une .DLL, soit une instruction NAME pour désigner un .EXE. Tout nom de module de bibliothèque doit correspondre au nom du fichier exécutable. Par exemple, la bibliothèque MYLIB.DLL a pour nom de module MYLIB.

LIBRARY <LibrarName> [INITGLOBAL | INITINSTANCE]

• <NomBiblio> (facultatif) est une chaîne ASCII qui définit le nom du module de la bibliothèque. Si vous n'indiquez pas de NomBiblio, ILINK32 utilise le nom du fichier en supprimant l'extension. Si le fichier de définition de module ne comporte ni instruction NAME ni instruction LIBRARY, ILINK32 utilise par défaut une instruction NAME sans paramètre NomModule.
• INITGLOBAL signifie que la routine d'initialisation de la bibliothèque est appelée.
• INITINSTANCE signifie que la routine d'initialisation de la bibliothèque est appelée chaque fois qu'un nouveau processus utilise la bibliothèque.

Instruction NAME

Est le nom du module exécutable de l'application. Le nom du module identifie le module quand vous exportez des fonctions. NAME doit figurer avant EXETYPE. Si NAME et EXETYPE n'indiquent pas le même type de cible, le lieur utilise le type indiqué par NAME.

NAME <ModuleName> [WINDOWSAPI] | [WINDOWCOMPAT]

• <NomModule> ((facultatif) contient un ou plusieurs caractères ASCII majuscules désignant le nom du module exécutable. Ce nom doit être le même que celui du fichier exécutable. Par exemple, une application avec le fichier exécutable EXEMPLE.EXE aura pour nom de module EXEMPLE.

Si <NomModule> n'est pas indiqué, ILINK32 considère que le nom du module correspond au nom du fichier exécutable. Par exemple, si vous n'indiquez pas de nom de module et si le fichier exécutable s'appelle MYAPP.EXE, ILINK32 considère que le nom du module est MYAPP. Si le fichier de définition de module ne comporte ni instruction NAME ni instruction LIBRARY, ILINK32 utilise par défaut une instruction NAME sans paramètre <NomModule>.

• WINDOWSAPI désigne un exécutable Windows ; équivaut à l'option -aa de ILINK32.
• WINDOWCOMPAT spécifie un exécutable en mode caractère compatible Windows ; équivaut à l'option -ap de ILINK32.

Instruction SECTIONS

Vous permet de définir les attributs d'une ou plusieurs sections du fichier image. Vous pouvez utiliser cette instruction pour outrepasser les valeurs par défaut des attributs de chaque type de section.

SECTIONS<section_name> [CLASS '<ClassName>'] <attributes>

• SECTIONS signale le début de la liste des définitions de sections.
• Après le mot réservé SECTIONS, chaque définition de section doit figurer sur une ligne différente. Le mot réservé SECTIONS peut être sur la même ligne que la première définition ou sur la ligne précédente. En outre, le fichier .DEF peut contenir une ou plusieurs instructions SECTIONS. Le mot réservé SEGMENTS est accepté comme synonyme de SECTIONS.
• <NomClasse> est sensible à la casse. Le mot réservé CLASS est accepté pour des raisons de compatibilité, mais il est ignoré.
• <Attributs> désigne un ou plusieurs des attributs suivants : EXECUTE, READ, SHARED et WRITE.

Instruction SEGMENTS

Définit les attributs des sections de code et de données supplémentaires. Le mot réservé SEGMENTS est accepté comme synonyme de SECTIONS. La syntaxe est :

SEGMENTS
   <SegmentName> [CLASS '<ClassName>']
        [<MinAlloc>]
        [SHARED | NONSHARED]
        [PRELOAD | LOADONCALL]

• <SegmentName> est une chaîne de caractères qui désigne le nouveau segment. Il peut s'agir d'un nom quelconque, y compris des noms de segments standard _TEXT et _DATA qui correspondent aux segments de code et de données standard.
• <ClassName> (facultatif) est le nom de classe du segment concerné. Si le nom de classe n'est pas indiqué, ILINK32 utilise le nom de classe CODE.
• <MinAlloc> (facultatif) est un entier désignant la taille d'allocation minimale pour le segment. ILINK32 ne tient pas compte de cette valeur.
• SHARED signifie qu'un exemplaire du segment est partagé par tous les processus.
• NONSHARED (valeur par défaut pour les .EXE et DLL) signifie qu'un exemplaire du segment est chargé pour chaque processus qui a besoin du segment de données.
• PRELOAD signifie que le segment est chargé immédiatement.
• LOADONCALL signifie que le segment est chargé quand on y accède ou quand il est appelé (ignoré par ILINK32). Le compilateur de ressources peut outrepasser l'option LOADONCALL et précharger les segments.

Instruction STACKSIZE

Définit le nombre d'octets requis par l'application pour sa pile locale. Une application utilise la pile locale chaque fois qu'elle appelle des fonctions.

STACKSIZE <Reserve>[, <Commit>]

• <Reserve> peut être une valeur décimale ou hexadécimale, et la valeur par défaut est 1 Mo. Pour vous aider à assurer la compatibilité avec les applications 16 bits, le lieur utilise la valeur par défaut 1 Mo si vous spécifiez une valeur de réserve inférieure à 64 Ko dans le fichier .DEF.
• <Commit> peut être une valeur décimale ou hexadécimale. Cette valeur, facultative, est par défaut de 8 Ko. La valeur minimale de commit est 4 Ko. En outre, la valeur de commit, spécifiée ou par défaut, doit toujours être inférieure ou égale à la taille de réserve.

La mémoire réservée est la quantité maximale de mémoire pouvant être allouée soit en mémoire physique, soit dans le fichier de pagination. En d'autres termes, la mémoire réservée indique la taille maximale de la pile.

Le système d'exploitation garantit que cette quantité de mémoire sera réservée et, si nécessaire, allouée.

The meaning of committed memory varies among operating systems. In Windows NT, committed memory refers to the amount of physical memory allocated for the stack at application load/initialization time. Committed memory causes space to be allocated either in physical memory or in the paging file. A higher commit value saves time when the application needs more stack space, but increases memory requirements and possible startup time.

Vous pouvez outrepasser les tailles de réserve ou de commit de la pile spécifiées dans le fichier .DEF, en utilisant les options -S ou -Sc sur la ligne de commande ILINK32. -S vous permet de spécifier une taille de réserve pour la pile, inférieure au minimum de 64 Ko autorisé dans le fichier .DEF.

Remarque : N'utilisez pas l'instruction STACKSIZE lorsque vous compilez des .DLL.

Instruction STUB

Ajoute un fichier DOS exécutable désigné par <FileName> au début du module. Le stub exécutable affiche un message d'avertissement et se termine si l'utilisateur essaie de l'exécuter dans le mauvais environnement (application Windows exécutée sous DOS, par exemple).

STUB '<FileName>'

• <FileName> est le nom du fichier DOS exécutable qui doit être ajouté au module. Ce nom doit respecter le format des noms de fichiers DOS. Si le fichier désigné par FileName n'est pas dans le répertoire en cours, ILINK32 le recherche dans les répertoires indiqués par la variable d'environnement PATH.

C++Builder C++Builder ajoute un stub prédéfini au début de toute application Windows, sauf si un autre stub a été indiqué avec l'instruction STUB. N'utilisez pas l'instruction STUB pour inclure WINSTUB.EXE, car le lieur le fait automatiquement.

Instruction SUBSYSTEM

Vous permet de spécifier le sous-système Windows et le numéro de version du sous-système pour l'application à lier.

SUBSYSTEM [<subsystem>,]<subsystemID>

• <Subsystem> (facultatif) peut prendre l'une des valeurs suivantes : WINDOWS, WINDOWAPI, WINDOWCOMPAT. Si vous ne spécifiez pas de <Subsystem>, le lieur utilisera par défaut un sous-système WINDOWS.
• <SubsystemID> doit utiliser le format d.d où d est un nombre décimal. Par exemple, si vous voulez spécifier Windows 4.0, utilisez l'une des instructions SUBSYSTEM suivantes :

SUBSYSTEM 4.0

SUBSYSTEM WINDOWS 4.0

Vous pouvez outrepasser toute instruction SUBSYSTEM d'un fichier .DEF en utilisant les options -a et-V sur la ligne de commande ILINK32.

Voir aussi

• ILINK32.EXE, le lieur incrémentiel 32 bits
• IMPDEF.EXE, le gestionnaire de définition de module