pkgMkIndex

Pkg_mkIndex — это утилита, которая входит в стандартную библиотеку Tcl. Она используется для создания файлов индекса, которые позволяют пакетам загружаться автоматически при выполнении команд package require. Для использования pkg_mkIndex следуйте этим шагам:

Создайте пакет(ы). Каждый пакет может состоять из одного или нескольких файлов скриптов Tcl или бинарных файлов. Бинарные файлы должны быть пригодны для загрузки с помощью команды load с одним аргументом; например, если файл — test.so, то его необходимо загружать командой load test.so. Каждый файл скрипта должен содержать команду package provide для объявления пакета и номера версии, а каждый бинарный файл — вызов Tcl_PkgProvide.
Создайте индекс, вызвав pkg_mkIndex. Аргумент dir указывает имя каталога, а каждый аргумент pattern — шаблон в стиле glob, который выбирает файлы скриптов или бинарные файлы в dir. По умолчанию шаблонами являются *.tcl и *.[info sharedlibextension].
Pkg_mkIndex создаст файл pkgIndex.tcl в dir с информацией о пакетах обо всех файлах, заданных аргументами pattern. Для этого он загружает каждый файл в интерпретатор-дочерний процесс и определяет, какие пакеты и новые команды появятся (поэтому крайне важно, чтобы в файлах присутствовали команды package provide или вызовы Tcl_PkgProvide, как описано выше). Если у вас есть пакет, разделенный на скрипты и бинарные файлы, или у вас есть зависимости между файлами, вам может потребоваться использовать параметр -load или изменить порядок обработки файлов pkg_mkIndex. См. раздел СЛОЖНЫЕ СЛУЧАИ ниже.
Установите пакет в качестве подкаталога одного из каталогов, указанных в переменной tcl_pkgPath. Если $tcl_pkgPath содержит более одного каталога, пакеты, зависящие от машины (например, те, которые содержат бинарные общие библиотеки), как правило, следует устанавливать в первый каталог, а пакеты, не зависящие от машины (например, те, которые содержат только скрипты Tcl), — во второй. Подкаталог должен включать файлы скриптов и/или бинарные файлы пакета, а также файл pkgIndex.tcl. Пока пакет установлен в качестве подкаталога каталога в $tcl_pkgPath, он будет автоматически находиться при выполнении команд package require.
Если вы устанавливаете пакет в другое место, вам необходимо убедиться, что каталог, содержащий пакет, находится в глобальной переменной auto_path или в непосредственном подкаталоге одного из каталогов в auto_path. Auto_path содержит список каталогов, которые просматриваются как автозагрузчиком, так и загрузчиком пакета; по умолчанию он включает $tcl_pkgPath. Загрузчик пакета также проверяет все подкаталоги каталогов в auto_path. Вы можете добавить каталог в auto_path явно в своем приложении или добавить каталог в переменную среды TCLLIBPATH: если эта переменная среды присутствует, Tcl инициализирует auto_path из неё во время запуска приложения.
После выполнения вышеперечисленных шагов, чтобы использовать пакет, вам необходимо вызвать package require. Например, если версии 2.1, 2.3 и 3.1 пакета Test были проиндексированы с помощью pkg_mkIndex, команда package require Test сделает доступной версию 3.1, а команда package require -exact Test 2.1 сделает доступной версию 2.1. Может быть много версий пакета в различных файлах индекса в auto_path, но только одна будет фактически загружена в данный интерпретатор на основе первого вызова команды package require. В разных интерпретаторах могут быть загружены разные версии одного пакета.

Параметры

Дополнительные переключатели:

-direct: Сгенерированный индекс будет реализовывать прямую загрузку пакета при выполнении команды package require. Это значение по умолчанию.
-lazy: Сгенерированный индекс будет управлять отсрочкой загрузки пакета до использования одной из команд, предоставляемых пакетом, вместо немедленной загрузки при выполнении команды package require. Это несовместимо с использованием auto_reset, и поэтому его использование не рекомендуется.
-load pkgPat: Процесс индексирования предварительно загрузит в интерпретатор-дочерний процесс все пакеты, присутствующие в текущем интерпретаторе и соответствующие pkgPat. Сопоставление шаблонов использует правила совпадения строк, но без учёта регистра. См. раздел СЛОЖНЫЕ СЛУЧАИ ниже.
-verbose: Выводить данные во время процесса индексирования. Вывод осуществляется через процедуру tclLog, которая по умолчанию печатает в stderr.
--: Конец флагов, на случай, если dir начинается с дефиса.

Пакеты и автозагрузчик

