Инструменты

Анатомия проекта

Базовая компоновка проекта, а также общие файлы и папки, используемые cargo.

Минимальные примеры для различных точек входа могут выглядеть следующим образом:

Приложение

// src/main.rs (Точка входа приложения по умолчанию)

fn main() {
    println!("Ржавый код!");
}

Библиотеки

// src/lib.rs (Точка входа в библиотеку по умолчанию)

pub fn f() {}      // Является общедоступным элементом в корне, поэтому он доступен извне.

mod m {
    pub fn g() {}  // Нет общедоступного пути ('m' не общедоступен) от root, поэтому 'g'.
}                  // Крейт недоступен с внешней стороны ящика.

Модульные тесты

// src/my_module.rs (любой файл вашего проекта)

fn f() -> u32 { 0 }

#[cfg(test)]
mod test {
    use super::f;           // Необходимо импортировать элементы из родительского модуля.
						    //  Имеет доступ к непубличным членам.
    #[test]
    fn ff() {
        assert_eq!(f(), 0);
    }
}

Интеграционные тесты

// tests/sample.rs (пример интеграционного теста)
#[test]
fn my_sample() {
    assert_eq!(my_crate::f(), 123); // Интеграционные тесты (и бенчмарки) «зависят» от crate, как 3-я сторона. 
}                                   // Следовательно, они видят только общедоступные элементы.

Тесты производительности

// benches/sample.rs (пример теста производительности)

#![feature(test)]

extern crate test;  // Обычно это не нужно в новых версиях rust

use test::{black_box, Bencher};

#[bench]
fn my_algo(b: &mut Bencher) {
    b.iter(|| black_box(my_crate::f())); // 'black_box' предотвращает оптимизацию 'f'.
}

Построение скриптов

// build.rs (Пример сценария предварительной сборки)

fn main() {
    // Вам нужно полагаться на env.vars, '#[cfg(...)] ' предназначен для хоста.
    let target_os = env::var("CARGO_CFG_TARGET_OS");
}

Макросы

// src/lib.rs (Точка входа по умолчанию для макросов)

extern crate proc_macro;  // Видимо нужно импортировать именно так.

use proc_macro::TokenStream;

#[proc_macro_attribute]   // Крейты теперь могут использовать '#[my_attribute]'
pub fn my_attribute(_attr: TokenStream, item: TokenStream) -> TokenStream {
    item
}

// Cargo.toml

[package]
name = "my_crate"
version = "0.1.0"

[lib]
proc-macro = true

Деревья модулей и импорт:

Деревья модулей

Исходные файлы модулей работают следующим образом:

• Дерево модулей должно быть явно определено, не является неявно построенным из дерева файловой системы.
• Корень дерева модуля равен библиотеке, приложению, … точка входа (например, lib.rs). Фактически определения модулей работают следующим образом:
• mod m {} определяет модуль в файле, в то время как mod m; прочитает m.rs или m/mod.rs.
• Путь к .rs на основе вложенности, например, mod a { mod b { mod c; }}} либо a/b/c.rs, либо a/b/c/mod.rs.
• Файлы не идут из корня дерева модулей через какой-нибудь mod m;, не будет затронут компилятором!

Пространства имен

Rust имеет три типа пространств имен:

struct X; - Вычисляется в типах и в функциях, определяет тип X как константу. struct X(); - Вычисляется в типах и в функциях, определяет тип X как функцию.

• В любой заданной области, например в модуле, может существовать только один элемент на пространство имен, например: — enum X {} и fn X() {} могут сосуществовать. — struct X; и const X не может сосуществовать.
• С использованием my_mod::X; все элементы, называемые ‘X’, будут импортированы. Из-за соглашений об именах (например, fn и mod написаны строчными буквами) и здравого смысла (большинство разработчиков просто не называют все вещи X) вам не придется беспокоиться об этих видах в большинстве случаев. Однако они могут быть фактором при проектировании макросов.

Cargo

