Сборка модуля на Rust¶
Компонент, собранный с помощью cargo, создаёт нативный модуль Tarantool:
библиотеку Rust-пакета, которую код приложения загружает через require
и которая содержит C-функции для box.schema.func.create. Тот же
компонент может создавать и программу пакета.
API Tarantool предоставляет
крейт tarantool.
Backend cargo входит в стандартный модуль build tt, который есть в
официальном tt и в любом дистрибутиве со стандартными модулями:
команда tt version --modules выводит build, если он присутствует в tt.
Создание крейта¶
В libs/fastrs/ пакета с именем myapp, файл Cargo.toml:
[package]
name = "fastrs"
version = "0.1.0"
edition = "2021"
[dependencies]
tarantool = "11"
и src/lib.rs с C-функцией add и Lua-модулем из одной функции mul:
use std::os::raw::c_int;
use tarantool::proc;
use tarantool::tlua::ffi;
#[proc]
fn add(a: i64, b: i64) -> i64 {
a + b
}
unsafe extern "C-unwind" fn mul(l: *mut ffi::lua_State) -> c_int {
let product = ffi::lua_tointeger(l, 1) * ffi::lua_tointeger(l, 2);
ffi::lua_pushinteger(l, product);
1
}
/// require('myapp.fastrs')
#[no_mangle]
pub unsafe extern "C" fn luaopen_myapp_fastrs(l: *mut ffi::lua_State) -> c_int {
ffi::lua_createtable(l, 0, 1);
ffi::lua_pushcclosure(l, mul, 0);
ffi::lua_setfield(l, -2, c"mul".as_ptr());
1
}
Задавать crate-type в крейте не требуется: tt в любом случае собирает
из него cdylib.
Объявление компонента¶
[components.fastrs]
path = "libs/fastrs"
[components.fastrs.build]
backend = "cargo"
$ tt package build
$ find .rocks -name 'fastrs*'
.rocks/lib/tarantool/myapp/fastrs.so
Сборка запускает cargo rustc --lib --crate-type cdylib --profile release
в каталоге компонента, с _build/cargo/ проекта в качестве целевого каталога,
и берёт библиотеку из того, о чём сообщает cargo. Модуль называется по имени
библиотеки, fastrs; module = "..." задаёт другое имя. Это файл
<module>.so, а на macOS - <module>.dylib, где Tarantool ищет именно
такое имя, и библиотека линкуется там с -undefined dynamic_lookup:
символы Tarantool разрешаются при загрузке библиотеки в Tarantool, как и
для модулей на C. package выбирает пакет в workspace'е, features - его
фичи, а profile - профиль сборки, отличный от release.
Каталог target/ компонента, который оставляет cargo, запущенный там
вручную, не раскладывается в дерево пакета: библиотека и процедурные
макросы в нём не являются файлами пакета. Файл *.lua компонента
раскладывается так же, как и в любом компоненте.
Модуль и программа из одного крейта¶
Пакет может содержать как библиотеку, так и бинарный файл: CLI модуля или
процесс, который приложение запускает рядом с Tarantool. Один компонент
собирает и то, и другое, если в его блоке указаны оба. При наличии секции
[[bin]] в Cargo.toml:
[[bin]]
name = "fastrs-cli"
path = "src/main.rs"
и src/main.rs:
fn main() {
println!("6 * 7 = {}", 6 * 7);
}
блок указывает модуль и бинарный файл:
[components.fastrs.build]
backend = "cargo"
module = "fastrs"
bin = "fastrs-cli"
$ tt package build
$ find .rocks/bin .rocks/lib -name 'fastrs*'
.rocks/bin/fastrs-cli
.rocks/lib/tarantool/myapp/fastrs.so
$ .rocks/bin/fastrs-cli
6 * 7 = 42
Сборка сначала выполняет cargo rustc --lib для модуля, затем
cargo build --bin fastrs-cli и копирует бинарный файл в .rocks/bin/,
где его находит описание экземпляра {binary: fastrs-cli}; см.
Запуск внешнего процесса. Одно лишь поле module
собирает только модуль, одно лишь bin - только программу, а блок без
обоих собирает библиотеку под её собственным именем, как описано выше.
При static = true бинарный файл собирается под musl и не требует
разделяемых библиотек, а модуль собирается как обычно.
Вызов модуля¶
local fastrs = require('myapp.fastrs')
assert(fastrs.mul(6, 7) == 42)
box.schema.func.create('myapp.fastrs.add', {language = 'C', if_not_exists = true})
assert(box.func['myapp.fastrs.add']:call({20, 22}) == 42)
require('<namespace>.<module>')вызывает функциюluaopen_<namespace>_<module>библиотеки, в которой точки заменены на_, а часть имени до первого-отброшена:require('my-app.fastrs')для пакета с именемmy-appвызываетluaopen_app_fastrs. Приnamespace = ""модуль подключается черезrequire('fastrs'), а функция называетсяluaopen_fastrs.- C-функция называется
<module>.<function>: Tarantool берёт имя модуля из части до последней точки,myapp.fastrs, а функцию - из оставшейся части,add, которую экспортирует#[proc].
Архив tt package pack содержит модуль, собранный для той машины, на которой
выполнялась упаковка, и экземпляры установленной версии загружают его точно так
же, как и в проекте.
Тулчейн¶
cargo и rustc устанавливаются самостоятельно с помощью
rustup: tt не устанавливает ни тот, ни другой инструмент
и ищет cargo в PATH. Крейту tarantool требуется rustc версии 1.67.1 или
новее. Модуль линкуется с библиотекой C той машины, на которой он собирается:
собирать его следует на самой старой системе из тех, где он будет запускаться.