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

Сборка дистрибутива tt

Модуль tt - это модуль Go, который компилируется внутрь tt, а не работает рядом с ним: его пакет экспортирует конструктор func New(sdk.Services) []sdk.Mount, возвращающий команды, которые он добавляет, или func New(sdk.Services) sdk.Module, возвращающий также его бэкенды сборки и проверки файлов пакета (см. Write a tt module и SDK). Дистрибутив tt - это ядро tt и набор таких модулей, собранных в один бинарный файл и описанных в tt.manifest.toml:

manifest_version = "0.1"
manifest_kind = "tt-distribution"

[package]
name = "tt"

[core]
tt = "v3.0.0-alpha.3"

[distribution]
title = "Tarantool CLI EE"
edition = "ee"
integrity = "rsa"

[dependencies]
migrations = "./plugins/migrations"
foo = "github.com/acme/tt-foo@v1.2.0"

Обязательны только manifest_version и manifest_kind; каждое поле описано в tt.manifest.toml. Без секции [core] дистрибутив собирается на ядре того tt, который выполняет сборку; tt принимает запрос версии Go для модуля ядра - версию, коммит или latest, а path - локальный чекаут ядра. Версию или коммит надёжнее зафиксировать: Go читает v3 как "самый новый релиз v3.x.y", а не как ветку v3, и пока у tt 3 есть только предварительные версии, под этот запрос ничего не подходит. Секция [distribution] задаёт то, как бинарный файл представляет себя (title, edition), провайдер контроля целостности (none или rsa), наличие стандартных модулей ядра (standard, см. Стандартные модули), собственных команд tt (builtin) и внешних модулей (external_modules), по умолчанию включённых, а также откуда tt binary install берёт предсобранные продукты (bundle_sources: по умолчанию customer-zone, личный кабинет tarantool.io, для Tarantool Enterprise, SDK, TCM и tt-ee, rws, RPM-пакеты rws.tarantool.org, для Tarantool Community и github, релизы tt на GitHub, для tt; [] - ни одного источника, и тогда Tarantool Community и tt собираются из исходного кода). Секция [build] задаёт реализацию TLS (ssl: default, openssl или openssl_static, переопределяется переменной TT_CLI_BUILD_SSL), сборку с cgo (по умолчанию только для вариантов с OpenSSL), дополнительные теги сборки tags и флаги линковщика ldflags.

Зависимость - это локальный каталог (./..., ../... или абсолютный путь), путь к модулю либо путь к модулю с версией после @; длинная форма - это таблица с полями module, version, path, package и symbol: конструктором считается функция New в корневом пакете модуля, если package и symbol не говорят об обратном. Модуль из репозитория ядра, такой как aeon, собирается на коммите ядра; любой другой модуль без версии - на самой свежей. Стандартным модулям запись здесь не нужна: дистрибутив выше содержит aeon, build, emmylua и wasm с двумя его собственными модулями.

tt binary build tt                  # собрать ./tt из ./tt.manifest.toml
tt binary build tt --update         # взять самые свежие версии ядра и модулей
tt binary build tt --locked -o tt   # собрать ровно то, что фиксирует локфайл

Тулчейн Go должен быть в PATH. Сборка генерирует модуль main, требующий ядро и модули, компилирует его с теми тегами сборки, с которыми собран сам tt, запускает tt version для результата - tt --help для варианта без builtin, в котором находится version, - и записывает tt.manifest.lock и tt.manifest.sum рядом с манифестом. Оба файла коммитим в репозиторий: пока манифест говорит то же самое, следующая сборка берёт версии из локфайла, а флаг --locked завершается с ошибкой, если локфайл или модули Go расходятся. Локфайл связывается с манифестом через хеш его таблиц, ключей и значений, как и локфайл пакета: комментарий или переформатирование манифеста оставляют его актуальным. Локфайл фиксирует то, из чего собирается бинарный файл, а не параметры компиляции: реализацию TLS, теги и тулчейн Go каждая сборка выбирает сама, поэтому один локфайл собирает любой из этих вариантов, а сборка, не фиксирующая ничего нового - например, выполненная другим tt, - оставляет оба файла без изменений.

