Build a module in Zig¶
A component built by zig makes a native module of Tarantool: a library,
which the code of the application loads with require, and which holds the
C functions of box.schema.func.create. The same component may make a
program too, from the same build.zig.
zig-tarantool gives
the Zig code the API of Tarantool, and the build.zig helpers that build a
module and a program.
The zig backend is one of the standard module build of tt, which the
official tt and every distribution that takes the standard modules have:
tt version --modules lists build in a tt that has it.
Get zig¶
zig is yours to install: tt does not install it, and looks for zig on
PATH, .tarantool/bin of the project first. zig-tarantool and the
examples here need zig 0.17.1:
$ zig version
0.17.1
The backend builds with zig 0.16 too, a build.zig that does not use
zig-tarantool.
Write the package¶
In libs/hello/ of a package named myapp, build.zig.zon names the
package, with no dependency yet:
.{
.name = .hello,
.version = "0.1.0",
.fingerprint = 0x3610a6861c561281,
.minimum_zig_version = "0.17.1",
.dependencies = .{},
.paths = .{ "build.zig", "build.zig.zon", "src" },
}
The fingerprint is that of a new package: zig says what to put when it is
missing, error: missing top-level 'fingerprint' field; suggested value:
0x....
build.zig builds the module hello and the program 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 makes a library whose symbols of Tarantool are resolved when
Tarantool loads it, and installModule installs it as lib/hello.so, the
name Tarantool loads, lib/hello.dylib on macOS.
src/hello.zig, with a C function, add, and a Lua module of one
function, 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 });
}
and src/client.zig, a program that calls add over the network:
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});
}
Then, in libs/hello/, zig fetch --save adds zig-tarantool to
build.zig.zon as the dependency tarantool, pinned to a commit by its
.url and its .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 looks for the build.zig of the package, so it comes
after it, and zig 0.17 puts what it fetched into zig-pkg/ beside
build.zig.zon. That
directory is no file of the package: tt leaves it out of the layout, and
its build fetches into a directory of its own, out of the sources (see
below). Put zig-pkg/ and zig-out/ into .gitignore.
Declare the component¶
The block names the module and the program the build makes:
[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
The build runs, in the directory of the component,
zig build -p _build/component/hello/zig-out --cache-dir _build/component/hello/zig-cache --pkg-dir _build/component/hello/zig-pkg --release=safe
which installs into a prefix of the build's own, out of the sources, and
keeps the cache of the project and the packages it fetches there too;
tt -V package build shows the line, with absolute paths. --pkg-dir is
given to zig 0.17 and later, and not when ZIG_LOCAL_PKG_DIR is set,
the directory of the packages zig takes then, whether it is exported where
tt runs or set by the env of the block: env =
{ ZIG_LOCAL_PKG_DIR = "/home/me/.cache/zig-pkg" } shares one between
projects. zig 0.16 keeps the packages in its global cache and is given
none. tt takes the module from lib/ of the prefix, hello.so or
hello.dylib as installModule installs it, or libhello.so or
libhello.dylib as b.installArtifact installs a library, and copies it
as <module>.so, <module>.dylib on macOS, where Tarantool looks for that
name. The program comes from bin/ of the prefix, into .rocks/bin/,
where an instance description {binary: hello-client} finds it; see
Run an external process. module alone builds the
module only, bin alone the program only, and a block with neither is an
error. A dotted module, module = "codec.fast", is the file
lib/codec/fast.so of the prefix, as installModule installs a module of
that name, and codec/fast.so in the namespace of the component.
A module or a program the build did not install fails it, saying what it installed:
$ 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
A zig-out/ of the component, which zig build run there by hand leaves,
is not laid out, nor is its zig-pkg/, which zig fetch --save and
zig build run there leave, and neither are the .zig sources: a
*.lua file of the component is laid out as in any component, but one
of zig-pkg/, as examples/kv/init.lua of zig-tarantool, is not. A
module renamed in the block, module = "greet" for hello, leaves no
hello.so behind: a build of a block that changed starts the component
afresh.
The other fields of the block:
stepsare the steps ofzig buildrun, its default step,install, when there are none: abuild.zigthat installs the module from another step names it,steps = ["modules"].optimizeis the mode the build is made in,ReleaseSafeby default:Debug,ReleaseSafe,ReleaseFastorReleaseSmall. tt passes it as--release=safe,fastorsmall, andDebugas no flag, which abuild.zigtakes whether or not it declares-Doptimize; one whosestandardOptimizeOptiongets it builds in that mode.optionsare the options thebuild.zigdeclares withb.option, given as-D<name>=<value>, each a string:options = { tls = "true" }forb.option(bool, "tls", ...).optimizeis not one of them, as the field says it.incremental = trueskips the build when its block, the files of the component, the version of zig andbuild.zigandbuild.zig.zonofcwdare those of the last one. A change of a path dependency outside the component is not seen:--rebuildbuilds anyway.static = truechecks that the program needs no shared library, and the module none but those of the C library. A block that builds a program alone builds it for<arch>-linux-musl,-Dtarget, when thebuild.zigtakes-Dtargetandoptionsnames notarget: a program that links the C library links musl in. A block of a module and a program builds both for the target of the module. A program ofaddExecutablelinks no C library and is static as it is.
tt package build --target linux/arm64 builds for another platform than
the machine (see
Other platforms): zig has
what it links for every target in itself, and is given
-Dtarget=aarch64-linux-gnu, aarch64-linux-musl for a static program
alone, or aarch64-macos for darwin/arm64. The build.zig is to take
-Dtarget, as b.standardTargetOptions declares it: one that does not,
and a block whose options name a target, fail the build, since zig
would build for the machine or the target of the options.
Call it¶
app.lua in the project:
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)
Run it in one terminal, where Tarantool goes on serving after the script, and the program in another:
$ tt run app.lua
$ .rocks/bin/hello-client
20 + 22 = 42
require('<namespace>.<module>')calls the functionluaopen_<namespace>_<module>of the library, dots made_: the moduleexportModuleexports asmyapp_hello. Withnamespace = ""the module isrequire('hello'), exported ashello.- A C function is named
<module>.<function>: Tarantool takes the module from the name up to its last dot,myapp.hello, and the function from the rest,add, whichexportProcexports.
The archive of tt package pack carries the module and the program, built
for the machine it is packed on, and the instances of an installed version
load and run them as in the project.
The toolchain¶
zig fetches the dependencies of build.zig.zon itself, as it builds, into
its global cache, and zig 0.17 into _build/component/<component>/zig-pkg/
from there: tt package fetch does not run the build, and
tt package build --locked keeps the lock of tt, not zig off the network.
The hashes of build.zig.zon pin what zig fetches. The module links
against the C library of the machine it is built on: build it on the
oldest system it runs on.