Команды и инструменты, которые полезно знать.

cargo build означает, что вы можете написать cargo build, либо просто cargo b, —release можно заменить на -r.

Дополнительные компоненты rust устанавливаются утилитой rustup, добавляет необходимый инструмент.

Большое количество дополнительных cargo плагинов можно найти здесь.

Кросс-компиляция

• Проверка компилируемого объекта поддерживается разными платформами.
• Установка через rustup target install X.
• Установите собственные нативные инструменты (зависит от ОС). Получить от поставщика (Google, Apple, …), может быть доступно не на всех платформах (например, нет инструментов iOS в Windows). Некоторые инструменты требуют дополнительных шагов сборки (например, make-standalone-toolchain.sh Android).
• Обновите ~/.cargo/config.toml следующим образом:

[target.aarch64-linux-android]
linker = "[PATH_TO_TOOLCHAIN]/aarch64-linux-android/bin/aarch64-linux-android-clang"

или

[target.aarch64-linux-android]
linker = "C:/[PATH_TO_TOOLCHAIN]/prebuilt/windows-x86_64/bin/aarch64-linux-android21-clang.cmd"

• Установите переменные среды (необязательно, подождите, пока компилятор пожалуется перед настройкой):

set CC=C:\[PATH_TO_TOOLCHAIN]\prebuilt\windows-x86_64\bin\aarch64-linux-android21-clang.cmd
set CXX=C:\[PATH_TO_TOOLCHAIN]\prebuilt\windows-x86_64\bin\aarch64-linux-android21-clang.cmd
set AR=C:\[PATH_TO_TOOLCHAIN]\prebuilt\windows-x86_64\bin\aarch64-linux-android-ar.exe
…

Установите ли вы их, зависит от того, как компилятор жалуется, не обязательно все необходимы.

Некоторые платформы могут быть чрезвычайно чувствительными к тому, как указаны пути (например, \ против /). Компиляция приложения: cargo build —target=X

Директивы инструментов

Специальные токены, встроенные в исходный код, используются инструментарием или препроцессорной обработки.

Макросы

Внутри декларативного макроса на примере macro_rules! осуществляется:

Документирование

Внутри документа комментируют:

#![globals]

Атрибуты, влияющие на весь трейт или приложение:

C - означает на уровне крейта (обычно указывается как #![ my_attr] в файле верхнего уровня). M - модуля. F - функции. S - статических.

#[code]

Атрибуты, в первую очередь управляющие эмитируемым кодом:

M - модуля. F - функции. S - статических. T - типа. X - означает что-то особенное. * - означает практически любой предмет.

#[quality]

$^1$ Есть некоторые споры, какой из них является лучшим для обеспечения высокого качества крейтов. Активно поддерживаемые крейты для нескольких разработчиков, вероятно, выигрывают от более агрессивного отрицания или запрета линта; менее регулярно обновляемые, вероятно больше от консервативного использования warn (так как будущие обновления компилятора или clippy могут внезапно сломать, в этом случае работающий код будет с незначительными проблемами).

C - означает на уровне крейта (обычно указывается как #![ my_attr] в файле верхнего уровня). M - на уровне модуля. F - на уровне функции. T - на уровне типа. X - означает что-то особенное. * - означает практически любой предмет.

#[macros]

! - макрос. M - на уровнемодуля. F - на уровнефункции. X - означает что-то особенное.

#[cfg]

Атрибуты, управляющие условной компиляцией:

Следует отметить, что опции обычно можно задавать несколько раз, т.е. одна и та же команда может использоваться с несколькими значениями. Можно ожидать, что #[cfg (target_feature = «avx»)] и #[cfg (target_feature = «avx2»)] будут истинными одновременно.

* - означает практически любой предмет.

build.rs

Переменные среды и выходные данные, связанные со сценарием перед построением.

Доступно в build.rs через env::var()?. Список не является исчерпывающим.

Выводится из build.rs через println!(). Список не является исчерпывающим.