У локального модуля, локального ядра или каталога из [replace] нет версии, которую можно зафиксировать, поэтому локфайл сохраняет content_hash - хеш его файлов по путям и содержимому, так же как Go вычисляет хеш модуля для go.sum. Это те файлы, которые бандл при --vendor копирует: каждый обычный файл его каталога, кроме находящихся в каталогах VCS и vendor, во вложенных модулях, go.work и go.work.sum, которые сборка не читает, и файлов, игнорируемых .gitignore. Файлы .gitignore учитываются как собственные для модуля, так и в вышестоящих каталогах вплоть до корня его git-репозитория - вне репозитория вплоть до каталога манифеста, если модуль находится в нём. Они читаются так, как их читает git, но без запуска git, поэтому архив чекаута хешируется так же, как и сам чекаут; файлы .git/info/exclude и core.excludesFile, различающиеся от машины к машине, не читаются, а отслеживаемый git'ом файл, который .gitignore игнорирует, не учитывается. Файлы, из которых Go может собрать модуль, учитываются даже тогда, когда они проигнорированы: исходные файлы Go и cgo, go.mod, go.sum и файлы, внедряемые через //go:embed. Сборка с --locked завершается с ошибкой, если файлы изменились; обычная сборка записывает их заново. Бинарный файл, собранный в чекауте ядра, например ./tt, изменением не считается: .gitignore самого tt его игнорирует.

Команда tt version для собранного файла показывает версию дистрибутива и ядра tt, на котором он собран; tt version --modules перечисляет его модули с версиями, зафиксированными Go для их модулей, или (devel) для локального:

$ ./tt version --modules
Tarantool CLI EE version 3.0.0, linux/amd64. commit: 1a2b3c4
Tarantool CLI core version 3.0.0. commit: 9031d7ad96d9 (v3.0.1-0.20261028190206-9031d7ad96d9)
  aeon        v0.0.0-20261028190206-9031d7ad96d9    github.com/tarantool/tt/modules/aeon
  build       v0.0.0-20261028190206-9031d7ad96d9    github.com/tarantool/tt/modules/build
  builtin     v3.0.1-0.20261028190206-9031d7ad96d9  github.com/tarantool/tt/v3
  emmylua     v0.0.0-20261028190206-9031d7ad96d9    github.com/tarantool/tt/modules/emmylua
  foo         v1.2.0                                github.com/acme/tt-foo
  migrations  (devel)                               example.com/tt-ee/plugins/migrations
  wasm        v0.0.0-20261028190206-9031d7ad96d9    github.com/tarantool/tt/modules/wasm

Стандартные модули

Стандартные модули - это модули из репозитория ядра, с которыми собирается официальный tt: сейчас это aeon, build, emmylua и wasm. Ядро перечисляет их в своём пакете standard, и дистрибутив по умолчанию берёт их все на коммите ядра, поэтому модули, добавленные более новым ядром, попадают в сборку без правки манифеста. build содержит бэкенды сборки tt, от make и shell до cargo и go: у самого ядра собственных бэкендов нет, и дистрибутив без build раскладывает код Lua в пакете, но не собирает ни один компонент с блоком сборки и не выполняет ни один хук. wasm содержит команду tt wasm и проверку файлов .wasm пакета; компоненты, добавляемые командой tt wasm new, собираются бэкендом shell модуля build. Секция [distribution].exclude исключает некоторые из них по имени:

manifest_version = "0.1"
manifest_kind = "tt-distribution"

[package]
name = "tt-lite"

[core]
path = "../tt"

[distribution]
exclude = ["emmylua", "wasm"]

При чекауте tt в ../tt сборка берёт aeon и build, но не emmylua и wasm:

$ tt binary build tt
   • Resolving the core github.com/tarantool/tt/v3
   •   core github.com/tarantool/tt/v3 (path ../tt)
   •   standard aeon, build (with the core)
   • Building tt-lite
   • Built /src/lite/tt-lite
