{"id":22588798,"url":"https://github.com/wolframresearch/wolfram-library-link-rs","last_synced_at":"2025-08-20T14:31:50.305Z","repository":{"id":38020578,"uuid":"441299175","full_name":"WolframResearch/wolfram-library-link-rs","owner":"WolframResearch","description":"Safe, efficient, and ergonomic bindings to Wolfram LibraryLink and the Wolfram Language","archived":false,"fork":false,"pushed_at":"2023-11-29T06:45:10.000Z","size":588,"stargazers_count":54,"open_issues_count":4,"forks_count":5,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-12-14T01:06:13.772Z","etag":null,"topics":["rust","rust-crate","wolfram-language","wolfram-librarylink"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WolframResearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-12-23T21:25:50.000Z","updated_at":"2024-12-08T02:28:03.000Z","dependencies_parsed_at":"2023-11-29T07:44:19.875Z","dependency_job_id":null,"html_url":"https://github.com/WolframResearch/wolfram-library-link-rs","commit_stats":{"total_commits":425,"total_committers":5,"mean_commits":85.0,"dds":0.4117647058823529,"last_synced_commit":"10f45da9c534440a1506cad14291feef2d3aea78"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolframResearch%2Fwolfram-library-link-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolframResearch%2Fwolfram-library-link-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolframResearch%2Fwolfram-library-link-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolframResearch%2Fwolfram-library-link-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WolframResearch","download_url":"https://codeload.github.com/WolframResearch/wolfram-library-link-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230431104,"owners_count":18224655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rust","rust-crate","wolfram-language","wolfram-librarylink"],"created_at":"2024-12-08T08:11:08.617Z","updated_at":"2024-12-19T12:10:17.702Z","avatar_url":"https://github.com/WolframResearch.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wolfram-library-link\n\n[![Crates.io](https://img.shields.io/crates/v/wolfram-library-link.svg)](https://crates.io/crates/wolfram-library-link)\n![License](https://img.shields.io/crates/l/wolfram-library-link.svg)\n[![Documentation](https://docs.rs/wolfram-library-link/badge.svg)](https://docs.rs/wolfram-library-link)\n\n\u003ch4\u003e\n  \u003ca href=\"https://docs.rs/wolfram-library-link\"\u003eAPI Documentation\u003c/a\u003e\n  \u003cspan\u003e | \u003c/span\u003e\n  \u003ca href=\"https://github.com/WolframResearch/wolfram-library-link-rs/blob/master/docs/CHANGELOG.md\"\u003eChangelog\u003c/a\u003e\n  \u003cspan\u003e | \u003c/span\u003e\n  \u003ca href=\"https://github.com/WolframResearch/wolfram-library-link-rs/blob/master/docs/CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n\u003c/h4\u003e\n\nBindings to the Wolfram LibraryLink interface, making it possible to call Rust code\nfrom the Wolfram Language.\n\nThis library is used for writing Rust programs that can be loaded by the Wolfram\nLibraryLink family of functions, specifically by\n[`LibraryFunctionLoad[]`][ref/LibraryFunctionLoad].\n\n#### Features\n\n  * Efficiently call Rust functions from Wolfram code.\n  * Pass arbitrary Wolfram expressions to and from Rust code.\n  * Evaluate Wolfram expressions from Rust code.\n  * Respond to Wolfram [abort][interrupts] requests while in Rust code.\n  * Safe API for the Wolfram Symbolic Transfer Protocol, using the [`wstp`][wstp] crate.\n\nFollow the [**Quick Start**](./docs/QuickStart.md) guide to begin using `wolfram-library-link`.\n\nSee [**Why Rust?**](./docs/WhyRust.md) for an overview of some of the advantages Rust has\nwhen writing native code for use from the Wolfram Language: performance, memory and thread\nsafety, high-level features, and more.\n\n[interrupts]: https://reference.wolfram.com/language/tutorial/InterruptingCalculations.html\n\n## Quick Examples\n\nThe examples in this section are written with two back-to-back code blocks. The first\nshows the Rust code, and the second shows the Wolfram Language code needed to load and use\nthe related Rust function(s).\n\n#### Basic data types\n\n```rust\nuse wolfram_library_link::export;\n\n#[export]\nfn square(x: i64) -\u003e i64 {\n    x * x\n}\n```\n\n```wolfram\nsquare = LibraryFunctionLoad[\"...\", \"square\", {Integer}, Integer];\n\nsquare[5]\n```\n\nSee also: [`LibraryFunctionLoad`][ref/LibraryFunctionLoad]\n\n#### Efficient numeric arrays\n\nCreate an array of a million integers in Wolfram Language and compute the total using\nRust:\n\n```rust\nuse wolfram_library_link::{export, NumericArray};\n\n#[export]\nfn total(array: \u0026NumericArray\u003ci64\u003e) -\u003e i64 {\n    array.as_slice().into_iter().sum()\n}\n```\n\n```wolfram\ntotal = LibraryFunctionLoad[\n    \"...\",\n    \"square\",\n    {LibraryDataType[NumericArray, \"Integer64\"]},\n    Integer\n];\n\ntotal[NumericArray[Range[1000000], \"Integer64\"]]\n```\n\nSee also: [`NumericArray`][ref/NumericArray], [`LibraryDataType`][ref/LibraryDataType]\n\n## Example Programs\n\nThe [wolfram-library-link/examples](./wolfram-library-link/examples) subdirectory\ncontains sample programs demonstrating features of the `wolfram-library-link` API.\n\nRust code                                                                          | Wolfram Language code                                                                               | Demonstrates ...\n-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------------------\n[basic_types.rs](wolfram-library-link/examples/basic_types.rs)                     | [BasicTypes.wlt](wolfram-library-link/RustLink/Examples/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.\n[numeric_arrays.rs](wolfram-library-link/examples/numeric_arrays.rs)               | [NumericArrays.wlt](wolfram-library-link/RustLink/Examples/NumericArrays.wlt)                | how the [`NumericArray`][NumericArray] data type can be used to efficiently pass large multi-dimensional arrays of uniform numeric data.\n[wstp.rs](wolfram-library-link/examples/wstp.rs)                                   | [WSTP.wlt](wolfram-library-link/RustLink/Examples/WSTP.wlt)                                  | how WSTP [`Link`][wstp::Link]s can be used to pass arbitrary expressions to and from LibraryLink functions.\n[aborts.rs](wolfram-library-link/examples/aborts.rs)                               | [Aborts.wlt](wolfram-library-link/RustLink/Examples/Aborts.wlt)                              | how Rust code can respond to Wolfram [abort requests][interrupts].\n[async_file_watcher.rs](wolfram-library-link/examples/async/async_file_watcher.rs) | [AsyncExamples.wlt](wolfram-library-link/RustLink/Examples/AsyncExamples.wlt)                | how Rust code can generate asynchronous events that trigger Wolfram evaluations to process the event.\n[managed.rs](wolfram-library-link/examples/exprs/managed.rs)                       | [ManagedExpressions.wlt](wolfram-library-link/RustLink/Examples/ManagedExpressions.wlt)      | how the managed expression API can be used to free library data when a Wolfram expression is deallocated.\n[data_store.rs](wolfram-library-link/examples/data_store.rs)                       | [DataStore.wlt](wolfram-library-link/RustLink/Examples/DataStore.wlt)                        | how the [`DataStore`][DataStore] data type can be used to efficiently pass arbitrary expression-like heterogenous structures made up of native *LibraryLink* data types.\n\n[NumericArray]: https://docs.rs/wolfram-library-link/latest/wolfram_library_link/struct.NumericArray.html\n[wstp::Link]: https://docs.rs/wstp/latest/wstp/struct.Link.html\n[DataStore]: https://docs.rs/wolfram-library-link/latest/wolfram_library_link/struct.DataStore.html\n\n#### Raw functions\n\nThese examples demonstrate how to write functions that use the \"raw\" low-level\n*LibraryLink* and WSTP interfaces, using the `extern \"C\"` ABI, the low-level `MArgument`\nand `WSLINK` types, and manual WSTP operations.\n\nRust code                                                            | Wolfram Language code\n---------------------------------------------------------------------|-----------------\n[raw_librarylink_function.rs](wolfram-library-link/examples/raw/raw_librarylink_function.rs) and [raw_wstp_function.rs](wolfram-library-link/examples/raw/raw_wstp_function.rs) | [RawFunctions.wlt](wolfram-library-link/RustLink/Examples/RawFunctions.wlt)\n\n#### Additional examples\n\nIn addition to the polished high-level examples, the\n[wolfram-library-link/examples/tests/](wolfram-library-link/examples/tests/) directory\ncontains test code for a more exhaustive range of functionality and behavior, and may be a\nuseful additional reference. The [RustLink/Tests/](./wolfram-library-link/RustLink/Tests/) directory contains\nthe Wolfram Language unit testing logic that loads and calls the test functions.\n\n[wstp]: https://crates.io/crates/wstp\n[wolfram-expr]: https://crates.io/crates/wolfram-expr\n[wolfram-app-discovery]: https://crates.io/crates/wolfram-app-discovery\n[library-link]: https://reference.wolfram.com/language/guide/LibraryLink.html\n\n[wad-configuration]: https://github.com/WolframResearch/wolfram-app-discovery-rs#configuration\n\n[ref/LibraryFunctionLoad]: https://reference.wolfram.com/language/ref/LibraryFunctionLoad.html\n[ref/LibraryDataType]: https://reference.wolfram.com/language/ref/LibraryDataType.html\n[ref/NumericArray]: https://reference.wolfram.com/language/ref/NumericArray.html\n\n## Building `wolfram-library-link`\n\n`wolfram-library-link` depends on the [`wstp`][wstp] crate for bindings to the Wolfram\nSymbolic Transfer Protocol (WSTP). Building the `wstp` crate requires access to the\nWSTP SDK, which provides the WSTP static library. `wstp` uses [`wolfram-app-discovery`][wolfram-app-discovery] to\nlocate a local installation of the Wolfram Language that contains a suitable copy of the\nWSTP SDK. If the WSTP SDK cannot be located, `wstp` will fail to build, and consequently,\nso will `wolfram-library-link`.\n\nIf you have installed the Wolfram Language to a location unknown to `wolfram-app-discovery`,\nyou may specify the installed location manually by setting the `WOLFRAM_APP_DIRECTORY`\nenvironment variable. See [Configuring wolfram-app-discovery][wad-configuration] for details.\n\n## Related Links\n\n#### Related crates\n\n* [`wstp`][wstp] — bindings to the Wolfram Symbolic Transfer Protocol, used for passing\n  arbitrary Wolfram expressions between programs.\n* [`wolfram-expr`][wolfram-expr] — native Rust representation of Wolfram Language\n  expressions.\n* [`wolfram-app-discovery`][wolfram-app-discovery] — utility for locating local\n  installations of Wolfram applications and the Wolfram Language.\n\n#### Related documentation\n\n* [*Wolfram LibraryLink User Guide*](https://reference.wolfram.com/language/LibraryLink/tutorial/Overview.html)\n* [*Introducing C++ and the Wolfram Language with LibraryLinkUtilities*](https://community.wolfram.com/groups/-/m/t/2133603), a C++ wrapper around the *LibraryLink* API.\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0\n   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license\n   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\nNote: Licensing of the WSTP library linked by the [wstp][wstp] crate is covered by the\nterms of the\n[MathLink License Agreement](https://www.wolfram.com/legal/agreements/mathlink.html).\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n\nSee [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for more information.\n\n### Developer Notes\n\nSee [**Development.md**](./docs/Development.md) for instructions on how to perform common\ndevelopment tasks when contributing to the `wolfram-library-link` crate.\n\nSee [**Maintenance.md**](./docs/Maintenance.md) for instructions on how to keep\n`wolfram-library-link` up to date as new versions of the Wolfram Language are released.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolframresearch%2Fwolfram-library-link-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolframresearch%2Fwolfram-library-link-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolframresearch%2Fwolfram-library-link-rs/lists"}