jlrs

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

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

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

概述

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

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

先决条件

在可以使用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将无法编译。

如果您想使您的crate兼容多个版本的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模块提供的代码生成。此模块允许您生成Rust实现的Julia结构体，此生成代码使用此特性提供的自定义 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。