{"id":29193151,"url":"https://github.com/ironcorelabs/uniffi-bindgen-java","last_synced_at":"2025-07-02T02:07:44.494Z","repository":{"id":237718986,"uuid":"790923848","full_name":"IronCoreLabs/uniffi-bindgen-java","owner":"IronCoreLabs","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-03T21:41:25.000Z","size":170,"stargazers_count":9,"open_issues_count":8,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-04T05:12:10.979Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IronCoreLabs.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-23T19:17:20.000Z","updated_at":"2025-06-03T21:41:10.000Z","dependencies_parsed_at":"2024-05-28T17:46:51.801Z","dependency_job_id":"64eea46e-402c-4530-874b-a19ba7e95fd5","html_url":"https://github.com/IronCoreLabs/uniffi-bindgen-java","commit_stats":null,"previous_names":["ironcorelabs/uniffi-bindgen-java"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/IronCoreLabs/uniffi-bindgen-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronCoreLabs%2Funiffi-bindgen-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronCoreLabs%2Funiffi-bindgen-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronCoreLabs%2Funiffi-bindgen-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronCoreLabs%2Funiffi-bindgen-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IronCoreLabs","download_url":"https://codeload.github.com/IronCoreLabs/uniffi-bindgen-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronCoreLabs%2Funiffi-bindgen-java/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263061405,"owners_count":23407606,"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":[],"created_at":"2025-07-02T02:07:43.788Z","updated_at":"2025-07-02T02:07:44.464Z","avatar_url":"https://github.com/IronCoreLabs.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uniffi-bindgen-java\n\nGenerate [UniFFI](https://github.com/mozilla/uniffi-rs) bindings for Java.\n\nOfficial Kotlin bindings already exist, which can be used by any JVM language including Java. The Java specific bindings use Java-native types where possible for a more ergonomic interface, for example the Java bindings use `CompletableFutures` instead of `kotlinx.coroutines`.\n\nWe highly reccommend you use [UniFFI's proc-macro definition](https://mozilla.github.io/uniffi-rs/latest/proc_macro/index.html) instead of UDL where possible. \n\n## Requirements\n\n* Java 20+: `javac`, and `jar`\n* The [Java Native Access](https://github.com/java-native-access/jna#download) JAR downloaded and its path added to your `$CLASSPATH` environment variable.\n\n## Installation\n\nMSRV is `1.77.0`.\n\n`cargo install uniffi-bindgen-java --git https://github.com/IronCoreLabs/uniffi-bindgen-java`\n\n## Usage\n\n```\nuniffi-bindgen-java --help\nJava scaffolding and bindings generator for Rust\n\nUsage:\n\nCommands:\n  generate     Generate Java bindings\n  scaffolding  Generate Rust scaffolding code\n  print-repr   Print a debug representation of the interface from a dynamic library\n\nOptions:\n  -h, --help     Print help\n  -V, --version  Print version\n```\n\n### Generate Bindings\n\n```\nuniffi-bindgen-java generate --help\nGenerate Java bindings\n\nUsage:\n\nArguments:\n  \u003cSOURCE\u003e  Path to the UDL file, or cdylib if `library-mode` is specified\n\nOptions:\n  -o, --out-dir \u003cOUT_DIR\u003e    Directory in which to write generated files. Default is same folder as .udl file\n  -n, --no-format            Do not try to format the generated bindings\n  -c, --config \u003cCONFIG\u003e      Path to optional uniffi config file. This config is merged with the `uniffi.toml` config present in each crate, with its values taking precedence\n  --lib-file \u003cLIB_FILE\u003e      Extract proc-macro metadata from a native lib (cdylib or staticlib) for this crate\n  --library                  Pass in a cdylib path rather than a UDL file\n  --crate \u003cCRATE_NAME\u003e       When `--library` is passed, only generate bindings for one crate. When `--library` is not passed, use this as the crate name instead of attempting to locate and parse Cargo.toml\n```\n\nAs an example:\n\n```\n\u003e git clone https://github.com/mozilla/uniffi-rs.git\n\u003e cd uniffi-rs/examples/arithmetic-proc-macro\n\u003e cargo b --release\n\u003e uniffi-bindgen-java generate --out-dir ./generated-java --library ../../target/release/libarithmeticpm.so\n\u003e ll generated-java/uniffi/arithmeticpm/\ntotal 216\n-rw-r--r-- 1 user users  295 Jul 24 13:02 ArithmeticExceptionErrorHandler.java\n-rw-r--r-- 1 user users  731 Jul 24 13:02 ArithmeticException.java\n-rw-r--r-- 1 user users 3126 Jul 24 13:02 Arithmeticpm.java\n-rw-r--r-- 1 user users  512 Jul 24 13:02 AutoCloseableHelper.java\n-rw-r--r-- 1 user users  584 Jul 24 13:02 FfiConverterBoolean.java\n...\n\u003e cat generated-java/uniffi/arithmeticpm/Arithmeticpm.java\npackage uniffi.arithmeticpm;\n\n\nimport java.util.List;\nimport java.util.Map;\nimport java.util.concurrent.CompletableFuture;\npublic class Arithmeticpm {\n  public static Long add(Long a, Long b) throws ArithmeticException {\n            try {\n...\n\n```\n\n### Generate Scaffolding\n\n```\nuniffi-bindgen-java scaffolding --help\nGenerate Rust scaffolding code\n\nUsage:\n\nArguments:\n  \u003cUDL_FILE\u003e  Path to the UDL file\n\nOptions:\n  -o, --out-dir \u003cOUT_DIR\u003e  Directory in which to write generated files. Default is same folder as .udl file\n  -n, --no-format          Do not try to format the generated bindings\n```\n\n### Print Debug Representation\n\n```\nuniffi-bindgen-java print-repr --help\nPrint a debug representation of the interface from a dynamic library\n\nUsage:\n\nArguments:\n  \u003cPATH\u003e  Path to the library file (.so, .dll, .dylib, or .a)\n```\n\n## Integrating Bindings\n\nAfter generation you'll have an `--out-dir` full of Java files. Package those into a `.jar` using your build tools of choice, and the result can be imported and used as per normal in any Java project with the `JNA` dependency available.\n\nAny top level functions in the Rust library will be static methods in a class named after the crate.\n\n## Configuration\n\nThe generated Java can be configured using a `uniffi.toml` configuration file.\n\n| Configuration name | Default | Description |\n| --- | --- | --- |\n| `package_name` | `uniffi` | The Java package name - ie, the value use in the `package` statement at the top of generated files. |\n| `cdylib_name` | `uniffi_{namespace}` | The name of the compiled Rust library containing the FFI implementation (not needed when using `generate --library`) |\n| `generate_immutable_records` | `false` | Whether to generate records with immutable fields (`record` instead of `class`). |\n| `custom_types` | | A map which controls how custom types are exposed to Java. See the [custom types section of the UniFFI manual](https://mozilla.github.io/uniffi-rs/latest/udl/custom_types.html#custom-types-in-the-bindings-code) |\n| `external_packages` | | A map of packages to be used for the specified external crates. The key is the Rust crate name, the value is the Java package which will be used referring to types in that crate. See the [external types section of the manual](https://mozilla.github.io/uniffi-rs/latest/udl/ext_types_external.html#kotlin) |\n| `android` | `false` | Used to toggle on Android specific optimizations (warning: not well tested yet) |\n| `android_cleaner` | `android` | Use the `android.system.SystemCleaner` instead of `java.lang.ref.Cleaner`. Fallback in both instances is the one shipped with JNA. |\n\n### Example\n\n#### Custom types\n\n```\n[bindings.java]\npackage_name = \"customtypes\"\n\n[bindings.java.custom_types.Url]\n# Name of the type in the Java code\ntype_name = \"URL\"\n# Classes that need to be imported\nimports = [\"java.net.URI\", \"java.net.URL\"]\n# Functions to convert between strings and URLs\nlift = \"new URI({}).toURL()\"\nlower = \"{}.toString()\"\n```\n\n#### External Types\n\n```\n[bindings.java.external_packages]\n# This specifies that external types from the crate `rust-crate-name` will be referred by by the package `\"java.package.name`.\nrust-crate-name = \"java.package.name\"\n```\n\n## Notes\n\n- failures in CompletableFutures will cause them to `completeExceptionally`. The error that caused the failure can be checked with `e.getCause()`. When implementing an async Rust trait in Java, you'll need to `completeExceptionally` instead of throwing. See `TestFixtureFutures.java` for an example trait implementation with errors.\n- all primitives are signed in Java by default. Rust correctly interprets the a signed primitive value from Java as unsigned when told to. Callers of Uniffi functions need to be aware when making comparisons (`compareUnsigned`) or printing when a value is actually unsigned to code around footguns on this side.\n\n## Unsupported features\n\n* Defaults aren't supported in Java so [uniffi struct, method, and function defaults](https://mozilla.github.io/uniffi-rs/proc_macro/index.html#default-values) don't exist in the Java code. *Note*: a reasonable case could be made for supporting defaults on structs by way of generated builder patterns. PRs welcome.\n* Output formatting isn't currently supported because a standalone command line Java formatter wasn't found. PRs welcome enabling that feature, the infrastructure is in place.\n\n## Testing\n\nWe pull down the pinned examples directly from Uniffi and run Java tests using the generated bindings. Run `cargo t` to run all of them.\n\nNote that if you need additional toml entries for your test, you can put a `uniffi-extras.toml` as a sibling of the test and it will be read in addition to the base `uniffi.toml` for the example. See [CustomTypes](./tests/scripts/TestCustomTypes/) for an example. Settings in `uniffi-extras.toml` apply across all namespaces.\n\n## Versioning\n\n`uniffi-bindgen-java` is versioned separately from `uniffi-rs`. We follow the [Cargo SemVer rules](https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility), so versions are compatible if their left-most non-zero major/minor/patch component is the same. Any modification to the generator that causes a consumer of the generated code to need to make changes is considered breaking.\n\n`uniffi-bindgen-java` is currently unstable and being developed by IronCore Labs to target features required by [`ironcore-alloy`](https://github.com/IronCoreLabs/ironcore-alloy/). The major version is currently 0, and most changes are likely to bump the minor version. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironcorelabs%2Funiffi-bindgen-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fironcorelabs%2Funiffi-bindgen-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironcorelabs%2Funiffi-bindgen-java/lists"}