Внешние модули¶
Внешний модуль - это исполняемый файл, который tt запускает как команду:
tt <name> запускает модуль <name> со всеми аргументами, переданными после
имени. Так к tt добавляют новые команды или заменяют встроенные без
пересборки самого tt. О том, как встроить команды непосредственно в tt, см.
Написание модуля tt и
Сборка дистрибутива tt.
Написание модуля¶
Модуль представляет собой каталог, названный по имени добавляемой команды.
Внутри находится файл manifest.yaml:
version: 1.0.0
help: Upload tt backups to an S3 bucket
main: main
version - версия модуля, help - его краткое однострочное описание, а
main - имя исполняемого файла в каталоге; все три поля обязательны.
Манифест может называться и manifest.yml; если присутствуют оба файла, tt
не читает ни один из них, как если бы манифеста не было вовсе. Поля
tt-version, description и homepage_url tt также считывает, но
игнорирует.
Модуль без манифеста - это исполняемый файл с именем main, который при
вызове с флагами --description --version выводит те же version и help
в формате YAML. tt запускает его так при каждом старте, какую бы команду ни
вызвали, чтобы составить список модулей; манифест избавляет от этого запуска.
Поле help описывает модуль везде, где tt выводит его в списках: среди
команд в tt --help, в секции EXTERNAL COMMANDS, в автодополнении командной
строки и в выводе tt modules list. tt берёт только первую строку, поэтому
в таких списках каждый модуль занимает ровно одну строку. Более длинный
текст помещают в собственный --help модуля, который tt help <module> и
tt <module> --help выводят в stdout.
Подключение модуля к tt¶
tt ищет модули в каталогах, перечисленных в переменной
TT_CLI_MODULES_PATH через двоеточие:
export TT_CLI_MODULES_PATH=/path/to/modules:/path/to/other/modules
Относительные пути отсчитываются от текущего рабочего каталога, в котором запущен tt, поэтому лучше указывать абсолютные пути.
$ tt modules list
$ tt upload-backups --help
Каждый подкаталог в перечисленных путях, содержащий манифест или файл
main, считается модулем. Если в двух каталогах найдутся модули с
одинаковым именем, выбирается первый найденный по списку, а о втором tt
выводит предупреждение. Несуществующие пути из списка пропускаются; если же
указанный путь существует, но каталогом не является, либо каталог
недоступен для чтения, с ошибкой завершается любая команда tt. Модуль,
информацию о котором tt не может прочитать - манифест повреждён, не хватает
обязательного поля или исполняемый файл не отвечает на
--description --version, - пропускается с предупреждением.
Как tt запускает модуль¶
Команда tt [global flags] <name> [args] запускает исполняемый файл с
аргументами args, передавая каждый из них в неизменном виде, включая флаги;
tt не разбирает эти аргументы и потому не выполняет автодополнение флагов или
параметров модуля. Глобальные флаги перед именем команды, такие как -V и
--no-prompt, относятся к tt: модуль их не получает. tt ничего не добавляет
в переменные окружения модуля - тот наследует окружение tt - и запускает его
в рабочем каталоге tt. Модуль читает stdin tt и сам пишет в stdout и stderr tt.
tt завершает работу с кодом возврата модуля и ничего не выводит от себя, если код отличен от 0: модуль уже сообщил об ошибке сам. Если модуль завершён сигналом, tt также молча завершается с кодом 255. Сообщение об ошибке tt выводит только тогда, когда исполняемый файл не удалось запустить или его отклонила проверка целостности.
Проверка целостности¶
В дистрибутиве, собранном с integrity = "rsa", tt проверяет манифест
модуля и его исполняемый файл - перед каждым запуском и каждым вызовом
--help - через механизм проверки целостности. С флагом --integrity-check
файл отклоняется, если он не указан в подписанном файле контрольных сумм
проекта или окружений, запускаемых tt, поэтому модуль за пределами
подписанного дерева перестаёт работать: tt пропускает его с
предупреждением. Модуль, чей манифест попал в список, а исполняемый файл -
нет, отображается в списках tt, но при попытке запуска завершается с
ошибкой (см. Подпись пакетов). Без флага
--integrity-check проверка не выполняется.
Замена встроенных команд tt¶
Модуль, названный так же, как команда tt, заменяет её: если подключён
внешний модуль connect, tt connect запускает именно его, а флаг -V
сообщает в журнале о замене команды. Модуль с именем группы команд, например
cluster, переопределяет всю группу целиком; кроме того, модуль откликается
на псевдонимы заменяемой команды. Флаг --internal (-I) позволяет
запустить вместо модуля встроенную команду tt: tt -I connect.
Команды modules, help, completion и version заменить нельзя: модуль
с таким именем игнорируется с выводом предупреждения.
Дистрибутив tt может быть собран без поддержки внешних модулей (см. Дистрибутивы и модули).