/src/lite/tt-lite
$ ./tt-lite version --modules
Tarantool CLI version 3.0.0, linux/amd64. commit: 1a2b3c4
  aeon     (devel)  github.com/tarantool/tt/modules/aeon
  build    (devel)  github.com/tarantool/tt/modules/build
  builtin  (devel)  github.com/tarantool/tt/v3

Локфайл перечисляет вошедшие в бинарный файл стандартные модули в своей секции [core], а сборка с --locked завершается с ошибкой, если сборка взяла бы другие:

[core]
module = 'github.com/tarantool/tt/v3'
path = '../tt'
content_hash = 'sha256:4367f681...'
standard = ['aeon', 'build']

Сборка читает этот список из исходного кода пакета standard и импортирует каждый включённый стандартный модуль в сгенерированный файл main, как и модули из [dependencies], поэтому исключённый модуль не компилируется вовсе:

$ go version -m tt-lite | grep 'dep.*tt/modules'
    dep github.com/tarantool/tt/modules/aeon    v0.0.0-0
    dep github.com/tarantool/tt/modules/build   v0.0.0-0

builtin, собственные команды tt, здесь считается стандартным модулем: exclude = ["builtin"] означает builtin = false. Имя, которого нет в списке ядра, приводит к ошибке с перечислением допустимых имён:

$ tt binary build tt
   • Resolving the core github.com/tarantool/tt/v3
   •   core github.com/tarantool/tt/v3 (path ../tt)
   ⨯ distribution.exclude: "tcm" is not a standard module of the core ../tt: they are aeon, build, emmylua, wasm, builtin

Модуль из [dependencies] с именем стандартного модуля занимает его место - например, форк aeon или чекаут в ./aeon. Укажите его и в exclude, чтобы подтвердить это намерение явно; иначе сборка выдаст предупреждение, а манифест, в котором aeon указан напрямую из репозитория ядра, как делалось раньше, соберёт тот же самый бинарный файл, что и манифест без него:

$ tt binary build tt
   • Resolving the core github.com/tarantool/tt/v3
   •   core github.com/tarantool/tt/v3 (path ../tt)
   ⚠ dependencies.aeon takes the place of the standard module aeon of the core: add "aeon" to distribution.exclude to say so, or drop the dependency to take the core's
   •   standard build (with the core)
   •   aeon github.com/tarantool/tt/modules/aeon (with the core)
   • Building tt-lite

У ядер до v3.0.0-alpha.3 пакета standard нет. Сборка дистрибутива на таком ядре завершается с ошибкой, пока не задано standard = false и не перечислены нужные модули:

$ tt binary build tt
   • Resolving the core github.com/tarantool/tt/v3
   •   core github.com/tarantool/tt/v3@v3.0.0-alpha.2
   ⨯ distribution.standard: the core github.com/tarantool/tt/v3@v3.0.0-alpha.2 has no package github.com/tarantool/tt/v3/standard that lists the standard modules: standard needs core v3.0.0-alpha.3 or later; set standard = false and list the modules in [dependencies]
[core]
tt = "v3.0.0-alpha.2"

[distribution]
standard = false

[dependencies]
aeon = "github.com/tarantool/tt/modules/aeon"

Подмена модулей Go

Модуль tt собирается с зависимостями, указанными в его собственном go.mod, но Go применяет директивы replace только из модуля main, поэтому модуль, зависящий от неопубликованной библиотеки или библиотеки не той версии, не может задать подмену сам. Секция [replace] добавляет подмену в go.mod, генерируемый сборкой перед вызовом go mod tidy:

[replace]
"gitlab.corp.mail.ru/tarantool/go-migration" = "../go-migration"
"github.com/tarantool/go-storage/v2" = "github.com/tarantool/go-storage/v2@v2.1.0-rc1"
"github.com/acme/old@v1.2.3" = "github.com/acme/new@main"

