pkg_mkIndex Commandes Internes Tcl

pkg_mkIndex - Construit un index pour le chargement automatique des packages

pkg_mkIndex ?-lazy? ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?

Pkg_mkIndex est une fonction utilitaire qui fait partie de la bibliothèque standard Tcl. Elle est utilisée pour créer des fichiers index qui permettent aux packages à être chargés automatiquement quand des commandes package require sont exécutées. Pour utiliser pkg_mkIndex, suivre ces étapes:

[1]: Créer le(s) package(s). Chaque package peut consister en un ou plusieurs fichiers script Tcl ou fichiers binaires. Les fichiers binaires doivent être compatibles pour le chargement avec la commande load avec un seul argument; par exemple, si le fichier est test.so il doit être possible de charger ce fichier avec la commande load test.so. Chaque fichier script doit contenir une commande package provide pour déclarer le package et son numéro de version, et chaque fichier binaire doit contenir un appel à Tcl_PkgProvide.
[2]: Créer l'index en appelant pkg_mkIndex. L'argument dir donne le nom d'un répertoire et chaque argument pattern est un modèle glob-style qui choisit les scripts ou fichiers binaires dans dir. Le modèle par défaut est *.tcl et *.[info sharedlibextension].
Pkg_mkIndex créera un fichier pkgIndex.tcl dans dir avec l'information de package au sujet de tous les fichiers donnés par les arguments pattern. Ceci est fait par chargement de chaque fichier dans un interpréteur esclave et constatation de quels packages et nouvelles commandes apparaissent (c'est pourquoi il est essentiel d'avoir des commandes package provide ou un appel à Tcl_PkgProvide dans le fichier, comme décrit plus haut). Si vous avez un package divisé en scripts et fichiers binaires, ou si vous avez des dépendances entre les fichiers, vous pouvez utiliser l'option -load ou ajuster l'ordre dans lequel pkg_mkIndex traite les fichiers. Voir CAS COMPLEXES ci-dessous.
[3]: Installer le package dans un sous répertoire d'un des répertoires donnés par la variable tcl_pkgPath. Si $tcl_pkgPath contient plus d'un répertoire, les packages dépendants de la machine (ex., ceux qui contient libraries partagées binaires) doivent normalement être installés sous le premier répertoire et les packages indépendants de la machine (ex., ceux qui contiennent seulement des scripts Tcl) seront installés sous le second répertoire. Le sous répertoire doit inclure le script du package et/ou les fichiers binaires aussi bien que le fichier pkgIndex.tcl. Tant que le package est installé dans un sous répertoire d'un répertoire de $tcl_pkgPath il sera automatiquement trouvé pendant les commandes package require.
Si vous installez le package nulle part ailleurs, alors vous devez vous assurer que le répertoire contenant le package est dans la variable globale auto_path ou un sous répertoire immédiat d'un des répertoires de auto_path. Auto_path contient une liste de répertoires qui sont recherché par le auto-loader et le package loader; qui par défaut inclut $tcl_pkgPath. Le package loader vérifie aussi tous les sous répertoire des répertoires dans auto_path. Vous pouvez ajouter un répertoire à auto_path explicitement dans votre application, ou vous pouvez ajouter le répertoire à votre variable d'environnement TCLLIBPATH: si cette variable d'environnement est présente, Tcl initialise auto_path avec pendant le démarrage de l'application.
[4]: Une fois les étapes précedentes accomplies, tout ce que vous avez besoin de faire pour utiliser le package est d'appeler package require. Par exemple, si les versions 2.1, 2.3, et 3.1 du package Test ont été indexées par pkg_mkIndex, la commande package require Test rendra la version 3.1 disponible et la commande package require-exact Test 2.1 rendra la version 2.1 disponible. Il peut y avoir de nombreuses versions d'un package dans les fichiers d'index de auto_path, mais seulement un sera actuellement chargé dans un interpréteur donné, en se basant sur le premier appel de package require. Différentes versions d'un package peuvent être chargées dans différents interpréteurs.

Les commutateurs optionnels sont:

-lazy: L'index généré retardera le chargement du package jusqu'à l'utilisation d'une des commandes fourni par le package, au lieu de le charger immédiatement avec package require.
-load pkgPat: Le processus d'index prechargera tous les packages existants dans l'interpréteur courant et correspondants à pkgPat dans l'interpréteur esclave utilisé pour générer l' index. La correspondance de modèle utilise les règles de chaîne de correspondance. Voir CAS COMPLEXES ci-dessous.
-verbose: Génère une sortie pendant le processus d'indexage. La sortie se fait via la fonction tclLog, qui par défaut affiche sur stderr.
--: Termine les flags, dans les cas ou dir commence avec un tiret.

PACKAGES ET AUTO-LOADER

