/wolfram-library-link-rs

Safe, efficient, and ergonomic bindings to Wolfram LibraryLink and the Wolfram Language

Primary LanguageRustApache License 2.0Apache-2.0

wolfram-library-link

Crates.io License Documentation

API Documentation | Changelog | Contributing

Bindings to the Wolfram LibraryLink interface, making it possible to call Rust code from the Wolfram Language.

This library is used for writing Rust programs that can be loaded by the Wolfram LibraryLink family of functions, specifically by LibraryFunctionLoad[].

Features

  • Efficiently call Rust functions from Wolfram code.
  • Pass arbitrary Wolfram expressions to and from Rust code.
  • Evaluate Wolfram expressions from Rust code.
  • Respond to Wolfram abort requests while in Rust code.
  • Safe API for the Wolfram Symbolic Transfer Protocol, using the wstp crate.

Follow the Quick Start guide to begin using wolfram-library-link.

See Why Rust? for an overview of some of the advantages Rust has when writing native code for use from the Wolfram Language: performance, memory and thread safety, high-level features, and more.

Quick Examples

The examples in this section are written with two back-to-back code blocks. The first shows the Rust code, and the second shows the Wolfram Language code needed to load and use the related Rust function(s).

Basic data types

use wolfram_library_link::export;

#[export]
fn square(x: i64) -> i64 {
    x * x
}
square = LibraryFunctionLoad["...", "square", {Integer}, Integer];

square[5]

See also: LibraryFunctionLoad

Efficient numeric arrays

Create an array of a million integers in Wolfram Language and compute the total using Rust:

use wolfram_library_link::{export, NumericArray};

#[export]
fn total(array: &NumericArray<i64>) -> i64 {
    array.as_slice().into_iter().sum()
}
total = LibraryFunctionLoad[
    "...",
    "square",
    {LibraryDataType[NumericArray, "Integer64"]},
    Integer
];

total[NumericArray[Range[1000000], "Integer64"]]

See also: NumericArray, LibraryDataType

Example Programs

The wolfram-library-link/examples subdirectory contains sample programs demonstrating features of the wolfram-library-link API.

Rust code Wolfram Language code Demonstrates ...
basic_types.rs BasicTypes.wlt how to write Rust LibraryLink functions utilizing the basic, native types that can be passed efficiently, like integers, floating-point real numbers, and strings.
numeric_arrays.rs NumericArrays.wlt how the NumericArray data type can be used to efficiently pass large multi-dimensional arrays of uniform numeric data.
wstp.rs WSTP.wlt how WSTP Links can be used to pass arbitrary expressions to and from LibraryLink functions.
aborts.rs Aborts.wlt how Rust code can respond to Wolfram abort requests.
async_file_watcher.rs AsyncExamples.wlt how Rust code can generate asynchronous events that trigger Wolfram evaluations to process the event.
managed.rs ManagedExpressions.wlt how the managed expression API can be used to free library data when a Wolfram expression is deallocated.
data_store.rs DataStore.wlt how the DataStore data type can be used to efficiently pass arbitrary expression-like heterogenous structures made up of native LibraryLink data types.

Raw functions

These examples demonstrate how to write functions that use the "raw" low-level LibraryLink and WSTP interfaces, using the extern "C" ABI, the low-level MArgument and WSLINK types, and manual WSTP operations.

Rust code Wolfram Language code
raw_librarylink_function.rs and raw_wstp_function.rs RawFunctions.wlt

Additional examples

In addition to the polished high-level examples, the wolfram-library-link/examples/tests/ directory contains test code for a more exhaustive range of functionality and behavior, and may be a useful additional reference. The RustLink/Tests/ directory contains the Wolfram Language unit testing logic that loads and calls the test functions.

Building wolfram-library-link

wolfram-library-link depends on the wstp crate for bindings to the Wolfram Symbolic Transfer Protocol (WSTP). Building the wstp crate requires access to the WSTP SDK, which provides the WSTP static library. wstp uses wolfram-app-discovery to locate a local installation of the Wolfram Language that contains a suitable copy of the WSTP SDK. If the WSTP SDK cannot be located, wstp will fail to build, and consequently, so will wolfram-library-link.

If you have installed the Wolfram Language to a location unknown to wolfram-app-discovery, you may specify the installed location manually by setting the WOLFRAM_APP_DIRECTORY environment variable. See Configuring wolfram-app-discovery for details.

Related Links

Related crates

  • wstp — bindings to the Wolfram Symbolic Transfer Protocol, used for passing arbitrary Wolfram expressions between programs.
  • wolfram-expr — native Rust representation of Wolfram Language expressions.
  • wolfram-app-discovery — utility for locating local installations of Wolfram applications and the Wolfram Language.

Related documentation

License

Licensed under either of

at your option.

Note: Licensing of the WSTP library linked by the wstp crate is covered by the terms of the MathLink License Agreement.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md for more information.

Developer Notes

See Development.md for instructions on how to perform common development tasks when contributing to the wolfram-library-link crate.

See Maintenance.md for instructions on how to keep wolfram-library-link up to date as new versions of the Wolfram Language are released.