12 releases

0.2.10	Aug 28, 2023
0.2.9	Feb 4, 2023
0.2.7	Sep 19, 2022
0.2.6	Aug 29, 2022
0.1.2	Feb 9, 2022

#826 in Procedural macros

122 downloads per month
Used in 2 crates (via wolfram-library-link)

MIT/Apache

18KB
281 lines

wolfram-library-link

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]

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"]]

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 `Link`s 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.

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.

Wolfram LibraryLink User Guide
Introducing C++ and the Wolfram Language with LibraryLinkUtilities, a C++ wrapper around the LibraryLink API.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

Dependencies

~1.5MB
~33K SLoC