app.manifest.toml¶
Манифест пакета в корне его проекта. tt new
создаёт его заготовку.
manifest_version = "0.1"
[package]
name = "kv-api"
description = "A key-value API"
include = ["init.lua"]
[platform]
tarantool = ">=3.0.0,<4.0.0"
tt = ">=3.0.0"
registries = ["https://rocks.tarantool.org/", "./vendor-rocks"]
[dependencies]
checks = ">=3.0.0"
mylib = { source = "path", path = "../mylib" }
[dev_dependencies]
luatest = "*"
[components.app]
path = "kv"
[components.native]
path = "native"
[components.native.build]
backend = "lua-c"
module = "fast_hash"
sources = ["fast_hash.c"]
[products.default]
components = ["app", "native"]
default = true
[hooks.pre_build]
backend = "shell"
command = "./gen.sh"
Неизвестное поле считается ошибкой, если только в манифесте не объявлена более
новая минорная версия manifest_version, чем известна tt, - в этом случае
выводится предупреждение. Более новая мажорная версия отвергается.
Верхний уровень¶
| Поле | Обязательно | |
|---|---|---|
manifest_version |
да | версия формата: "0.1" |
manifest_kind |
нет | "app" по умолчанию; у дистрибутива tt свой манифест, tt.manifest.toml |
[package]¶
| Поле | Обязательно | |
|---|---|---|
name |
да | строчные буквы, цифры и дефисы, имя начинается с буквы; не bin и не manifests |
description |
нет | одна строка, отображается командой tt package list |
license |
нет | |
license_files |
нет | файлы, включаемые в пакет: в корень архива, в doc/ rock-модуля, который упаковывает --format rock, по их путям в проекте, и в исходный rock, даже если git их не отслеживает |
authors |
нет | |
repository |
нет | |
include |
нет | файлы проекта, помещаемые в корень архива |
generate_version_lua |
нет | false исключает version.lua из сборки; по умолчанию true |
[platform]¶
| Поле | Обязательно | |
|---|---|---|
tarantool |
да | версии Tarantool с редакцией: ">=3.0.0" или ">=3.0.0[ce]" для Community, ">=3.3.0[ee]" для Enterprise |
tt |
да | версии tt |
tcm |
нет | версии TCM, включаемые в архив; без редакции |
platforms |
нет | платформы, для которых предназначен пакет: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64 или только any |
registries |
нет | rock-серверы в порядке обращения вместо серверов по умолчанию: URL HTTP(S) или каталоги, относительно манифеста или абсолютные. См. Rock-серверы |
Ограничение версии - список сравнений через запятую, например
">=3.0.0,<4.0.0".
Rock, который зависит от tarantool, проверяется по tarantool: такого
rock-модуля нет ни на одном сервере. Если ни одна из этих версий ему не
подходит, разрешение завершается ошибкой; если не подходит самая младшая, tt
предупреждает, что нижнюю границу стоит поднять. В локфайл для него ничего не
попадает.
[dependencies] и [dev_dependencies]¶
Зависимость - rock в краткой форме:
checks = ">=3.0.0" # ограничение; "*" для любой версии
или в полной форме:
| Поле | |
|---|---|
source |
"registry" (по умолчанию) или "path" |
version |
ограничение версии; обязательно для registry |
path |
каталог с rock-модулем относительно манифеста или абсолютный; обязателен для path. См. Зависимости по пути |
registry |
rock-сервер, откуда брать этот rock: URL HTTP(S) или каталог, относительно манифеста или абсолютный |
Rock с указанным registry разрешается и устанавливается только с этого
сервера; rock-модули, от которых он зависит, берутся из rock-серверов проекта.
Зависимости из [dev_dependencies] устанавливаются для тестов и инструментов
проекта и не упаковываются. Компонент может объявлять собственные зависимости в
[components.<name>.dependencies].
Зависимости по пути¶
Зависимость path собирается из своего каталога в зависимости от того, что в нём
находится:
app.manifest.toml: каталог представляет собой отдельный проект, и tt собирает его так же, какtt package buildсобирает пакет, - компоненты его продукта по умолчанию, их структуру каталогов иversion.lua, - и устанавливает в.rocks/как rock его пакета, с егоlicense_filesвdoc/rock-модуля, как они размещены в его бинарном rock-модуле; если какого-то файла нет, выводится предупреждение. Зависимость называется по имени этого пакета или поrockдругого его продукта, который в таком случае и собирается. Её версия определяется tt в её каталоге, а её зависимости - это зависимости её продукта по умолчанию, разрешаемые вместе с собственными зависимостями проекта: относительныйpathберётся относительно самой зависимости, а зависимость сregistryсохраняет свой сервер. Её[dev_dependencies]и её локфайл не используются; её хуки не запускаются, а rockspec рядом с манифестом игнорируется, каждый раз с предупреждением при разрешении локфайла проекта.*.rockspec: tt собирает rock, который он описывает.- ни того, ни другого: собирать и устанавливать нечего, и локфайл лишь фиксирует каталог без версии; rock проекта от него не зависит.
Локфайл фиксирует зависимость по пути по её пути, относительному от проекта или
абсолютному, как указано в манифесте, и по хешу её файлов. Абсолютный путь
привязывает локфайл к машине: он действует только там, где каталог расположен по
этому пути. Хеш зависимости с манифестом не учитывает .git/, _build/,
.rocks/, _runtime/, её app.manifest.lock и то, что игнорируют её файлы
.gitignore, поэтому ни её собственная сборка, ни сборка проекта не приводят к
устареванию локфайла; новая версия зависимости приводит к устареванию, даже если
её создали только коммит или тег. Зависимость в подкаталоге репозитория, включая
собственный репозиторий проекта, версионируется исключительно по своему
каталогу (см. Сборка): коммит или изменение в
другом месте репозитория не сдвигает её версию. tt собирает такую зависимость в
_build/path/<name>/ проекта - там располагаются её stage, TT_BUILD_DIR её
компонентов и её CARGO_TARGET_DIR - и оставляет её каталог без изменений, кроме
того, что туда записывают сами её бэкенды сборки.
[dependencies]
memcached-contrib = { source = "path", path = "../memcached-contrib" }
[components.NAME]¶
| Поле | |
|---|---|
path |
каталог компонента относительно манифеста; обязательно |
include, exclude |
файлы компонента, включаемые в структуру каталогов; по умолчанию *.lua и *.so, для go по умолчанию ничего |
namespace |
куда помещаются файлы и модули компонента в .rocks/share/tarantool/ и .rocks/lib/tarantool/: по умолчанию имя пакета, "" для верхнего уровня |
dependencies |
зависимости компонента |
build |
его сборка, см. ниже |
kind |
устарело: "module" или "executable", то, что компонент заявляет о результатах своей сборки; см. ниже |
Компонент создаёт то, что создаёт его сборка, и раскладывает свои файлы. Сборка может создавать модули, файлы данных и программы, любые из них одновременно:
| Результат | Куда помещает сборка | Куда устанавливается |
|---|---|---|
| модуль | TT_OUTPUT_DIR, lib/<namespace>/ пакета |
.rocks/lib/tarantool/<namespace>/ |
файл данных, например .wasm |
share/<namespace>/ пакета |
.rocks/share/tarantool/<namespace>/ |
| программа | bin/ пакета |
.rocks/bin/, откуда её запускает tt instance |
То, что создаёт сборка, определяется полями её бэкенда: module и bin у
cargo и zig либо output у make, shell и cmake; go всегда создаёт
программу, c и lua-c - всегда модуль. tt записывает созданное каждым
компонентом, по типам, в _build/results.json. Один компонент пакета cargo с
библиотекой и CLI создаёт и то, и другое:
[components.fast]
path = "fast"
[components.fast.build]
backend = "cargo"
module = "fast"
bin = "fastctl"
Поле kind всё ещё принимается в manifest_version = "0.1" с предупреждением,
components.<name>.kind is deprecated: a component makes what its build makes;
remove it, как заявление компонента о результатах своей сборки, которое tt
проверяет. "executable" означает, что сборка создаёт программы и ничего больше:
компонент не раскладывает никаких своих файлов, поэтому include, exclude и
namespace вызывают ошибку, блок build обязателен, TT_OUTPUT_DIR его
сборки служит каталогом программ, простая строка в output считается программой,
а cargo или zig без module и bin собирают программу с именем
компонента. "module" означает, что сборка не создаёт программ. Backend,
который не умеет создавать то, что указано в kind, или блок, запрашивающий то,
что kind исключает, считаются ошибкой до начала сборки чего бы то ни было, в
components.<name>.kind: is "executable", but backend "c" makes no programs,
is "module", but the build makes programs. Сборка, которая всё же создаёт
такой результат, завершается с кодом возврата 2: kind = "executable", but the
build made more than programs: <files>, kind = "module", but the build made
programs: <files>. В manifest_version = "0.2" поля kind нет.
Файл .wasm, раскладываемый компонентом или записываемый его сборкой в
share/, должен быть бинарным файлом WebAssembly: файл другого вида приводит к
ошибке сборки, а core-модуль, который tarantool-wasm не загружает,
раскладывается с предупреждением. Проверка выполняется так же, как в
стандартном модуле wasm. tt wasm new объявляет компоненты, собираемые
tarawasm; см. Запуск компонентов WebAssembly.
[components.NAME.build]¶
| Поле | Backend'ы | |
|---|---|---|
backend |
c, lua-c (модули); go (программы); cargo, zig (модули и программы); cmake, make, shell (модули, файлы данных и программы) |
|
cwd, env |
все | каталог запуска сборки, её окружение |
output |
make, shell, cmake |
файлы, создаваемые сборкой, которые tt копирует по местам назначения, см. ниже; обязательно для cmake |
incremental |
make, shell, zig |
true пропускает сборку, когда её входные данные совпадают с прошлой сборкой и оставленное ею всё ещё на месте |
make_target, entrypoint, flags |
make |
make_target обязательно |
command, args |
shell |
command обязательно |
module, sources, include_dirs, libraries, library_dirs, defines |
c, lua-c |
module и sources обязательны |
cflags |
c, lua-c |
флаги компиляции исходного кода на C и ассемблере, по одному в элементе, после собственных флагов tt и перед CFLAGS окружения; см. ниже |
cxxflags |
c, lua-c |
флаги компиляции исходного кода на C++, по одному в элементе, после собственных флагов tt и перед CXXFLAGS окружения |
module |
cargo |
собирает библиотеку пакета как модуль с этим именем; блок без module и bin собирает библиотеку под её собственным именем |
platforms.<os> |
c, lua-c |
дополнительные include_dirs, libraries, library_dirs, defines, cflags, cxxflags, ldflags для одной ОС, linux или darwin, после списков сборки |
package |
go, cargo |
пакет Go (по умолчанию .) или пакет cargo |
static |
все | true: то, что создаёт сборка, не требует ничего от машины установки, и сборка это проверяет; см. ниже |
ldflags |
go, c, lua-c |
флаги компоновщика, по одному в элементе: для go build -ldflags - после собственных флагов tt; для компоновки c и lua-c - перед объектами; см. ниже |
name, tags, cgo |
go |
по умолчанию name - имя компонента; cgo по умолчанию выключен |
bin, features, profile |
cargo |
bin собирает бинарный файл с этим именем, программу с тем же именем; profile по умолчанию release |
module, bin |
zig |
модуль и программа, которые сборка берёт из установленного zig build; блок указывает одно из них или оба |
steps, optimize, options |
zig |
шаги zig build, по умолчанию его шаг по умолчанию; режим Debug, ReleaseSafe, ReleaseFast или ReleaseSmall, по умолчанию ReleaseSafe; -D<name>=<value> файла build.zig |
variables, targets, build_type |
cmake |
-D<name>=<value> конфигурации, собираемые цели (по умолчанию все) и CMAKE_BUILD_TYPE (по умолчанию RelWithDebInfo); output обязательно |
output¶
output перечисляет файлы, создаваемые сборкой, которые должны войти в пакет.
Это поле предназначено для сборки, чей инструмент записывает файлы куда ему
угодно, - Makefile, скрипт, проект CMake, - и tt забирает каждый файл оттуда
после завершения сборки и помещает в пакет. Элемент представляет собой строку,
путь к файлу, либо таблицу { path = "...", to = "..." }, указывающую место
назначения. Одиночный элемент можно записать без массива:
output = "dist/calc.wasm" # то же самое, что и ["dist/calc.wasm"]
output = { path = "build/tool", to = "bin" } # то же самое, что и [{ ... }]
output = ["build/tool.so", { path = "build/tool", to = "bin" }]
path задаётся относительно того места, откуда backend забирает файл:
| Backend | path задаётся относительно |
|---|---|
make, shell |
рабочего каталога сборки: cwd, задаваемого относительно проекта, или каталога компонента, если у блока нет cwd |
cmake |
дерева сборки, _build/component/<component>/ проекта (TT_BUILD_DIR) |
| backend модуля | того места, которое указано в его документации; backend, чей результат копирует tt, забирает его из рабочего каталога, как и make |
Файл забирается после успешного завершения сборки; файл, который сборка не создала, приводит к ошибке с кодом возврата 2:
⨯ building component "rates": copy declared output "dist/rates.json": opening the source: open /home/me/shop/rates/dist/rates.json: no such file or directory
Инкрементальная сборка, не требующая обновления, снова забирает файл из того же места и запускает сборку заново, если файл оттуда пропал.
Параметр to указывает, куда направляется файл. tt помещает его туда под его
базовым именем - каталоги из path отбрасываются - внутри пакета. Команда
tt package build устанавливает пакет в .rocks/ проекта, tt package pack
упаковывает этот .rocks/ в архив, а tt package install устанавливает его по
тем же путям: в .rocks/ проекта или версии приложения,
<root>/versions/<name>/<name>_<version>/.rocks/, в областях установки
пользователя и системы:
to |
Чем является файл | Куда устанавливается в .rocks/ |
|---|---|---|
lib |
модуль, загружаемый через require |
lib/tarantool/<namespace>/<file> |
share |
файл данных, например .wasm |
share/tarantool/<namespace>/<file>, рядом с файлами Lua пакета |
bin |
программа, исполняемый файл компонента, по которому его находит tt instance |
bin/<file> |
<namespace> - это namespace компонента, по умолчанию имя пакета. Элемент
без to считается модулем (lib), за исключением бэкенда, создающего файлы
только одного типа, чей тип он тогда и принимает, - файл данных бэкенда файлов
данных, - и компонента с kind = "executable", чьи файлы считаются программами.
Программа проверяется так же, как и любая программа.
Это отличается от include, который раскладывает файлы из каталога компонента
по их исходным путям: include = ["dist/calc.wasm"] устанавливает
share/tarantool/<namespace>/dist/calc.wasm, а
output = { path = "dist/calc.wasm", to = "share" } устанавливает
share/tarantool/<namespace>/calc.wasm. Файл, указанный в output, не
раскладывается, если только его не захватывает include.
Пакет, чья сборка создаёт файл JSON, читаемый кодом на Lua:
shop/
├── app.manifest.toml
├── app/init.lua
└── rates/build.sh
shop/app.manifest.toml:
manifest_version = "0.1"
[package]
name = "shop"
[platform]
tarantool = ">=3.0.0"
tt = ">=3.0.0"
[components.app]
path = "app"
[components.rates]
path = "rates"
[components.rates.build]
backend = "shell"
command = "sh"
args = ["build.sh"]
output = { path = "dist/rates.json", to = "share" }
shop/rates/build.sh, запускаемый в rates/:
mkdir -p dist
printf '{"usd": 90}\n' > dist/rates.json
shop/app/init.lua, модуль shop, находящий файл рядом с собой:
local fio = require('fio')
local json = require('json')
local M = {}
-- rates.json is a data file of the package: tt installs it into the
-- directory of the package, next to this file.
function M.rates()
local file = assert(fio.open(fio.pathjoin(debug.sourcedir(), 'rates.json')))
local data = file:read()
file:close()
return json.decode(data)
end
return M
$ cd shop
$ tt package build
$ find .rocks/share/tarantool/shop -type f | sort
.rocks/share/tarantool/shop/init.lua
.rocks/share/tarantool/shop/rates.json
.rocks/share/tarantool/shop/version.lua
$ tt run -e "print(require('shop').rates().usd) os.exit()"
90
rates/build.sh и rates/dist/ в структуру каталогов не попадают: по умолчанию
include берёт *.lua и *.so. debug.sourcedir() возвращает каталог файла
Lua, вызывающего функцию, поэтому модуль находит файл везде, где установлен
пакет. Код вне пакета читает его по пути от каталога приложения, служащего
рабочим каталогом его экземпляров и команды tt run, запущенной в корне
проекта: .rocks/share/tarantool/shop/rates.json.
Любое другое значение to считается ошибкой: components.rates.build.output[0].to:
"etc" is not lib, share or bin, как и таблица без path; значение, не
являющееся ни строкой, ни таблицей, ни массивом из них, даёт output must be a
file, a table { path = ..., to = ... } or an array of them, got integer.
Backend, не создающий файлов такого типа, отвергает элемент:
components.a.build.output[0].to: backend "wasm-tool" makes no data files.
Поле output у бэкенда, не имеющего такого поля (например, c), отвергается
так же, как любое поле чужого бэкенда ниже.
Поле бэкенда, отличного от используемого в сборке, считается ошибкой, поскольку
оно ничего бы не делало: cflags в сборке make, make_target в сборке или
хуке shell, output в сборке c. Поле принадлежит блоку независимо от его
значения, в том числе make_target = "". Ошибка перечисляет бэкенды, у
которых есть это поле, модуль за модулем в порядке имён модулей, а внутри модуля
- в его порядке: для стандартного модуля build сначала make и shell, затем
остальные по имени: components.a.build.ldflags: is a field of backend c, go or
lua-c, not of "cargo".
Описанные выше бэкенды принадлежат build, стандартному модулю tt
(modules/build его репозитория): в ядре собственных бэкендов нет, а в
официальном tt и в каждом дистрибутиве, включающем стандартные модули, они есть.
Модуль, с которым собран tt, может предоставлять дополнительные бэкенды (см.
Написание бэкенда сборки) со своими
собственными полями, проверяемыми так же, как поля build, а их сборки проходят
через те же шаги: до начала любой сборки, в описанном ниже окружении, и
раскладываются, фиксируются и пропускаются через incremental точно так же, как
сборки build. В дистрибутиве, исключающем build (см.
Стандартные модули), есть только бэкенды
его остальных модулей.
Блок сборки с бэкендом, который не предоставляет ни один модуль этого tt,
вызывает предупреждение:
no module of this tt provides backend "<name>"; its fields are not checked для
команд, которые ничего не собирают, таких как tt package add или
tt package pack --format rock-src. Как только tt предстоит собрать компонент -
командами tt package build и pack, а также tt package fetch для
зависимости по пути или собираемого ею исходного rock-модуля, - это приводит к
ошибке ещё до начала сборки чего бы то ни было, и ошибка называет зависимость.
Поля блока сборки проверяются при проверке манифеста, а не при его чтении: по
правилам версии формата выше для полей, которых нет ни у одного бэкенда, и с
путём поля для значения неверного типа:
components.a.build.cflags: must be an array, not a string.
Сборка получает свой контракт через переменные окружения: TT_OUTPUT_DIR, куда
она помещает создаваемые модули и который уже существует к началу сборки (для
компонента с kind = "executable" - программы), TT_PROJECT_ROOT,
TT_PACKAGE, TT_COMPONENT_NAME, TT_VERSION, TT_PLATFORM_OS и
TT_PLATFORM_ARCH. Если tt знает Tarantool, под который выполняется сборка,
сборка также получает TT_TARANTOOL_PREFIX (префикс установки этого Tarantool)
и TT_TARANTOOL_INCLUDE_DIR (каталог его файлов module.h и lua.h,
<prefix>/include/tarantool, под которые компилируют бэкенды c и lua-c);
если tt его не знает, обе переменные не заданы, как и
TT_TARANTOOL_INCLUDE_DIR, если module.h отсутствует (см.
Заголовки для rock-модулей с частью на C,
где описано, где tt их ищет). Поле env блока сборки не может их
переопределить. Если tt не находит Tarantool вовсе или не находит его
заголовков, компонент c или lua-c завершает сборку ошибкой ещё до её начала
из-за отсутствия заголовков с указанием каталогов, где tt их искал.
TT_BUILD_DIR - собственный каталог сборки для промежуточных результатов,
создаваемых из исходного кода: объектных файлов, дерева сборки. Это
_build/component/<component>/, существующий к началу сборки и сохраняющийся
между сборками, так что сборка make пересобирает только изменившееся; флаг
--rebuild сначала очищает его, и то же происходит при сборке блока,
изменившегося со времени прошлой сборки. Сборка make или shell, пишущая
туда, а не рядом с исходным кодом, оставляет каталог компонента нетронутым, как
и каталог зависимости по пути - другого рабочего дерева.
c и lua-c компилируют каждый исходный файл из sources относительно cwd
в объектный файл в TT_BUILD_DIR и компонуют объекты в один модуль,
<module>.so (<module>.dylib на macOS), в каталоге TT_OUTPUT_DIR.
Расширение исходного файла определяет его язык, а значит, компилятор и его
флаги:
| Расширение | Язык | Компилятор | Флаги языка |
|---|---|---|---|
.c |
C | $CC, cc по умолчанию |
cflags, $CFLAGS |
.cc, .cpp, .cxx, .c++ |
C++ | $CXX, c++ по умолчанию |
cxxflags, $CXXFLAGS |
.S, .s |
ассемблер, .S проходит через препроцессор |
$CC |
cflags, $CFLAGS |
Расширения чувствительны к регистру, а .C не поддерживается: на macOS a.C
и a.c - один и тот же файл. Исходный файл с другим расширением считается
ошибкой: components.hashkit.build.sources[1]: "fnv.h" is not a source tt
compiles: want a name ending in .c, .cc, .cpp, .cxx, .c++, .S or .s; a
prebuilt library goes into libraries and library_dirs - как и исходный файл,
указанный дважды. Каждый исходный файл компилируется отдельно, исходный код
модуля - одновременно, в столько потоков, сколько у машины ядер процессора:
$CC -O2 -fPIC <cflags> <$CFLAGS> -I<include dir of Tarantool> -D<defines> -I<include_dirs> \
-MD -MF <object>.d -MQ <object> -c <source> -o <object>
$CXX -O2 -fPIC <cxxflags> <$CXXFLAGS> -I<include dir of Tarantool> -D<defines> -I<include_dirs> \
-MD -MF <object>.d -MQ <object> -c <source> -o <object>
а объектные файлы компонуются с помощью $CXX, если среди исходного кода есть
C++, и с помощью $CC в противном случае:
$CXX -shared <ldflags> -o <module>.so <objects> \
-L<library_dirs> -Wl,-rpath,<library_dirs> -l<libraries> <$LDFLAGS>
Флаги компиляции выстраиваются по цепочке: сначала собственные флаги tt,
затем проекта, затем пользователя: -O2, опускаемый, когда переменная
соответствующего языка, CFLAGS или CXXFLAGS, задана (даже пустой), и
-fPIC; затем cflags или cxxflags; затем разбитая по пробелам переменная
CFLAGS или CXXFLAGS окружения, которая идёт последней и потому разрешает
конфликты в свою пользу, аналогично тому, как CFLAGS идёт после AM_CFLAGS
в autotools: CFLAGS="-O0 -g" компилирует исходный код на C для отладчика, а
CFLAGS=-Wno-error собирает проект, в чьих cflags указан -Werror,
компилятором, выдающим новые предупреждения. Флаги одного языка не доходят
до исходного кода другого (-std=c11 привело бы к ошибке компиляции C++), тогда
как defines, include_dirs, -fPIC и заголовки Tarantool передаются обоим.
Компоновка не получает никаких флагов компиляторов: флаг, нужный как при
компиляции, так и при компоновке (-pthread, -fsanitize=address, -flto,
-m32 или --target=...), указывается в cflags (и cxxflags) и в ldflags.
Флаги ldflags идут перед объектными файлами, как в вызове
$(CC) $(LDFLAGS) -o out objs $(LDLIBS) утилиты make, так что -Wl,--as-needed
действует на последующие -l; строка завершается переменной LDFLAGS
окружения. Список platforms.<os> идёт после списка самой сборки; <os> - это
linux или darwin, операционные системы, для которых собирает tt, а любая
другая (например, macos) считается ошибкой. На macOS вместо -shared
передаётся -bundle -undefined dynamic_lookup -all_load, а -Wl,-rpath не
передаётся.
Переменные CC и CXX делятся на слова так же, как shell делит команду, с
поддержкой '...', "..." и \ и без подстановок, поэтому компилятор можно
запускать через обёртку или с собственными аргументами: CC="ccache cc",
CC="zig cc" CXX="zig c++", CC="'/opt/my tools/gcc'". Первое слово ищется в
PATH сборки. CC, CXX, CFLAGS, CXXFLAGS и LDFLAGS берутся из
окружения, в котором запущен tt, и компилятор не читает ни одну из них: в env
сборки каждая из них считается ошибкой, поскольку никуда бы не дошла, а флаги
проекта задаются в cflags, cxxflags и ldflags. То же относится к
CPPFLAGS, LIBS и LDLIBS, которые не читают ни tt, ни компилятор:
defines, include_dirs, cflags и cxxflags принимают то, что
передавалось бы через CPPFLAGS, а libraries и library_dirs - через LIBS.
tt -V package build показывает каждую команду перед её запуском и вывод
успешной компиляции (её предупреждения); без -V упавшая компиляция выводит
свою команду и то, что она напечатала, в тексте ошибки.
Модулю на C++ требуется библиотека C++. На Linux сборка с static = true
линкует libstdc++ в модуль с флагами
-static-libstdc++ -Wl,--exclude-libs,ALL, причём второй флаг исключает её
символы из экспорта модуля: в сам Tarantool библиотека libstdc++ уже
встроена, поэтому на машине выполнения libstdc++.so.6 может отсутствовать.
Однако статическая libstdc++ из нового gcc требует glibc той машины, на
которой она была собрана (так, gcc 15 требует glibc 2.38 там, где модулю на
C достаточно 2.14), поэтому такой модуль загружается только там, где
Tarantool работает на столь же новой glibc; сборка предупреждает, если эта
версия новее glibc того Tarantool, под который собирается модуль. Без static
модулю требуется libstdc++.so.6 машины. На macOS модулю требуется
/usr/lib/libc++.1.dylib - системная библиотека C++, которая нужна и самому
Tarantool, и static = true её допускает. zig c++ (CXX="zig c++" или
компилятор, среди слов которого есть zig, а сразу за ним cc или c++: так
его называют и через обёртку, ccache zig cc) линкует собственную libc++ в
каждый модуль статически со скрытием символов, поэтому его компоновка не
получает ни одного из этих флагов (zig отклоняет --exclude-libs), а модуль не
требует библиотеки C++ независимо от значения static. Скрипт другого имени,
который запускает zig, за zig не считается.
[components.memcached.build]
backend = "lua-c"
module = "datapath"
sources = ["datapath.c", "ring.cpp"]
cflags = ["-std=gnu99", "-Wall", "-Wextra", "-Werror"]
cxxflags = ["-std=c++17", "-Wall"]
[components.memcached.build.platforms.linux]
ldflags = ["-Wl,--as-needed"]
[components.memcached.build.platforms.darwin]
cflags = ["-Wno-deprecated-declarations"]
Исходный файл на C++ для lua-c подключает Lua API через #include <lua.hpp>:
заголовочные файлы lua.h, lauxlib.h и lualib.h Tarantool не содержат
extern "C", поэтому исходный файл C++, подключающий их напрямую, объявляет Lua
API с именами C++, и модуль не загружается: undefined symbol:
_Z15luaL_checkstackP9lua_StateiPKc. Файл module.h объявляет собственные
функции как extern "C". Точка входа модуля на C++ также объявляется как
extern "C".
lua-c проверяет модуль после компоновки: сборка завершается ошибкой, если
модуль не экспортирует luaopen_<name> - функцию, которую вызывает
require('<name>') (<name> - это <namespace>.<module> или <module>
при namespace = "", где точки заменены на _, а часть до первого -
отброшена, как это делает Lua: require('my-app.fast') вызывает
luaopen_app_fast), а также если модуль требует функции Lua API по их именам
в C++. Проверяется каждый срез универсального файла Mach-O. Модуль c, чьи
функции Tarantool вызывает по именам box.schema.func, этим проверкам не
подлежит.
⨯ building component "hashkit": .../hashkit/_build/rock/default/lib/hashkit/fnv.so: the module needs functions of the Lua API by their C++ names: _Z17luaL_checkintegerP9lua_Statei, _Z15lua_pushintegerP9lua_Statel: lua.h, lauxlib.h and lualib.h of Tarantool declare no extern "C", so a C++ source includes them through <lua.hpp>, which does, or within extern "C" { }
⨯ building component "hashkit": .../hashkit/_build/rock/default/lib/hashkit/fnv.so: the module exports no luaopen_hashkit_fnv, the function require("hashkit.fnv") calls: define int luaopen_hashkit_fnv(lua_State *L), extern "C" in C++, or set module to the name the module is for
Сборка компилирует только то, что изменилось с прошлой сборки. Объектный файл
компилируется заново, когда изменилась его командная строка, компилятор (его
бинарный файл, размер и время изменения этого файла, вывод -dumpmachine и
--version), переменная окружения, которую читает компилятор (CPATH,
SOURCE_DATE_EPOCH, SDKROOT, MACOSX_DEPLOYMENT_TARGET и подобные,
C_INCLUDE_PATH для исходного кода на C или ассемблере, CPLUS_INCLUDE_PATH
для C++; но не TMPDIR), его исходный файл или файл, прочитанный прошлой
компиляцией: каждый заголовок из списка -MD, включая заголовки Tarantool и
системы. Модуль компонуется заново, когда изменился объектный файл, команда
компоновки, компилятор компоновки, LIBRARY_PATH или файл из libraries в
library_dirs, либо когда сам модуль отсутствует. Файл, указанный только во
флаге (например, version script в ldflags), и библиотеки, найденные в других
местах, не отслеживаются: tt package build --rebuild пересобирает всё заново,
как и изменение блока сборки. Объектные файлы и записи сборки о них хранятся в
_build/component/<component>/obj/.
Каждая сборка также записывает
_build/component/<component>/compile_commands.json - базу данных компиляции
исходного кода компонента с командой для каждого из них, предназначенную для
clangd и других читающих её инструментов. clangd ищет этот файл только в
каталогах выше исходного кода и в их build/, поэтому для каждого компонента на
C его указывают в файле .clangd проекта:
If:
PathMatch: memcached/.*
CompileFlags:
CompilationDatabase: _build/component/memcached
CompilationDatabase задаёт каталог этого файла относительно каталога
.clangd. Для проекта с одним таким компонентом подходит и ссылка в корне
проекта, которую clangd находит над любым исходным кодом:
ln -s _build/component/memcached/compile_commands.json . с добавлением
/compile_commands.json в .gitignore.
cmake собирает проект CMake из cwd, где расположен его CMakeLists.txt, вне
исходного кода, в каталоге TT_BUILD_DIR:
cmake -S <cwd> -B _build/component/<component> -DCMAKE_BUILD_TYPE=<build_type> \
-D<name>=<value>... -DCMAKE_PREFIX_PATH=<prefix of Tarantool>
cmake --build _build/component/<component> --config <build_type> --parallel <CPUs> \
--target <targets>...
и копирует перечисленные в output файлы относительно дерева сборки туда, куда
направляется каждый из них; файл, который сборка не создала, приводит к ошибке.
Префикс Tarantool добавляется после префиксов, заданных переменной
CMAKE_PREFIX_PATH в variables, так что вызов
find_path(... tarantool/module.h) из типового FindTarantool.cmake находит
его заголовки. Дерево сборки сохраняется между сборками, и cmake пересобирает
изменившееся в нём; флаг --rebuild конфигурирует его заново, как и сборка
перемещённого проекта. Переменная CMAKE_BUILD_PARALLEL_LEVEL, если она задана,
определяет число задач, а CMAKE_GENERATOR в env выбирает другой генератор.
На macOS модуль .so копируется как .dylib, который загружает там Tarantool.
Программа сборки задаётся элементом output с to = "bin". На PATH должен
присутствовать CMake 3.15 или новее. Компонент конфигурируется с версией
политик, запрошенной его cmake_minimum_required: CMake 4 отвергает версии
старше 3.5, а переменная CMAKE_POLICY_VERSION_MINIMUM, устанавливаемая tt для
собираемых им rock-модулей, не пробрасывается дальше, тогда как переменная,
заданная в env или в окружении запуска tt, пробрасывается.
[components.memcached]
path = "memcached"
include = ["init.lua"]
[components.memcached.build]
backend = "cmake"
cwd = "."
variables = { ENABLE_BUNDLED_SMALL = "ON" }
targets = ["internalso"]
output = ["memcached/internal.so"]
cargo собирает библиотеку пакета для module: cdylib, являющуюся нативным
модулем <module>.so (<module>.dylib на macOS); бинарный файл bin для
bin, программу bin; оба при указании обоих; и библиотеку под её собственным
именем, если не указано ни то, ни другое. Сборка получает CARGO_TARGET_DIR,
_build/cargo/, общий для всех cargo-компонентов проекта, подобно тому как
пакеты workspace разделяют его target/: то, от чего они зависят,
компилируется один раз. Настройка target-dir конфигурации cargo уступает этой
переменной, но CARGO_TARGET_DIR или CARGO_BUILD_TARGET_DIR, заданные в env
или в окружении запуска tt, сохраняются. Библиотека и бинарный файл забираются
оттуда, куда cargo сообщает об их сборке. --rebuild запускает cargo как
обычно, и cargo пересобирает изменившееся, включая смену компилятора. Каталог
target/ собираемого cargo компонента в структуру каталогов не попадает. См.
Сборка модуля на Rust.
zig запускает zig build для build.zig из cwd, устанавливая результаты в
_build/component/<component>/zig-out/ и сохраняя кеш в соседнем каталоге
zig-cache/:
zig build <steps>... -p _build/component/<component>/zig-out \
--cache-dir _build/component/<component>/zig-cache \
[--pkg-dir _build/component/<component>/zig-pkg] [--release=<mode>] -D<name>=<value>...
Флаг --pkg-dir, указывающий каталог, где zig 0.17 сохраняет скачиваемые для
build.zig.zon пакеты (по умолчанию соседний zig-pkg/), передаётся zig версии
0.17 и новее, если только не задана переменная ZIG_LOCAL_PKG_DIR,
экспортированная в окружении запуска tt или в env блока; zig 0.16 хранит их в
своём глобальном кеше и отвергает этот флаг.
Параметр optimize передаётся как --release=safe, fast или small, а
Debug передаётся без флага, так что build.zig, не объявляющий -Doptimize,
тоже работает; options передаются в порядке своих имён, и optimize среди них
быть не должно. Модуль module берётся из lib/ префикса: <module>.so или
.dylib, как его устанавливает installModule из zig-tarantool, либо
lib<module>.so или .dylib, как библиотеку устанавливает b.installArtifact,
и копируется как <module>.so (<module>.dylib на macOS); модуль с точкой в
имени, a.b, берётся там как lib/a/b.so и помещается как a/b.so в
namespace компонента. Программа bin берётся из bin/ префикса. Блок, не
указывающий ни того, ни другого, считается ошибкой, как и модуль или программа,
которые сборка не установила, - при этом перечисляется то, что она установила.
Флаг --rebuild очищает префикс, кеш и пакеты. Каталоги zig-out/ и zig-pkg/
компонента, собираемого zig, в структуру каталогов не попадают. Входными данными
инкрементальной сборки incremental также служат версия zig и файлы build.zig
и build.zig.zon из cwd. zig сам скачивает зависимости из build.zig.zon в
процессе сборки. См. Сборка модуля на Zig.
Значение static = true требует, чтобы результат сборки не нуждался ни в чём от
машины, на которую устанавливается пакет, и сборка это проверяет: файл,
требующий большего, завершает сборку ошибкой с кодом возврата 2, называя файл и
то, что ему требуется.
- Программе не нужны загрузчик и динамические библиотеки. Сборкам
go,cargoиzigдаётся указание собирать её именно так только под Linux:cargoсобирает бинарный файл под musl, а модуль из того же блока - как обычный модуль;zigсобирает программу из блока без модуля под musl,-Dtarget=<arch>-linux-musl, когдаbuild.zigпринимает-Dtargetи вoptionsне указанtarget, а программу из блока с модулем - под target модуля; то, что собираютcmake,makeиshell, только проверяется. - Модулю не нужны никакие динамические библиотеки, кроме библиотек стандартной
библиотеки C, которые сам Tarantool уже загрузил при старте: на Linux это
libc.so.6,libm.so.6,libdl.so.2,libpthread.so.0,librt.so.1, загрузчикld-linux-*или (для musl)ld-musl-*иlibc.musl-*, а такжеlibgcc_s.so.1- среда выполнения GCC, необходимая любой сборке Tarantool; на macOS -/usr/lib/libSystem.B.dylibи/usr/lib/libc++.1.dylib(системная библиотека C++, которая требуется и самому Tarantool) и каждый срез универсального бинарного файла. Нативными файлами считаются те, которые сборка записывает вTT_OUTPUT_DIR, и файлы компонента, захватываемые структурой каталогов. От бэкенда ничего не требуется, кромеcиlua-c, которые линкуютlibstdc++в модуль на C++ под Linux: библиотека, нужная модулю (например,libsasl2.so.2), линкуется статически из своего.aлибо загружается во время выполнения черезdlopen, а модуль на C++ другого бэкенда линкуетlibstdc++с флагом-static-libstdc++. Модуль, требующий более новую glibc, чем Tarantool, под который он собран, собирается с предупреждением: он не загрузится там, где этот Tarantool работает со старой glibc.
Входными данными инкрементальной сборки incremental являются её блок сборки и
файлы компонента, кроме скрытых, _build/, _runtime/ и того, что игнорируют
файлы .gitignore проекта и компонента: то, что сборка генерирует сама и что git
не отслеживает, входными данными не считается. Хеш входных данных её последней
сборки сохраняется в _build/cache/<component>.json, а флаг --rebuild команд
tt package build и tt package pack всё равно запускает сборку; так же
поступает и следующая сборка после tt package clean <component>, удаляющей хеш
и созданное сборкой. См. Инкрементальная сборка
и Очистка.
Каталог .tarantool/bin проекта, куда команды tt binary и tt wasm prepare
помещают программы проекта, идёт первым в PATH сборки и хука: параметр
command может ссылаться на такую программу без выполнения
.env/activate.sh. Программа ищется только в этом PATH: блок, чей env
задаёт PATH, получает программы из этого PATH и из .tarantool/bin, а
программа, присутствующая только в собственном PATH tt, найдена не будет.
tt -V package build выводит в журнал каждую команду, запускаемую сборкой или
хуком, и каталог её выполнения перед её запуском, а также показывает её
вывод; без флага -V эта информация вместе с самой командой выводится только при
ошибке.
[products.NAME]¶
| Поле | |
|---|---|
components |
компоненты продукта; обязательно |
default |
true для продукта, выбираемого build и pack без флага --product; ровно один продукт является продуктом по умолчанию |
rock |
имя rock-модуля, под которым выпускается продукт, [a-z][a-z0-9-]*; по умолчанию имя пакета для продукта по умолчанию, отсутствует для остальных |
Манифест без секции [products] содержит один продукт, default, состоящий из
всех компонентов.
Пакет из нескольких rock-модулей, например модуль и сопутствующие утилиты,
задаёт каждому продукту, от которого зависят другие проекты, собственный rock.
Два продукта, выпускаемые как два rock-модуля, не имеют общих компонентов,
поскольку дерево установки обоих содержало бы их файлы дважды, а файл
version.lua продукта помещается под именем его rock-модуля,
<rock>/version.lua, а не под именем пакета. Команда
tt package pack --format rock --product NAME упаковывает продукт как его rock;
продукт без указания rock упаковать нельзя. Зависимость по пути представляет
собой продукт пакета в её каталоге: продукт по умолчанию по имени пакета, другой
продукт - по имени его rock-модуля.
[hooks.pre_build], [hooks.post_build] и [hooks.clean]¶
Команда, запускаемая до или после сборки компонентов с помощью бэкенда shell
(по умолчанию) или make и полей сборки. Hook получает окружение сборки без
TT_OUTPUT_DIR, TT_COMPONENT_NAME и TT_BUILD_DIR, а файлы из его output
не копируются. Hook указывает backend, поддерживающий запуск хуков: make или
shell стандартного модуля build либо backend модуля, объявляющего такую
поддержку; любой другой считается ошибкой: hooks.pre_build: backend "cmake" is
not supported (want make or shell). tt без бэкенда, поддерживающего хуки
(например, дистрибутив без build), отклоняет любые хуки, в том числе не
указывающие backend вовсе: hooks.pre_build: backend "shell" is not supported: no
module of this tt provides a backend that runs hooks.
[hooks.clean] запускается командой tt package clean для пакета целиком, без
указания конкретного компонента, после того как бэкенды компонентов очистили
оставленное своими инструментами и до того, как tt удалит _build/. Этот hook
предназначен для того, что проект генерирует рядом со своим исходным кодом
самостоятельно и что tt сам не удаляет: например, для созданного хуком
pre_build.
[hooks.pre_build]
command = "sh"
args = ["-c", "mkdir -p src/gen && date +'return %Y' > src/gen/year.lua"]
[hooks.clean]
command = "rm"
args = ["-rf", "src/gen"]
Завершившийся неудачей hook приводит к завершению команды с кодом возврата 2:
до начала сборки чего бы то ни было для pre_build и до удаления чего бы то ни
было для clean. Версия tt, выпущенная раньше появления этого хука, пропускает
[hooks.clean] с предупреждением: unknown hook "clean" skipped.