Les utilités de gestion de package font double emploi avec l'auto-loader, dans le sens ou ils préparent tous les deux les fichiers à être chargés à la demande. Néanmoins, la gestion package est un mécanisme de plus haut niveau qui utilise l'auto-loader pour la dernière étape dans le processus de chargement. Il est généralement meilleur d'indexer un package avec pkg_mkIndex plutôt que auto_mkindex parce que le mécanisme de package fournit un contrôle de version: plusieurs versions d'un package peuvent être rendues disponibles dans les fichiers d'index, avec différentes applications utilisant différentes versions basées sur des commandes package require. Au contraire, auto_mkindex ne reconnaît pas les versions donc il peut seulement gérer une seule version de chaque package. Ce n'est probablement pas une bonne idée d'indexer un package donné avec pkg_mkIndex et auto_mkindex. Si vous utilisez pkg_mkIndex pour indexer un package, ses commandes ne peuvent pas appelées jusqu'a ce que package require ait été utilisé pour choisir une version; au contraire, les packages indexés avec auto_mkindex peuvent être utilisés immédiatement car il n'y a pas de contrôle de version.

COMMENT CA MARCHE ?

Pkg_mkIndex depend de la commande package unknown, de la commande package ifneeded, et de l'auto-loader. la première fois qu'une commande package require est appelée, le script package unknown est appelé. Ceci est fixé par l'initialisation Tcl dans un script qui évalue tous les fichiers pkgIndex.tcl dans le auto_path. Les fichiers pkgIndex.tcl contiennent des commandes package ifneeded pour chaque version de chaque package disponible; ces commandes appellent package provide pour annoncer la disponibilité du package, et elles écrivent l'information d'auto-loader pour charger les fichiers du package. Si le flag -lazy a été fourni quand pkgIndex.tcl a été généré, un fichier donné d'une version donnés d'un package donné n'est pas chargé jusqu'au premier appel d'une de ses commandes dans l'interpréteur, mais vous pourrez appeler les commandes et elles seront auto-chargées.

CHARGEMENT DIRECT

Certains packages, par exemple packages qui utilisent les namespaces et exportent descommandes ou ceux qui exigent une initialisation spéciale, peuvent choisir que leurs fichiers package seront chargés immédiatement à package require au lieu de retarder le chargement à la première utilisation d'une commande du package. C'est le mode par défaut pendant la génération de l'index de package. Ceci peut être surchargé en specifiant l'argument -lazy.

La plupart des cas complexes de dépendances entre scripts et fichiers binaires, et packages divisés entre scripts et fichiers binaires sont gérées correctement. Néanmoins, vous pouvez avoir à ajuster l'ordre dans lequel les fichiers sont traités par pkg_mkIndex. Ce problème est décrit en détail ci-dessous.

Si chaque script ou fichier contient un package, et que les packages sont contenus dans un seul fichier, alors les choses sont faciles. Vous spécifiez simplement tous les fichiers à indexer dans n'importe quel ordre avec quelques modèles glob.

En general, il est OK pour les scripts d'avoir des dépendances avec d'autres packages. Si les scripts contiennent des commandes package require, elles sont extraites dans l'interpréteur utilisé pour traiter les scripts, donc elles ne causent pas de problèmes. Si les scripts appellent d'autre packages dans le code global, ces appels sont gérés par une commande unknown. Néanmoins, si les scripts font référence à des variables d'un autre package dans le code global, cela causera des erreurs. C'est aussi un mauvais style de codage.

Si les fichiers binaires ont des dépendances avec d'autres packages, les choses peuvent devenir compliquées parcequ'il n'est pas possible d'extraire des API niveau C telle que Tcl_PkgRequire en chargeant un fichier binaire. Par exemple, supposez que le package BLT exige Tk, et exprime ceci avec un appel de Tcl_PkgRequire dans sa routine Blt_Init. Pour supporter ceci, vous devez exécuter pkg_mkIndex dans un interpréteur qui aura chargé Tk . Vous pouvez accomplir ceci avec l'option -loadpkgPat. Si vous spécifiez cette option, pkg_mkIndex chargera tous les packages listés par info loaded et qui correspondent à pkgPat dans l'interpréteur utilisé pour traiter les fichiers. Dans la plupart des cas ceci satisfera l'appel à Tcl_PkgRequire fait par les fichiers binaires.

Si vous indexez deux fichiers binaires et qu'un dépend de l'autre, vous devez spécifier celui qui a les dépendances en dernier. De cette façon, celui sans dépendances sera chargé et indexé, et alors le package qu'il fournit sera disponible quand le second fichier sera traité. Vous pouvez aussi avoir besoin de charger le premier package dans un interpréteur temporaire utilisé pour créer l'index en utilisant le flag -load; vous pourrez spécifier des modèles package qui ne sont pas encore chargés.

Si vous avez un package qui est divisé en scripts et fichiers binaires, alors vous devez éviter le flag -load. Le problème est que si vous chargez un package avant de calculer l'index, il masque tout autre fichier qui fait partie du même package. Si vous devez utiliser -load, alors vous devez spécifier les scripts en premier; autrement le package chargé du fichier binaire peut masquer le package défini par les scripts.

Dernière révision: 8.3