jlrs

jlrs 是一个提供对 Julia C API 访问权限的 crate。它可以用来在 Rust 应用程序中嵌入 Julia，并编写可以被 Julia 使用的互操作库。

支持 Julia 版本 1.6 一直到 1.11，但只有 LTS 和稳定版本被积极测试。强烈建议使用当前稳定版本的 Julia。目前最低支持的 Rust 版本是 1.77。

此说明仅包含关于 jlrs 支持的功能、必须满足的先决条件和如何满足它们的信息。有关如何使用 jlrs 的信息和示例，请参阅 文档。该文档假设您已经熟悉 Julia 和 Rust 编程语言。

概述

jlrs 当前支持的功能不完全列表

• 访问任意 Julia 模块及其内容。
• 调用 Julia 函数，包括接受关键字参数的函数。
• 处理异常或将它们转换为错误消息，可选地带有颜色。
• 包含并调用您的 Julia 代码。
• 使用自定义系统映像。
• 从 Rust 创建 Julia 可以使用的值，并将它们转换回 Rust。
• 访问此类值的类型信息和字段。内联和位联合字段可以直接访问。
• 创建和使用 n 维数组。可以启用 jlrs-ndarray 功能以与 ndarray 集成。
• 将 Julia 结构体映射到 Rust 结构体，Rust 实现可以使用 JlrsCore 包生成。
• 可以映射到 Rust 的结构体包括具有类型参数和位联合的结构体。
• 直接或通过 Julia 感知的线程池使用多个线程。
• 使用 julia_module 宏将 Rust 类型、方法和函数导出到 Julia。
• 使用 julia_module 的库可以使用 BinaryBuilder 编译，并以 JLL 的形式分发。

先决条件

在使用jlrs之前，必须先安装Julia，jlrs与Julia 1.6及更高版本兼容，包括1.11。如果未安装JlrsCore包，则在默认情况下初始化jlrs时会自动安装。jlrs在Linux和macOS上尚未与juliaup进行测试。

Linux

安装Julia的推荐方法是下载官方网站上的二进制文件，这些文件以包含名为julia-x.y.z的目录的存档形式分发。此目录包含多个其他目录，包括一个包含julia可执行文件的bin目录。

在编译过程中，通常通过执行which julia命令自动检测头文件和库的路径。julia.h的路径必须是$(which julia)/../include/julia/julia.h，而库的路径必须是$(which julia)/../lib/libjulia.so。如果您想覆盖此默认行为，则必须将JULIA_DIR环境变量设置为适当的julia.x-y-z目录的路径，在这种情况下使用$JULIA_DIR/include/julia/julia.h和$JULIA_DIR/lib/libjulia.so。

为了能够加载libjulia.so，此文件必须在库搜索路径上。如果不是这种情况，您必须将/path/to/julia-x.y.z/lib添加到LD_LIBRARY_PATH环境变量中。

macOS

遵循Linux的说明，但将LD_LIBRARY_PATH替换为DYLD_LIBRARY_PATH。

Windows

可以使用juliaup、安装程序或从官方网站下载的便携式安装程序来安装Julia。在前一种情况下，Julia很可能已安装在%USERPROFILE%\.julia\juliaup\julia-x.y.z+0~x64，而使用安装程序或提取操作允许您选择目标位置。安装或提取后，将存在一个名为Julia-x.y.z的文件夹，其中包含多个文件夹，包括一个包含julia.exe的bin文件夹。必须将bin文件夹的路径添加到Path环境变量中。

通过执行where julia命令自动检测Julia。如果返回多个位置，则使用第一个。可以通过设置JULIA_DIR环境变量来覆盖默认设置。但这与juliaup不兼容，在这种情况下必须设置环境变量。

特性

jlrs的大多数功能仅在启用适当的功能时才可用。这些功能通常属于以下三个类别之一：版本、运行时和实用程序。

版本

Julia C API是不稳定的，并且Julia的不同版本之间存在一些不兼容性。为确保使用特定版本的Julia的正确绑定，必须启用版本功能。以下是目前存在的版本功能

• julia-1-6
• julia-1-7
• julia-1-8
• julia-1-9
• julia-1-10
• julia-1-11

必须启用恰好一个版本功能。否则，jlrs将无法编译。