Средства управления пакетами частично перекрываются с автозагрузчиком, так как оба обеспечивают загрузку файлов по требованию. Однако управление пакетами — это механизм более высокого уровня, который использует автозагрузчик для последнего шага процесса загрузки. Обычно лучше индексировать пакет с помощью pkg_mkIndex, чем с помощью auto_mkindex, потому что механизм пакета поддерживает управление версиями: несколько версий одного пакета могут быть доступны в файлах индекса, и различные приложения могут использовать разные версии на основе команд package require. В отличие от этого, auto_mkindex не понимает версий, поэтому может обрабатывать только одну версию каждого пакета. Вероятно, не стоит индексировать данный пакет как с pkg_mkIndex, так и с auto_mkindex. Если вы используете pkg_mkIndex для индексирования пакета, его команды нельзя вызвать до тех пор, пока не будет использована команда package require для выбора версии; в отличие от этого, пакеты, проиндексированные с помощью auto_mkindex, могут быть использованы немедленно, поскольку контроль версий отсутствует.

Как это работает

Pkg_mkIndex зависит от команд package unknown, package ifneeded и автозагрузчика. В первый раз при вызове команды package require вызывается скрипт package unknown. Этот скрипт в Tcl по умолчанию задан как скрипт, который оценивает все файлы pkgIndex.tcl в auto_path. Файлы pkgIndex.tcl содержат команды package ifneeded для каждой версии каждого доступного пакета; эти команды вызывают команды package provide для объявления доступности пакета и устанавливают информацию автозагрузчика для загрузки файлов пакета. Если при создании pkgIndex.tcl был предоставлен флаг -lazy, то данный файл данной версии данного пакета не загружается фактически до первого вызова одной из его команд. Таким образом, после вызова package require вы можете не увидеть команды пакета в интерпретаторе, но вы сможете вызвать эти команды, и они будут загружены автоматически.

Непосредственная загрузка

Некоторые пакеты, например, пакеты, использующие пространства имен и экспортирующие команды или те, которые требуют специальной инициализации, могут выбрать, чтобы их файлы пакета загружались немедленно при выполнении package require вместо отсрочки фактической загрузки до первого использования одной из команд пакета. Это режим по умолчанию при создании индекса пакета. Его можно переопределить, указав аргумент -lazy.

Сложные случаи

Большинство сложных случаев зависимостей между скриптами и бинарными файлами, и пакетов, разделяемых между скриптами и бинарными файлами, обрабатываются нормально. Однако вам может потребоваться изменить порядок обработки файлов pkg_mkIndex. Эти проблемы подробно описаны ниже.

Если каждый скрипт или файл содержит один пакет, и пакеты содержатся только в одном файле, то всё просто. Вы просто указываете все файлы для индексирования в любом порядке с помощью некоторых шаблонов glob.

В целом, скрипты могут зависеть от других пакетов. Если скрипты содержат команды package require, эти команды заглушаются в интерпретаторе, используемом для обработки скриптов, поэтому это не вызывает проблем. Если скрипты вызывают другие пакеты в глобальном коде, эти вызовы обрабатываются заглушенной командой unknown. Однако если скрипты ссылаются на переменные других пакетов в глобальном коде, это вызовет ошибки. Это также плохой стиль кодирования.

Если двоичные файлы зависят от других пакетов, ситуация может осложниться, так как невозможно имитировать (stub out) API C-уровня, такие как Tcl_PkgRequire, при загрузке двоичного файла. Например, предположим, что пакет BLT зависит от пакета Tk и выражает это вызовом Tcl_PkgRequire в своей процедуре Blt_Init. Для поддержки этого нужно выполнить команду pkg_mkIndex в интерпретаторе, в котором загружен Tk. Это можно сделать с помощью опции -load pkgPat. Если вы укажете эту опцию, pkg_mkIndex загрузит в используемый интерпретатор все пакеты, перечисленные командой info loaded и соответствующие pkgPat. В большинстве случаев этого будет достаточно для обработки вызовов Tcl_PkgRequire, сделанных двоичными файлами.

Если вы индексируете два двоичных файла, и один из них зависит от другого, следует указать файл с зависимостями последним. Таким образом, файл без зависимостей будет загружен и проиндексирован, а затем пакет, предоставляемый им, станет доступным при обработке второго файла. Возможно, вам также потребуется загрузить первый пакет в временный интерпретатор, используемый для создания индекса, используя флаг -load; не повредит указать шаблоны пакетов, которые ещё не загружены.

Если у вас есть пакет, который разделен между скриптами и двоичным файлом, следует избегать использования флага -load. Проблема в том, что если вы загрузите пакет до вычисления индекса, это может скрыть любые другие файлы, предоставляющие часть того же пакета. Если вы всё же должны использовать -load, то сначала нужно указать скрипты; в противном случае пакет, загруженный из двоичного файла, может скрыть пакет, определённый скриптами.

См. также

package

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/pkgMkIndex.htm