Сборка модуля на Zig¶
Компонент, собранный с помощью zig, создаёт нативный модуль Tarantool:
библиотеку, которую код приложения загружает через require и которая
содержит C-функции для box.schema.func.create. Тот же компонент может
создавать и программу из того же build.zig.
zig-tarantool
предоставляет коду на Zig API Tarantool и вспомогательные функции для
build.zig, собирающие модуль и программу.
Backend zig входит в число стандартных модулей build tt, которые есть в
официальном tt и в любом дистрибутиве со стандартными модулями:
tt version --modules выводит build, если он присутствует в tt.
Установка zig¶
zig устанавливается самостоятельно: tt его не устанавливает, а ищет zig
в PATH, проверяя сначала .tarantool/bin проекта. Для zig-tarantool и
приведённых здесь примеров требуется zig 0.17.1:
$ zig version
0.17.1
Backend собирает и с zig 0.16, если build.zig не использует
zig-tarantool.
Написание пакета¶
В libs/hello/ пакета с именем myapp файл build.zig.zon задаёт имя
пакета, пока без зависимостей:
.{
.name = .hello,
.version = "0.1.0",
.fingerprint = 0x3610a6861c561281,
.minimum_zig_version = "0.17.1",
.dependencies = .{},
.paths = .{ "build.zig", "build.zig.zon", "src" },
}
Fingerprint взят для нового пакета: zig сам сообщает, что подставить,
если он отсутствует, error: missing top-level 'fingerprint' field; suggested value:
0x....
build.zig собирает модуль hello и программу hello-client:
const std = @import("std");
const tarantool = @import("tarantool");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// zig-out/lib/hello.so, hello.dylib on macOS.
const hello = tarantool.addModule(b, .{
.name = "hello",
.root_source_file = b.path("src/hello.zig"),
.target = target,
.optimize = optimize,
});
tarantool.installModule(b, hello);
// zig-out/bin/hello-client.
const client = tarantool.addExecutable(b, .{
.name = "hello-client",
.root_source_file = b.path("src/client.zig"),
.target = target,
.optimize = optimize,
});
b.installArtifact(client);
}
addModule создаёт библиотеку, символы Tarantool в которой разрешаются при
загрузке в Tarantool, а installModule устанавливает её как lib/hello.so
- имя, под которым её загружает Tarantool (lib/hello.dylib на macOS).
src/hello.zig с C-функцией add и Lua-модулем из одной функции mul:
const t = @import("tarantool");
/// The C function myapp.hello.add.
fn add(a: i64, b: i64) i64 {
return a + b;
}
/// mul of the Lua module, require('myapp.hello').
fn mul(a: i64, b: i64) i64 {
return a * b;
}
comptime {
t.proc.exportProc("add", add);
t.lua.exportModule("myapp_hello", .{ .mul = mul });
}
и src/client.zig - программа, вызывающая add по сети:
const std = @import("std");
const client = @import("tarantool-client");
pub fn main(init: std.process.Init) !void {
const address = init.environ_map.get("TT_URI") orelse "127.0.0.1:3301";
var conn = try client.Connection.connect(init.gpa, init.io, .{
.address = address,
.user = "guest",
.password = "",
});
defer conn.close();
const sum = try conn.call("myapp.hello.add", .{ 20, 22 }, i64);
std.debug.print("20 + 22 = {d}\n", .{sum});
}
Затем в libs/hello/ команда zig fetch --save добавляет zig-tarantool в
build.zig.zon как зависимость tarantool, зафиксированную по коммиту
своими .url и .hash:
$ cd libs/hello
$ zig fetch --save=tarantool git+https://github.com/tarantool-contrib/zig-tarantool#c43e6c84c371b59e89cdc0354b8d377ffdd93dc8
$ grep -A3 '\.tarantool' build.zig.zon
.tarantool = .{
.url = "git+https://github.com/tarantool-contrib/zig-tarantool#c43e6c84c371b59e89cdc0354b8d377ffdd93dc8",
.hash = "tarantool-0.0.0-LczyxTwvEQC19W4vsXUbauN_kO8EABpFyamoek3lPuqV",
},
$ cd ../..
zig fetch --save ищет build.zig пакета, поэтому выполняется после его
создания, а zig 0.17 сохраняет скачанное в zig-pkg/ рядом с build.zig.zon.
Этот каталог не входит в состав файлов пакета: tt не включает его в структуру
каталогов, а при сборке скачивание происходит в отдельный каталог вне исходного
кода (см. ниже). zig-pkg/ и zig-out/ добавляют в .gitignore.
Объявление компонента¶
Блок указывает модуль и программу, создаваемые сборкой:
[components.hello]
path = "libs/hello"
[components.hello.build]
backend = "zig"
module = "hello"
bin = "hello-client"
$ tt package build
$ find .rocks/bin .rocks/lib -name 'hello*'
.rocks/bin/hello-client
.rocks/lib/tarantool/myapp/hello.so
$ find .rocks -path '*zig-pkg*' | wc -l
0
Сборка запускает в каталоге компонента команду
zig build -p _build/component/hello/zig-out --cache-dir _build/component/hello/zig-cache --pkg-dir _build/component/hello/zig-pkg --release=safe
которая выполняет установку в собственный префикс сборки вне исходного кода и
сохраняет там же кэш проекта и скачиваемых им пакетов; tt -V package build
показывает эту строку с абсолютными путями. --pkg-dir передаётся в zig
0.17 и новее, кроме случаев, когда задана переменная ZIG_LOCAL_PKG_DIR,
каталог пакетов из которой zig берёт в таком случае, независимо от того,
экспортирована ли она в окружении запуска tt или задана в env блока: env =
{ ZIG_LOCAL_PKG_DIR = "/home/me/.cache/zig-pkg" } позволяет использовать
один каталог между проектами. zig 0.16 хранит пакеты в своём глобальном кэше
и этот флаг не получает. tt берёт модуль из каталога lib/ префикса:
hello.so или hello.dylib, как его устанавливает installModule, либо
libhello.so или libhello.dylib, как устанавливает библиотеку
b.installArtifact, и копирует его как <module>.so (<module>.dylib на
macOS) туда, где Tarantool ищет это имя. Программа копируется из каталога
bin/ префикса в .rocks/bin/, где её находит описание экземпляра
{binary: hello-client}; см.
Запуск внешнего процесса. Задание только module
собирает только модуль, только bin - только программу, а блок без обоих
полей считается ошибкой. Модуль с точками, module = "codec.fast",
соответствует файлу lib/codec/fast.so префикса, как устанавливает модуль
с таким именем installModule, и codec/fast.so в пространстве имён
компонента.
Если модуль или программа не были установлены сборкой, сборка завершается с ошибкой и выводит список того, что было установлено:
$ tt package build
⨯ building component "hello": zig build installed no module "hullo": .../_build/component/hello/zig-out/lib has none of hullo.so, hullo.dylib, libhullo.so, libhullo.dylib (it installed hello.so); install it with installModule of zig-tarantool, or name the step that installs it in steps
Каталог zig-out/ компонента, остающийся после запуска zig build вручную, не
попадает в структуру каталогов; то же относится к zig-pkg/, остающемуся после
ручных zig fetch --save и zig build, а также к исходным файлам .zig: файл
*.lua компонента попадает в структуру каталогов, как и в любом компоненте, но
файл из zig-pkg/ (например, examples/kv/init.lua из zig-tarantool) в неё не
попадает. Переименование модуля в блоке (module = "greet" вместо hello) не
оставляет старый hello.so: сборка блока с изменениями собирает компонент
заново.
Остальные поля блока:
steps- шаги запускаемогоzig build, по умолчанию его стандартный шагinstall: еслиbuild.zigустанавливает модуль из другого шага, его указывают явно,steps = ["modules"].optimize- режим, в котором выполняется сборка, по умолчаниюReleaseSafe:Debug,ReleaseSafe,ReleaseFastилиReleaseSmall. tt передаёт его как--release=safe,fastилиsmall, аDebug- без флага, чтоbuild.zigпринимает независимо от объявления-Doptimize; еслиstandardOptimizeOptionполучает режим, сборка собирается в нём.options- параметры, объявляемыеbuild.zigчерезb.option, передаваемые в виде-D<name>=<value>, каждый в виде строки:options = { tls = "true" }дляb.option(bool, "tls", ...).optimizeсюда не входит, поскольку задаётся отдельным полем.incremental = trueпропускает сборку, если её блок, файлы компонента, версия zig, а такжеbuild.zigиbuild.zig.zonв текущем каталоге не менялись с прошлой сборки. Изменения зависимости по пути вне компонента не отслеживаются: флаг--rebuildфорсирует пересборку в любом случае.static = trueпроверяет, что программа не зависит от разделяемых библиотек, а модуль зависит только от библиотек C. Блок, собирающий только программу, собирает её под<arch>-linux-musl,-Dtarget, когдаbuild.zigпринимает-Dtarget, а вoptionstarget не указан: программа, линкующая библиотеку C, линкует musl статически. Блок с модулем и программой собирает обе цели под целевую платформу модуля. Программа изaddExecutableне линкует библиотеку C и остаётся статической изначально.
Вызов¶
app.lua в проекте:
local hello = require('myapp.hello')
assert(hello.mul(6, 7) == 42)
box.cfg({listen = '127.0.0.1:3301'})
box.schema.func.create('myapp.hello.add', {language = 'C', if_not_exists = true})
box.schema.user.grant('guest', 'execute', 'function', 'myapp.hello.add',
{if_not_exists = true})
assert(box.func['myapp.hello.add']:call({20, 22}) == 42)
Скрипт запускают в одном терминале, где Tarantool продолжает обслуживать запросы после выполнения скрипта, а программу - в другом:
$ tt run app.lua
$ .rocks/bin/hello-client
20 + 22 = 42
require('<namespace>.<module>')вызывает функциюluaopen_<namespace>_<module>библиотеки, где точки заменяются на_: модуль, которыйexportModuleэкспортирует какmyapp_hello. Приnamespace = ""модуль загружается какrequire('hello')и экспортируется какhello.- C-функция именуется как
<module>.<function>: Tarantool берёт имя модуля из части до последней точки,myapp.hello, а имя функции - из остальной части,add, которую экспортируетexportProc.
Архив tt package pack содержит модуль и программу, собранные под
платформу машины, на которой упаковывался пакет, а экземпляры установленной
версии загружают и запускают их так же, как в проекте.
Тулчейн¶
zig сам скачивает зависимости из build.zig.zon при сборке в свой глобальный
кэш, а zig 0.17 копирует их оттуда в
_build/component/<component>/zig-pkg/: tt package fetch сборку не
запускает, а tt package build --locked сохраняет блокировку tt, не отключая
zig от сети. Хеши в build.zig.zon фиксируют состав скачиваемого zig. Модуль
линкуется с библиотекой C той машины, на которой собирается: собирать его
следует на наиболее старой системе из тех, где он будет запускаться.