如果您希望您的箱子与多个版本的 Julia 兼容，您应该按照以下方式“重新导出”这些版本功能

[features]
julia-1-6 = ["jlrs/julia-1-6"]
julia-1-7 = ["jlrs/julia-1-7"]
julia-1-8 = ["jlrs/julia-1-8"]
julia-1-9 = ["jlrs/julia-1-9"]
julia-1-10 = ["jlrs/julia-1-10"]
julia-1-11 = ["jlrs/julia-1-11"]

运行时

运行时允许从 Rust 应用程序初始化 Julia，以下功能启用运行时

• local-rt

  启用本地运行时。本地运行时提供对 Julia 的单线程、阻塞访问。

• async-rt

  启用异步运行时。异步运行时在单独的线程上运行，可以从多个线程中使用。

• tokio-rt

  异步运行时需要执行器。此功能提供基于 tokio 的执行器。

• multi-rt

  启用多线程运行时。多线程运行时允许您从任意线程调用 Julia。它可以与 async-rt 功能结合使用，以创建 Julia 感知线程池。此功能需要 Julia 1.9 或更高版本。

警告：运行时功能必须仅由嵌入 Julia 的应用程序启用。库绝对不能启用运行时功能。

警告：当 Linux 上启用运行时功能时，如果您希望代码运行更快，请设置 RUSTFLAGS="-Clink-args=-rdynamic"。

工具

所有其他功能称为实用功能。以下功能可用

• async

  启用异步运行时不依赖执行器的功能。这可以用于提供异步运行时可以处理的任务实现的库。

• jlrs-derive

  应将此功能与 JlrsCore 包中 Reflect 模块提供的代码生成结合使用。此模块允许您生成 Julia 结构的 Rust 实现，此生成的代码使用此功能提供的自定义 derive 宏，以实现从 Julia 到 Rust 以及在某些情况下从 Rust 到 Julia 的安全转换。

• jlrs-ndarray

  从 ndarray 中将 Julia 数组的内容作为 ArrayView 或 ArrayViewMut 访问。

• f16

  通过使用 half 的 f16 类型支持在 Rust 中处理 Julia 的 Float16 类型。

• complex 通过使用 num 的 Complex 类型支持在 Rust 中处理 Julia 的 Complex 类型。

• ccall

  可以使用 Julia 的 ccall 接口从 Julia 调用 Rust 编写的函数。在这种情况下不能使用运行时，因为 Julia 已经初始化了。当启用此功能时，将提供 CCall 结构，它提供了与本地运行时相同的功能，而无需初始化 Julia。《julia_module》宏提供了一种简单的方法来与 JlrsCore 包中的 Wrap 模块宏一起导出函数、类型和数据。

• lto

  jlrs 依赖于用 C 编写的支持库，如果启用此功能，则支持库将使用跨语言 LTO 的支持构建，这可以提供显著的性能提升。

  此功能仅在 Linux 上进行了测试，并且需要使用与 rustc 的 LLVM 版本相同主版本的 clang 版本构建支持库；例如，rust 1.78.0 使用 LLVM 18.1.2，因此需要 clang-18。您可以通过执行 rustc -vV 检查您需要哪个版本。

  如果启用此功能，您必须设置RUSTFLAGS环境变量，可能还需要设置CC环境变量。设置RUSTFLAGS将覆盖jlrs设置的默认标志，因此您必须设置以下标志：RUSTFLAGS="-Clinker-plugin-lto -Clinker=clang-XX -Clink-arg=-fuse-ld=lld -Clink-args=-rdynamic"。最后一个对于嵌入式开发者尤其重要，忘记它将保证性能受损。

• 诊断

  由于默认的lint无助于解决问题，因此启用为多个特质自定义诊断功能。此功能需要Rust 1.78。

• i686

  在Linux上链接32位Julia构建版本，仅用于交叉编译。

• windows

  在从Linux交叉编译Windows时必须启用的标志。

• debug

  在Linux上链接Julia的调试版本。

• no-link

  不链接Julia。

• yggdrasil

  在通过BinaryBuilder编译时必须启用的标志。

您可以通过启用full功能来启用除debug、i686、windows、no-link和yggdrasil以外的所有功能。如果您不想启用任何运行时，可以使用full-no-rt。