Ключ - это путь к модулю Go, при необходимости с @version, чтобы подменить только эту версию, как в go.mod. Значение - это либо локальный каталог (начинается с ./, ../ или / и отсчитывается относительно манифеста), содержащий указанный модуль, либо module@version, где версией может быть любой запрос (ветка, коммит, latest); сборка разрешает его в точную версию, как и для модулей, а локфайл фиксирует её. Ядро, модули из его репозитория и модули tt из [dependencies] здесь подменять нельзя, это считается ошибкой: для ядра есть [core].path и --core, а у модуля tt есть собственные path и version. Подмена, из которой не берётся ни один пакет сборки, ни на что не влияет, и сборка предупреждает об этом.

Локфайл фиксирует каждую запись в [replace]: каталог - через content_hash, вычисленный так же, как для локального модуля (см. выше), а модуль - по его точной версии. Сборка с --locked завершается с ошибкой при изменении подменённого каталога, как и для локального модуля. Флаг --vendor копирует подменённые каталоги в local/replace/ бандла, а go.mod подменяет их по относительному пути, поэтому бандл собирается без доступа к сети.

Сборка на другом ядре

Флаг --core VALUE или переменная окружения TT_DIST_CORE (флаг имеет приоритет) собирает дистрибутив на другом ядре, отличном от указанного в [core], без правки манифеста: на локальном чекауте (существующий каталог или путь, начинающийся с ./, ../ или /, отсчитываемый от каталога проекта) либо по запросу версии, как в [core].tt. Это нужно для сборки дистрибутива на изменениях ядра, которые ещё не вышли в релиз, а также для CI самого tt, собирающего дистрибутивы из своего рабочего дерева:

tt binary build tt --core ../tt
TT_DIST_CORE=. tt binary build tt --manifest dist/tt.manifest.toml

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

Команда tt binary workspace с тем же параметром --core или [core].path записывает go.work, собирающий локальные модули дистрибутива на этом чекауте также для go test и редактора, какую бы версию SDK ни требовал их go.mod; см. Develop together with the core.

Сборка без доступа к сети

Флаг --vendor DIR создаёт бандл вместо бинарного файла: всё то, из чего собирается дистрибутив, и что один лишь тулчейн Go превращает в бинарный файл на машине без сети, кэша модулей и tt.

tt binary build tt --locked --vendor dist/bundle

Бандл содержит сгенерированные go.mod, go.sum и main.go, каталог vendor/ со всеми пакетами, из которых собирается бинарный файл (ядро, модули из его репозитория, модули tt, сторонние модули и внедряемые ими файлы), каталог local/ с копией каждого локального модуля - локального ядра, зависимостей по пути и каталогов из [replace], на которые go.mod перенаправляет сборку по относительному пути, а также параметры сборки: build.env задаёт теги, флаги линковщика и cgo для каждой реализации TLS, реализацию, с которой собирался бандл, тулчейн и версию, а скрипт build.sh выполняет сборку с этими параметрами. Бандл не содержит имён каталогов той машины, на которой он создавался, поэтому его можно перенести куда угодно; при создании он один раз собирается в автономном режиме.

На изолированной машине при наличии тулчейна Go, указанного в build.env (TT_DIST_TOOLCHAIN), или более нового в PATH:

sh bundle/build.sh                         # TLS, с которым собирался бандл
sh bundle/build.sh openssl_static ./tt     # либо default, openssl; и выходной файл

Скрипт build.sh делает следующее:

cd bundle
. ./build.env
GOFLAGS=-mod=vendor GOPROXY=off GOWORK=off GOTOOLCHAIN=local \
CGO_ENABLED=$TT_DIST_CGO_DEFAULT \
    go build -trimpath -tags "$TT_DIST_TAGS_DEFAULT" \
        -ldflags "$TT_DIST_LDFLAGS_DEFAULT" -o tt .

Реализациям OpenSSL требуются компилятор C и заголовки OpenSSL на изолированной машине; на macOS скрипт build.sh использует TT_DIST_LDFLAGS_DARWIN_*.