{"id":22084909,"url":"https://github.com/taaitaaiger/jlrs","last_synced_at":"2025-04-14T00:51:41.034Z","repository":{"id":37849401,"uuid":"239168160","full_name":"Taaitaaiger/jlrs","owner":"Taaitaaiger","description":"Julia bindings for Rust","archived":false,"fork":false,"pushed_at":"2025-03-30T20:09:04.000Z","size":4571,"stargazers_count":448,"open_issues_count":8,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-06T22:01:29.210Z","etag":null,"topics":["ffi","julia","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Taaitaaiger.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-08T16:53:31.000Z","updated_at":"2025-04-05T11:32:53.000Z","dependencies_parsed_at":"2023-11-21T20:31:19.736Z","dependency_job_id":"46b6f185-65b6-43b2-b050-4ad2e46d1619","html_url":"https://github.com/Taaitaaiger/jlrs","commit_stats":{"total_commits":555,"total_committers":5,"mean_commits":111.0,"dds":0.05045045045045049,"last_synced_commit":"45402a4dd301ba8cd0b4fb2aa74e44a389cfe244"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taaitaaiger%2Fjlrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taaitaaiger%2Fjlrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taaitaaiger%2Fjlrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taaitaaiger%2Fjlrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Taaitaaiger","download_url":"https://codeload.github.com/Taaitaaiger/jlrs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248804773,"owners_count":21164131,"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":["ffi","julia","rust"],"created_at":"2024-12-01T01:08:21.327Z","updated_at":"2025-04-14T00:51:41.027Z","avatar_url":"https://github.com/Taaitaaiger.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jlrs\n\n[![Rust Docs](https://docs.rs/jlrs/badge.svg)](https://docs.rs/jlrs)\n[![License:MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\njlrs is a crate that provides access to the Julia C API. It can be used to embed Julia in Rust\napplications and to write interop libraries to Rust crates that can be used by Julia.\n\nJulia versions 1.10, 1.11 and 1.12 are currently supported. In general jlrs aims to support all\nversions starting at the current LTS version, but only the LTS and stable versions are actively\ntested. Using the current stable version of Julia is highly recommended. The minimum supported\nRust version is currently 1.79.\n\nThis readme only contains information about what features are supported by jlrs, what\nprerequisites must be met, and how to meet them. A complete tutorial is available\n[here](https://taaitaaiger.github.io/jlrs-tutorial/). For more information and examples about how\nto use jlrs, please read the [docs](https://docs.rs/jlrs). All documentation assumes you are\nalready familiar with the Julia and Rust programming languages.\n\n## Overview\n\nAn incomplete list of features that are currently supported by jlrs:\n\n- Access arbitrary Julia modules and their content.\n- Call Julia functions, including functions that take keyword arguments.\n- Handle exceptions or convert them to an error message, optionally with color.\n- Include and call your own Julia code.\n- Use custom system images.\n- Create values that Julia can use, and convert them back to Rust, from Rust.\n- Access the type information and fields of such values. Inline and bits-union fields can be\n  accessed directly.\n- Create and use n-dimensional arrays. The `jlrs-ndarray` feature can be enabled for\n  integration with ndarray.\n- Map Julia structs to Rust structs, the Rust implementation can be generated with the\n  JlrsCore package.\n- Structs that can be mapped to Rust include those with type parameters and bits unions.\n- Use Julia from multiple threads either directly or via Julia-aware thread pools.\n- Export Rust types, methods and functions to Julia with the `julia_module` macro.\n- Libraries that use `julia_module` can be compiled with BinaryBuilder and distributed as JLLs.\n\n## Prerequisites\n\nTo use jlrs, supported versions of Rust and Julia must have been installed. Currently, Julia 1.10,\n1.11 and 1.12 are supported, the minimum supported Rust version is 1.79. Some features may require\na more recent version of Rust. jlrs uses the JlrsCore package for Julia, if this package has not\nbeen installed, the latest version will be installed automatically by default.\n\n### Linux\n\nThe recommended way to install Julia is to download the binaries from the official website,\nwhich is distributed as an archive containing a directory called `julia-x.y.z`. This directory\ncontains several other directories, including a `bin` directory containing the `julia`\nexecutable.\n\nDuring compilation, the paths to the header and library are normally detected automatically by\nexecuting the command `which julia`. The path to `julia.h` must be\n`$(which julia)/../include/julia/julia.h` and the path to the library\n`$(which julia)/../lib/libjulia.so`. If you want to override this default behaviour the\n`JULIA_DIR` environment variable must be set to the path to the appropriate `julia.x-y-z`\ndirectory, in this case `$JULIA_DIR/include/julia/julia.h` and\n`$JULIA_DIR/lib/libjulia.so` are used instead.\n\nIn order to be able to load `libjulia.so` this file must be on the library search path. If\nthis is not the case you must add `/path/to/julia-x.y.z/lib` to the `LD_LIBRARY_PATH`\nenvironment variable.\n\n### macOS\n\nFollow the instructions for Linux, but replace `LD_LIBRARY_PATH` with `DYLD_LIBRARY_PATH`.\n\n### Windows\n\nJulia can be installed using juliaup, or with the installer or portable installation\ndownloaded from the official website. In the first case, Julia has been likely installed in\n`%USERPROFILE%\\.julia\\juliaup\\julia-x.y.z+0~x64`, using the installer or extracting allows you to\npick the destination. After installation or extraction a folder called `Julia-x.y.z` exists, which\ncontains several folders including a `bin` folder containing `julia.exe`. The path to the `bin`\nfolder must be added to the `Path` environment variable.\n\nJulia is automatically detected by executing the command `where julia`. If this returns\nmultiple locations the first one is used. The default can be overridden by setting the\n`JULIA_DIR` environment variable. This doesn't work correctly with juliaup, in this case\nthe environment variable must be set.\n\n## Features\n\nMost functionality of jlrs is only available if the proper features are enabled. These\nfeatures generally belong to one of three categories: versions, runtimes and utilities.\n\n### Versions\n\nThe Julia C API is unstable and there are minor incompatibilities between different versions of\nJulia. To ensure the correct bindings are used for a particular version of Julia you must enable a\nversion feature. The following version features are currently supported:\n\n- `julia-1-10`\n- `julia-1-11`\n- `julia-1-12`\n\nExactly one version feature must be enabled. Otherwise, jlrs will fail to compile.\n\nIf you want your crate to be compatible with multiple versions of Julia, you should \"reexport\"\nthese version features as follows:\n\n```toml\n[features]\njulia-1-10 = [\"jlrs/julia-1-10\"]\njulia-1-11 = [\"jlrs/julia-1-11\"]\njulia-1-12 = [\"jlrs/julia-1-12\"]\n```\n\n### Runtimes\n\nA runtime lets initialize Julia from Rust application, the following features enable a runtime:\n\n- `local-rt`\n\n  Enables the local runtime. The local runtime provides single-threaded, blocking access to Julia.\n\n- `async-rt`\n\n  Enables the async runtime. The async runtime runs on a separate thread and can be used from\n  multiple threads. This feature requires using at least Rust 1.85.\n\n- `tokio-rt`\n\n  The async runtime requires an executor. This feature provides a tokio-based executor. This\n  feature requires using at least Rust 1.85.\n\n- `multi-rt`\n\n  Enables the multithreaded runtime. The multithreaded runtime lets you call Julia from arbitrary\n  threads. It can be combined with the `async-rt` feature to create Julia-aware thread pools.\n\n**WARNING**: Runtime features must only be enabled by applications that embed Julia. Libraries\nmust never enable a runtime feature.\n\n**WARNING**: When building an application that embeds Julia, set\n`RUSTFLAGS=\"-Clink-args=-rdynamic\"` if you want fast code.\n\n### Utilities\n\nAll other features are called utility features. The following are available:\n\n- `async`\n\n  Enable the features of the async runtime which don't depend on the executor. This\n  can be used in libraries which provide implementations of tasks that the async runtime can\n  handle. This feature requires using at least Rust 1.85.\n\n- `jlrs-derive`\n\n  This feature should be used in combination with the code generation provided by the Reflect\n  module in the JlrsCore package. This module lets you generate Rust implementations of Julia\n  structs, this generated code uses custom derive macros made available with this feature to\n  enable the safe conversion of data from Julia to Rust, and from Rust to Julia in some cases.\n\n- `jlrs-ndarray`\n\n  Access the content of a Julia array as an `ArrayView` or `ArrayViewMut` from ndarray.\n\n- `f16`\n\n  Adds support for working with Julia's `Float16` type from Rust using half's `f16` type.\n\n- `complex`\n  Adds support for working with Julia's `Complex` type from Rust using num's `Complex` type.\n\n- `ccall`\n\n  Julia's `ccall` interface can be used to call functions written in Rust from Julia. No\n  runtime can be used in this case because Julia has already been initialized, when this\n  feature is enabled the `CCall` struct is available which offers the same functionality as\n  the local runtime without initializing Julia. The `julia_module` macro is provided to\n  easily export functions, types, and data in combination with the macros from the Wrap\n  module in the JlrsCore package.\n\n- `lto`\n\n  jlrs depends on a support library written in C, if this feature is enabled this support library\n  is built with support for cross-language LTO which can provide a significant performance boost.\n\n  This feature has only been tested on Linux and requires building the support library using a\n  version of `clang` with the same major version as `rustc`'s LLVM version; e.g. rust 1.78.0 uses\n  LLVM 18.1.2, so it requires `clang-18`. You can check what version you need by executing\n  `rustc -vV`.\n\n  You must set the `RUSTFLAGS` environment variable if this feature is enabled, and possibly the\n  `CC` environment variable. Setting `RUSTFLAGS` overrides the default flags that jlrs sets, so\n  you must set at least the following flags:\n  `RUSTFLAGS=\"-Clinker-plugin-lto -Clinker=clang-XX -Clink-arg=-fuse-ld=lld -Clink-args=-rdynamic\"`.\n  The last one is particularly important for embedders, forgetting it is guaranteed to kill\n  performance.\n\n- `i686`\n\n  Link with a 32-bit build of Julia on Linux, only used for cross-compilation.\n\n- `windows`\n\n  Flag that must be enabled when cross-compiling for Windows from Linux.\n\n- `debug`\n\n  Link with a debug build of Julia on Linux.\n\n- `no-link`\n\n  Don't link Julia.\n\n- `yggdrasil`\n\n  Flag that must be enabled when compiling with BinaryBuilder.\n\nYou can enable all features except `debug`, `i686`, `windows`, `no-link` and `yggdrasil` by\nenabling the `full` feature. If you don't want to enable any runtimes either, you can use\n`full-no-rt`.\n\n## Environment variables\n\nIt's possible to override certain defaults of jlrs and Julia by setting environment variables.\nMany of the environment variables mentioned\n[here](https://docs.julialang.org/en/v1/manual/environment-variables/) should apply to applications\nthat use jlrs as well, but this is mostly untested.\n\nSeveral additional environment variables can be set which only affect applications that use jlrs.\n\n- `JLRS_CORE_VERSION=major.minor.patch`\nInstalls the set version of JlrsCore before loading it.\n\n- `JLRS_CORE_REVISION=rev`\nInstalls the set revision of JlrsCore before loading it.\n\n- `JLRS_CORE_REPO=repo-url`\nCan be used with `JLRS_CORE_REVISION` to set the repository JlrsCore will be downloaded from.\n\n- `JLRS_CORE_NO_INSTALL=...`\nDon't install JlrsCore, its value is ignored.\n\n`JLRS_CORE_NO_INSTALL` takes priority over `JLRS_CORE_REVISION`, which takes priority over\n`JLRS_CORE_VERSION`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaaitaaiger%2Fjlrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaaitaaiger%2Fjlrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaaitaaiger%2Fjlrs/lists"}