yandex-writeups/4.2/1.md

ОР - Умеет собирать статические и динамические библиотеки из Rust кода, и экспортировать функции из них. А также проверять экспортируемые символы с помощью системных утилит (например, nm).
ОР - Умеет описывать Си ABI в Rust коде. (с точки зрения best practice)
ОР - Умеет линковать Си библиотеки к Rust коду (статически, динамически и в рантайме - все три варианта)
ОР - Понимает, как использовать Rust библиотеку в других языках (например, в python) и понимает, для чего это может быть полезно.
ОР - Умеет использовать bindgen и cc для генерации Rust API из Си header файлов и сборки Си библиотеки (https://github.com/DaveGamble/cJSON).

• Умеет собирать статические и динамические библиотеки из Rust кода, и экспортировать функции из них. А также проверять экспортируемые символы с помощью системных утилит (например, nm).

• Умеет описывать Си ABI в Rust коде. (с точки зрения best practice)

• Умеет линковать Си библиотеки к Rust коду (статически, динамически и в рантайме - все три варианта)

• Понимает, как использовать Rust библиотеку в других языках (например, в python) и понимает, для чего это может быть полезно.

• Умеет использовать bindgen и cc для генерации Rust API из Си header файлов и сборки Си библиотеки (https://github.com/DaveGamble/cJSON).

  • Умеет импользовать bindgen и cc для генерации Rust API из Си header файлов
  • Практика: сборка Си библиотеки (https://github.com/DaveGamble/cJSON).

• Прописать ОРы для глав ✅ 2025-11-17

• Придумать квизы ✅ 2025-11-17

старт

• Сначала практически расписать бест практис с с аби,
• потом рассказать про биндген
• потом сс
• потом линковка
• ??а если мы захотим уже раст использовать как бблиотеку в другом языке?
• рассказать низкоуровнево как прописывать экспорт раст кода
• (упомянуть про как посмотреть экспорт)
• в том числе и про разные способы линковки
• потом показать на примере линковки к питону
• потом рассказать про бест практис (возможно решив какую-нибудь проблему в предыдущей главе)

C ABI Best practice

• Рассказать немного про бест практис, протом перейти к bindgen
• best practice:
• use std::ffi types
• use *-sys
• Добавление поля links в Cargo.toml крейта *-sys
• use bindgen
• генерация с build.rs (build dependencies)
• Option nonnull for c abi (null optimization) ?cstr

Линковка

Рассказать про то, как низкоуровнево линкуется при помощи rustc, потом рассказать про то, как линковать с build.rs и потом cc

Start

В прошлом уроке вы узнали, как описывается C ABI в Rust. Давайте теперь посмотрим, как используется C ABI в production коде. Для этого изучим best practice использования C ABI.

Правильное использование C ABI

ОР - Умеет описывать Си ABI в Rust коде. (с точки зрения best practice)

Совместимость начинается со стандартов

Допустим, у нас есть такая волшебная функция на С:

int square(int x) {
	return x * x;
}

Как описать эту функцию в Rust? Возможно так?

unsafe extern "C" {
	fn square(x: i32) -> i32;
}

Но тут возникает проблема: в rust явно указана размерность в 32 бита, в то время как в C, int может быть не только размером 32 бита (к примеру у avr, той самой, которая используется в Arduino, размер int 16 бит). Для таких исключений есть модуль core::ffi (который реэкспортирован как std::ffi, так что его можно встретить с импортом по этому пути, но рекомендуется использовать именно по пути core от для поддержки {{no_std}}[https://docs.rust-embedded.org/book/intro/no-std.html] среды). И для описания функций рекомендуется использовать именно эти типы, так как в rust может добавиться поддержка новой архитектуры, со своими типами из C, и программа может незаметно стать памяти-небезопасной. Перепишем функцию:

use core::ffi::c_int;

unsafe extern "C" {
	fn square(x: c_int) -> c_int;
}

Заметка (extern без unsafe): (может быть под тогл/скрываемый блок?) Если читать код библиотек, можно встретить, что extern пишется без unsafe (взаимодействие и смысл этого ключевого слова вы изучите в следующем уроке). Так можно было делать раньше, но в rust это стало обязательным с версии 1.85. Идея заключается в том, что пишущий код человек может задекларировать функцию неправильно, и это обязанность программиста, а не компилятора соблюсти здесь безопасность по памяти (пример такой ситуации вы только что разобрали).

Optional pointer (null optimization) - нужно ли?

Отделение взаимодействия с ffi в отдельный крейт

Если вы пишете библиотеку, взаимодействующую с C ABI, отделяйте это взаимодействие в отдельный крейт (который обычно называют *-sys). На это есть несколько веских {{причин}}[https://doc.rust-lang.org/cargo/reference/build-scripts.html#-sys-packages]:

• Несколько разных библиотек могут переиспользовать уже написанный код для взаимод
• ействия с библиотекой
• Так, одна и та же библиотека не будет собираться несколько раз и не будет слинкована несколько раз (то есть не будет существовать несколько разных или одинаковых версий библиотеки в бинаре)
• Легкость изменения библиотеки, от которой зависит бинарь (версии, поиска ее пути и всей остальной конфигурации)

Квиз - множественный выбор Зачем отделять FFI-взаимодействие в отдельный *-sys крейт?

Чтобы ускорить выполнение сборки программы с нуля. Нет. Это не ускорит сборку конченой программы. Но, будет полезно, если разрабатываете библиотеку, ведь при каждом изменении не будет выполнятся build скрипт с линковкой.

Чтобы ускорить выполнение программы во время рантайма. Нет, отделение логики не ускорит программу.

Чтобы переиспользовать взаимодействие с библиотекой.
Правильно, при отделении логики в -sys крейт, ее смогут переиспользовать другие крейты. Так же, как и при отделении логики в фукнцию, которую можно использовать в другом месте кода

Чтобы не собирать статическую библиотеку несколько раз. Правильно, при переиспользовании -sys крейта статические библиотеки, которые собираются из исходного кода, будут собраны и включены в бинарь только один раз, вместо сборки в каждом использующем библиотеку крейте

Чтобы было проще обновлять или перенастраивать зависимую C-библиотеку (версия, путь, параметры сборки). Правильно, программист сможет изменить используемую библиотеку через аттрибут {{target.<triple>.<links>}}[https://doc.rust-lang.org/cargo/reference/config.html#targettriplelinks] в файле настроек cargo (./cargo/config.toml)

Чтобы избежать необходимости писать unsafe-код в основном проекте. Нет. Хоть и часть unsafe логики отделяется в этот крейт (а именно декларация функций), взаимодействие с этими функциями все еще будет не безопасным

Добавление поля links в Cargo.toml крейта *-sys

При написании крейта, который линкуется с одной библиотекой, используйте {{links}}[https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key] в манифесте Cargo.toml, для указания, с какой библиотекой происходит линковка:

# Cargo.toml
[package]
links = "mylib"

Благодаря этому, программисты, в коде которых будет использоваться такой крейт, смогут {{перезаписать использование build скрипта}}[https://doc.rust-lang.org/cargo/reference/build-scripts.html#overriding-build-scripts], благодаря чему мы и получим третий плюс из предыдущего пункта

Автоматическая генерация extern внешних функций

ОР - Умеет использовать bindgen и cc для генерации Rust API из Си header файлов и сборки Си библиотеки (https://github.com/DaveGamble/cJSON). С обновлением версий библиотек, меняется и их интерфейс. К примеру, могут добавиться новые функции. Но поддерживать актуальные декларации внешних функций (так называемые {{байндинги}}[на английском термин binding, исходит от to bind, который переводится как связывать. говорит компилятору языка, что у нас существует такая функция, а линкеру объясняет, с какой функцией надо связывать]) вручную весьма трудозатратная задача (как и в принципе изначальное написание таких байндингов вручную). На помощь приходит автоматическая генерация при помощи крейта {{bindgen}}[https://github.com/rust-lang/rust-bindgen]. Одним из вариантов использования bindgen является его cli. Установите его:

cargo install bindgen-cli

Создайте новый проект, запишите следующее в файлы:

// src/main.rs
include!("./bindgen.rs");

fn main() {
    println!("Squared eleven: {}", unsafe { square(11) });
}

// src/mylib.c
int square(int x) {
    return x * x;
}

// src/mylib.h
int square(int x);

теперь используем bindgen для генерации байндингов:

bindgen src/mylib.h -o src/bindgen.rs

можете посмотреть в файл src/bindgen.rs, и увидеть там аналогичную декларацию функции, что вы писали, но сгенерированную автоматически :) Теперь соберем C библиотеку:

clang -c src/mylib.c -o mylib.o

Вместо clang можно использовать и gcc (и, теоретически, любой другой C компилятор), но так как rust зависит от инфраструктуры llvm, все примеры будут именно для clang И соберем и запустим программу:

RUSTFLAGS="-L. -l./mylib.o" cargo run

Переменная среды RUSTFLAGS позволяет добавить флаги, которые будут переданы rustc. В данном случае переданы флаги, которые говорят включить в сборку вашу библиотеку. То, как обычно это делается (через скрипт сборки и через cc) будет разобрано чуть позже в этом уроке.

Ваша программа успешно запустилась и выдала ожидаемый результат:

Squared eleven: 121

Автоматизация сборки

ОР - Умеет линковать Си библиотеки к Rust коду (статически, динамически и в рантайме - все три варианта)
Для того, чтобы не делать все это вручную, в cargo есть возможность написать свой скрипт сборщика, который выполнит нужные нам действия перед компиляцией и передаст cargo инструкции для компиляции кода. Обычно такой код расположен в файле build.rs (но путь к нему можно изменить через атрибут {{build}}[https://doc.rust-lang.org/cargo/reference/manifest.html#the-build-field] в Cargo.toml). Давайте сделаем то же самое, но используя build.rs. Для начала, подчистим выхлоп предыдущего эксперимента:

rm src/bindgen.rs # но пока оставим mylib.o

Теперь напишем build.rs (в корне проекта):

// build.rs
use bindgen;
use std::{env, path::PathBuf};

fn main() {
    let bindings = bindgen::builder()
        // Файл, для которого создаются байндинги
        .header("src/mylib.h")
        // Перезапуск сборки при изменении переданных файлов
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        // Сгенерировать байндинги
        .generate()
        .expect("Unable to generate bindings");

    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        // Записать получившиеся байндинги в файл OUT_DIR/bindgen.rs
        .write_to_file(out_path.join("bindgen.rs"))
        .expect("Couldn't write bindings!");

    // Передать линкеру, что библиотеки нужно искать в нынешней папке
    // Аналогичен флагу -L.
    // Информация в cargo передается через stdout
    println!("cargo::rustc-link-search=.");
    // Передать линкеру, что нужно слинковать с библиотекой ./mylib.o
    // Аналогичен флагу -l./mylib.o
    println!("cargo::rustc-link-lib=./mylib.o");
}

Как вы тут заметили, вместо вызова cli тут используется вызов крейта bindgen. Это рекомендуемый способ использования bindgen, и cli на практике используется редко. Чтобы иметь возможность использовать его в сборочном скрипте, добавьте его в зависимости для сборки:

cargo add bindgen --build

Так же, вместо выхлопа bindgen.rs в папку src/ выходной файл будет находиться внутри папки {{OUT_DIR}}[https://doc.rust-lang.org/cargo/reference/environment-variables.html#:~:text=.exe.-,OUT_DIR,-%E2%80%94%20If%20the%20package]. Это именно та папка, куда build.rs должен ложить все свои выходные файлы. Ни в коем случае не надо ложить файлы в src! Так как выходные файлы не являются сами по себе частью проекта, и являются промежуточным результатом компиляции, то и находится они должны в одной из подпапок target, а именно в OUT_DIR. Так как путь к bindgen.rs изменился, замените предыдущий include! в src/main.rs на такой:

include!(concat!(env!("OUT_DIR"), "/bindgen.rs"));

Попробуем запустить все это:

cargo run

Байндинги автоматически были созданы и линковка тоже произошла, осталось добавить сборку C кода в библиотеку.

Сброка C кода в Rust

ОР - Умеет использовать bindgen и cc для генерации Rust API из Си header файлов и сборки Си библиотеки (https://github.com/DaveGamble/cJSON). Так же, как и для генерации байндингов существует bindgen, для компиляции библиотек существует крейтcc. Фактически, он под капотом вызывает компилятор C со всеми задаными флагами. Добавим его в зависимости для сборки:

cargo add cc --build

И обновим build.rs:

// build.rs
use bindgen;
use cc;
use std::{env, path::PathBuf};

fn main() {
    let bindings = bindgen::builder()
        // Файл, для которого создаются байндинги
        .header("src/mylib.h")
        // Перезапуск сборки при изменении переданных файлов
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        // Сгенерировать байндинги
        .generate()
        .expect("Unable to generate bindings");

    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        // Записать получившиеся байндинги в файл OUT_DIR/bindgen.rs
        .write_to_file(out_path.join("bindgen.rs"))
        .expect("Couldn't write bindings!");

    cc::Build::new()
        // добавить src/mylib.c в выходную библиотеку
        .file("src/mylib.c")
        // скомпилировать C код как библиотеку libmylib.a в папке OUT_DIR 
        .compile("mylib");
}

Заметьте, что пропало явное обозначение, что нужно слинковать с библиотекой. cc сам передаст cargo название библиотеки, с которой нужно слинковать. Перед запуском, для чистоты эксперимента, удалите старый файл:

rm mylib.o

Теперь сборку и запуск можно делать просто через cargo run, не выполняя лишних команд.

Линковка с динамической библиотекой

До этого мы собирали только со статической библиотекой. Теперь, давайте слинкуем с динамической библиотекой. Для этого, сначала соберем ее:

clang src/mylib.c -shared -o libmylib.so

А теперь, в build.rs уберите использование cc и добавьте в конце функции main:

fn main() {
	// Генерация байндингов
	// ...
	
    println!("cargo:rustc-link-search=.");
    println!("cargo:rustc-link-lib=dylib=mylib");
}

В cargo:rustc-link-lib передано значение dylib=mylib. Оно позволяет явно указать, что нужно подгрузить динамическую библиотеку (dylib) с название mylib (у такой библиотеки будет название libmylib.so на примере linux). Значение [тип=] опционально и может быть одним из:

• dylib - динамическая библиотека
• static - статическая библиотека
• framework - специфичный формат для MacOS, содержащий динамичекую библиотеку с дополнительными ресурсами cc не поддерживает генерацию динамических библиотек, так как она не будет являться частью создаваемого cargo и rustc бинаря. Динамические библиотеки обычно являются частью системы (те же libc, zlib, openssl, присутствие которых бинари будут ожидать по стандартным путям). Установлены они могут быть, к примеру, через apt, pacman, установщики windows, и так далее. Либо создаются отдельно и поставляются с программой.

Линковка в рантайме

ОР - Умеет линковать Си библиотеки к Rust коду (статически, динамически и в рантайме - все три варианта)
Последний способ линковки в рантайме, позволяет не тратить лишний раз оперативную память, загружая код лишь только тогда, когда он нужен. Для независимости от платформы будем использовать dlopen и dlsym.

• dlopen - подгружает нужную нам библиотеку
• dlsym - ищет в библиотеке нужный символ и выдает его адрес, и это может быть не только функция, но и, к примеру, константа, статическая переменая, и тд. Для начала, удалите build.rs. Добавьте libc как зависимость. Напишите в src/main.rs:

// src/main.rs
use libc::{dlopen, dlsym};
use std::ffi::c_int;

fn main() {
    let mylib = unsafe { dlopen(c"./libmylib.so".as_ptr(), 0) };
    let square: extern "C" fn(c_int) -> c_int =
        unsafe { std::mem::transmute(dlsym(mylib, c"square".as_ptr())) };
    println!("Squared eleven: {}", unsafe { square(11) });
}

Запустив это, получите ровно тот же результат, что и раньше, но теперь библиотеку мы подгружаем сами. Кстати, линкер для динамических библиотек делает то же самое, но подгружает библиотеки еще до вызова main, а адреса функций кладет в заранее заготовленную таблицу функций.

Практика

Создайте новый проект, с таким содержимым в src/main.rs:

include!(concat!(env!("OUT_DIR"), "/bindgen.rs"));

use std::ffi::{CStr, CString};

const TEST_JSON: &CStr = c"{
    \"meaning_of_life\": 42
}";

fn main() {
    let json: *mut cJSON = unsafe { cJSON_Parse(TEST_JSON.as_ptr()) };

    let json_str = unsafe { cJSON_PrintUnformatted(json) };
    let json_str = unsafe { CString::from_raw(json_str) };
    let json_str = json_str.to_str().unwrap();
    assert_eq!(json_str, r#"{"meaning_of_life":42}"#);

    let meaning_of_life = unsafe { cJSON_GetObjectItem(json, c"meaning_of_life".as_ptr()) };
    let meaning_of_life = unsafe { cJSON_GetNumberValue(meaning_of_life) };
    println!("Meaning of life: {}", meaning_of_life);
    assert_eq!(meaning_of_life, 42f64);
}

Создайте такой build.rs, чтобы этот код заработал. Используйте библиотеку cJSON, ее можно склонировать прямо в корень проекта. Подсказки: Экспорт функций можно сгенерировать от cJSON.h используя bindgen Чтобы была возможность использовать код из cJSON, соберите библиотеку через cc Байндинги записываются в bindgen.rs в папке, указанной в переменной среды OUT_DIR Чек-лист: Линкуется cJSON как статическая библиотека Файл bindgen.rs с байндингами находится в папке, указанной в переменной среды OUT_DIR Тесты проходят Решение:

use bindgen;
use cc;
use std::{env, path::PathBuf};

fn main() {
    let bindings = bindgen::builder()
        .header("cJSON/cJSON.h")
        .generate()
        .expect("Unable to generate bindings");

    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out_path.join("bindgen.rs"))
        .expect("Couldn't write bindings!");

    cc::Build::new()
        // добавить src/mylib.c в выходную библиотеку
        .file("cJSON/cJSON.c")
        // скомпилировать C код как библиотеку libmylib.a в папке OUT_DIR
        .compile("cJSON");
}

Rust как библиотека

ОР - Умеет собирать статические и динамические библиотеки из Rust кода, и экспортировать функции из них. А также проверять экспортируемые символы с помощью системных утилит (например, nm).
ОР - Понимает, как использовать Rust библиотеку в других языках (например, в python) и понимает, для чего это может быть полезно.
В течении всего урока мы использовали C код из Rust кода. А что если нужно будет использовать rust код из других языков, к примеру, того же C, Go, или Python? И это тоже возможно, через тот же C ABI, но на экспорт. Такая функция декларируется так:

#[unsafe(no_mangle)]
pub extern "C" fn doublefast(x: u32) -> u32 {
    x << 1
}

• no_mangle - говорит rust, что название функции не надо преобразовывать
• extern "C" - использовать C ABI
• pub extern - экспорт функции Создайте новый проект как библиотеку:

cargo new --lib mylib

В Cargo.toml добавьте:

[lib]
crate-type = ["cdylib"] # cdylib означает, что нужно собрать динамическую библиотеку

А в src/lib.rs внесите показанный ранее код:

#[unsafe(no_mangle)]
pub extern "C" fn doublefast(x: u32) -> u32 {
    x << 1
}

Соберите библиотеку. Выходным файлом получится target/debug/libmylib.so (В зависимости от вашей ОС расширение .so, используемое в linux, может замениться на .dylib в macos или .dll в windows). Можем проверить наличие символа в библиотеке для функции через nm из пакета binutils:

# nm выведет весь список символов
# grep покажет только doublefast, если он есть
nm target/debug/libmylib.so | grep doublefast

Попробуем использовать нашу функцию, к примеру, такой код в Python:

from ctypes import cdll
mylib = cdll.LoadLibrary("target/debug/libmylib.dylib")
print(mylib.doublefast(8))

Успешно выведет 16 Информация о том, какие типы функция принимает и выдает не сохраняется в библиотеке, просто по дефолту python считает, что функция принимает и выдает i32 Такое применение имеет практическую пользу: аналогичный код на rust выполняется в разы быстрее, чем код на python, поэтому много библиотек для python пишутся на C, а со становления rust популяным многие уже пишутся на rust.

Сборка статической библиотеки

Что собрать то же самое, но в статическую библиотеку, нужно в crate-type изменить cdylib на staticlib (либо можно оставить и то и то, тогда будут собираться обе версии библиотеки):

[lib]
crate-type = ["staticlib"]
# или можно сделать такой вариант, тогда соберется
# два файла с разными расширениями
# crate-type = ["cdylib", "staticlib"]

Попробуем использовать статическую библиотеку, но теперь пример для C:

// main.c
#include <stdint.h>
#include <stdio.h>

uint32_t doublefast(uint32_t);

int main() {
    printf("Double six: %d\n", doublefast(6));
}

Соберем C код с использованием нашей библиотеки:

clang main.c target/debug/libmylib.a -o ./a.exe

При запуске ./a.exe будет получен ожидаемый результат. Для crate-type возможны следующие значения:

• staticlib - сборка статической библиотеки
• dylib - сборка динамической библиотеки, предназначенной для использования в rust коде. Собираться использующий код и dylib должны одной и той же версией компилятора, так как у dylib нет стабильного интерфейса
• cdylib - сборка динамической библиотеки, но предназначеную для использования во всех языках, поэтому отличается от dylib:
  • интерфейсы фукнций следуют c abi
  • в библиотеку будет включена стандартная rust библиотека (rust-std)
• bin - сборка конечной программ
• lib - соберет библиотеку, вид которой будет выбран компилятором (стандартное значение для крейтов-библиотек)
• rlib - внутренний тип библиотек rust
• proc-macro - крейт, в котором экспортированы proc макросы

Квиз - одиночный выбор Какое значение нужно указать в crate-type, чтобы использовать ваш rust код как динамическую библитеку в проекте на Go? lib Нет, lib соберет библиотеку на выбор компилятора

cdylib Правильно, cdylib соберет динамическую библиотеку с C ABI, который подходит для Go

dylib Нет, хоть dylib и соберет динамическую библиотеку, но полноценно подходить она будет только для rust кода

staticlib Нет, staticlib соберет статическую библиотеку

// update

cbindgen

Так же, как и для генерации rust байндингов из C есть библитека bindgen, для генерации C/C++/cython байндингов из rust кода есть cbindgen:

cargo install cbindgen

Итоги

В этом уроке мы на практике разобрали, как взаимодействовать с кодом на C в проектах на rust, best practice этого взаимодействия, а так же узнали, как можно взаимодействовать с кодом на rust из других языков. Вы научились автоматически генерировать декларации внешних функций, а так же собирать статические библиотеки при сборке проекта на rust. Далее вы узнаете, что означает ключевое слово unsafe, зачем оно нужно при взаимодействии с внешними библиотеками, а так же изучите best practice при написании unsafe кода.