Перейти к содержанию

Внешние модули

Внешний модуль - это исполняемый файл, который 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 может быть собран без поддержки внешних модулей (см. Дистрибутивы и модули).