{"id":26121532,"url":"https://github.com/fizzed/jne","last_synced_at":"2025-04-13T12:51:24.415Z","repository":{"id":57719281,"uuid":"17503399","full_name":"fizzed/jne","owner":"fizzed","description":"Java library for packaging native libraries, executables, and resources for runtime within jar files","archived":false,"fork":false,"pushed_at":"2025-01-20T18:41:23.000Z","size":6533,"stargazers_count":17,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-27T03:51:24.559Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","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/fizzed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2014-03-07T05:04:58.000Z","updated_at":"2025-03-13T14:01:12.000Z","dependencies_parsed_at":"2023-10-30T17:43:24.102Z","dependency_job_id":"7b50f6b8-7e67-431e-8824-26798de17cf5","html_url":"https://github.com/fizzed/jne","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fjne","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fjne/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fjne/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fjne/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fizzed","download_url":"https://codeload.github.com/fizzed/jne/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717251,"owners_count":21150388,"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-03-10T14:23:41.027Z","updated_at":"2025-04-13T12:51:24.394Z","avatar_url":"https://github.com/fizzed.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Java Native Environment by Fizzed\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.fizzed/jne?style=flat-square)](https://mvnrepository.com/artifact/com.fizzed/jne)\n\n## Automated Testing\n\nThe following Java versions and platforms are tested using GitHub workflows:\n\n[![Java 8](https://img.shields.io/github/actions/workflow/status/fizzed/jne/java8.yaml?branch=master\u0026label=Java%208\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/java8.yaml)\n[![Java 11](https://img.shields.io/github/actions/workflow/status/fizzed/jne/java11.yaml?branch=master\u0026label=Java%2011\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/java11.yaml)\n[![Java 17](https://img.shields.io/github/actions/workflow/status/fizzed/jne/java17.yaml?branch=master\u0026label=Java%2017\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/java17.yaml)\n[![Java 21](https://img.shields.io/github/actions/workflow/status/fizzed/jne/java21.yaml?branch=master\u0026label=Java%2021\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/java21.yaml)\n\n[![Linux x64](https://img.shields.io/github/actions/workflow/status/fizzed/jne/java8.yaml?branch=master\u0026label=Linux%20x64\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/java8.yaml)\n[![MacOS arm64](https://img.shields.io/github/actions/workflow/status/fizzed/jne/macos-arm64.yaml?branch=master\u0026label=MacOS%20arm64\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/macos-arm64.yaml)\n[![Windows x64](https://img.shields.io/github/actions/workflow/status/fizzed/jne/windows-x64.yaml?branch=master\u0026label=Windows%20x64\u0026style=flat-square)](https://github.com/fizzed/jne/actions/workflows/windows-x64.yaml)\n\nThe following platforms are tested using the [Fizzed, Inc.](http://fizzed.com) build system:\n\n[![Linux arm64](https://img.shields.io/badge/Linux%20arm64-passing-green)](buildx-results.txt)\n[![Linux armhf](https://img.shields.io/badge/Linux%20armhf-passing-green)](buildx-results.txt)\n[![Linux riscv64](https://img.shields.io/badge/Linux%20riscv64-passing-green)](buildx-results.txt)\n[![Linux MUSL x64](https://img.shields.io/badge/Linux%20MUSL%20x64-passing-green)](buildx-results.txt)\n[![MacOS x64](https://img.shields.io/badge/MacOS%20x64-passing-green)](buildx-results.txt)\n[![Windows arm64](https://img.shields.io/badge/Windows%20arm64-passing-green)](buildx-results.txt)\n[![FreeBSD x64](https://img.shields.io/badge/FreeBSD%20x64-passing-green)](buildx-results.txt)\n[![OpenBSD x64](https://img.shields.io/badge/OpenBSD%20x64-passing-green)](buildx-results.txt)\n\n## Overview\n\nJava library (8, 11, 17, 21 etc) for working with \"native\" resources on the JVM.  Utilities for finding \u0026 extracting\nOS and hardware architecture dependent files, executables, and libraries (e.g. including libraries as resources in JARs),\nas well as utilities for detecting installed JDKs, or calculating the \"targets\" of native compilation.\n\nThis is a battle-tested library w/ extensive test coverage and automated CI across various operating systems, versions,\nand architectures.\n\nIncludes the following features:\n\n- JNE class: helps to find, extract, and load OS, ABI, and hardware architecture dependent files, executables, and libraries\n- NativeTarget class: helps to compile native code by determining various \"targets\" for Rust, C/C++, or for CI frameworks\n- JavaHome, JavaHomes classes: helps to detect JDKs installed on the local system, as well as versions, distribution, JDK vs. JRE, etc.\n- Support for Linux, Windows, MacOS, FreeBSD, OpenBSD operating systems\n- Support for x64, x32, arm64, armhf, armel, riscv64 hardware architecture\n- Support for GNU \u0026 MUSL abis\n- Support for multiple operating systems and architectures so that a single jar dependency can support them all.\n- Support for finding executables (e.g. cat or cat.exe)\n- Support for finding libraries (e.g. sample.dll/libsample.dylib/libsample.so)\n- Support for finding generic files (e.g. movie.swf)\n- Use a one-time temporary directory for extracted executables (thus same apps running multiple instances get their own executable copy)\n- Specify a directory to extract executables to (useful for single instance daemons).\n- Specify if executables should be deleted on VM exit. If disabled and an extracted directory is specified, then a \"hash\" is calculated for an extracted executable so that if the next run of the app has a dependency change then the latest executable will be used.\n- Optional fallback to x86 executables on x64 platforms where an x64-specific executable is not found/included.  Useful in the case where an x86 executable is good for either architecture and you want to save space by not including both versions in your JAR.\n- Utility classes for double-locking, safe loading of libraries.\n\n## Sponsorship \u0026 Support\n\n![](https://cdn.fizzed.com/github/fizzed-logo-100.png)\n\nProject by [Fizzed, Inc.](http://fizzed.com) (Follow on Twitter: [@fizzed_inc](http://twitter.com/fizzed_inc))\n\n**Developing and maintaining opensource projects requires significant time.** If you find this project useful or need\ncommercial support, we'd love to chat. Drop us an email at [ping@fizzed.com](mailto:ping@fizzed.com)\n\nProject sponsors may include the following benefits:\n\n- Priority support (outside of Github)\n- Feature development \u0026 roadmap\n- Priority bug fixes\n- Privately hosted continuous integration tests for their unique edge or use cases\n\n## OS/Architecture Dependent Extraction at Runtime\n\nJNE can helps with finding, extracting, and using os and architecture dependent files (executables, libraries, and/or\nother files) that are packaged as resources within jar files. Extensive support and testing for operating system, libc\n(e.g. glibc vs. musl), and hardware architecture detection.\n\nAllows them to be easily included as part of a Java application and intelligently extracted for use at runtime. This library makes\nit easy to build your own custom \"bin\" directory based on the runtime operating\nsystem and architecture.  You can package .exe and .dll/.so resources within\njars and then use something like maven for dependency management.\n\nHere is how it works. At runtime, Java let's you find resources in directories\nand/or jars (if they are included on the classpath).  Let's say you wanted to load\nat runtime a shared object (.dll, .so, .dylib) that was packaged inside a .jar\n\n   JNE.loadLibrary(\"mylib\");\n\nThe library would search for the resource using the following resource path\n\n    /jne/\u003cos\u003e/\u003carch\u003e/\u003clib\u003e\n\nOr let's say you wanted to call an external \"cat\" executable.  With a properly packaged resource on the classpath\nthis executable can found with\n\n    File catExeFile = JNE.findExecutable(\"cat\");\n\nIf found the resource would be intelligently extracted to a temporary directory so it\ncan be executed.\n\n    /tmp/1394227238992-0/cat\n\nWhere \"os\" would be something such as \"windows\", \"macos\", or \"linux\" and \"arch\" could\nbe \"x32\" or \"x64\". If we were running on Linux with a 64-bit operating system\nthen the library would search for \"/jne/linux/x64/cat\". If found and contained\nwithin a jar file then this executable would be extracted to either a specific\nor temporary directory and returned as a File object. This File object can then\nbe included as the first argument to a Process or ProcessBuilder object. There\nare other options as well (e.g. fallback to x86 resources on x64 platforms) so\nplease see features below.\n\n## Operating Systems\n\nAll popular operating systems are supported, along with special care for MUSL-based operating systems\nsuch as Alpine Linux.\n\n| OS         | Description                        |\n|------------|------------------------------------|\n| linux      |                                    |\n| linux_musl | Such as alpine linux               |\n| macos      | Also supports osx in resource path |\n| windows    |                                    |\n| freebsd    |                                    |\n| openbsd    |                                    |\n| solaris    |                                    |\n\n## Hardware Architecture\n\nSince this library targets finding or loading libraries for use within a JVM, the\nsupported hardware architectures match what you'd typically find JDK distributors\ncall their architectures.\n\n| Arch     | Description                                                                | Docker          |\n|----------|----------------------------------------------------------------------------|-----------------|\n| x32      | 32-bit i386, i486, i686, etc.                                              | i386/debian     |\n| x64      | 64-bit. Can also use x86_64, amd64 in resource path                        |                 |\n| armel    | 32-bit armv4, armv5, armv6 w/ soft float support. E.g. Raspberry Pi 1      | arm32v5/debian  |\n| armhf    | 32-bit armv7 w/ hard float support. E.g. Raspberry Pi 2                    | arm32v7/debian  |\n| arm64    | 64-bit. Can also use aarch64 in resource path. E.g. Mac M1, Raspberry 3, 4 | arm64v8/ubuntu  |\n| mips64le | 64-bit mips                                                                | mips64le/debian |\n| riscv64  | 64-bit risc-v                                                              | riscv64/ubuntu  |\n| s390x    |                                                                            | s390x/debian    |\n| ppc64le  |                                                                            | ppc64le/debian  |\n\n## Usage\n\nPublished to maven central use the following\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.fizzed\u003c/groupId\u003e\n    \u003cartifactId\u003ejne\u003c/artifactId\u003e\n    \u003cversion\u003e4.3.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nTo safely load a library one time at application startup\n\n```java\n/**\n * Custom safe run once loading of native libs.\n */\npublic class CustomLoader {\n\n  static private final MemoizedRunner loader = new MemoizedRunner();\n\n  static public void loadLibrary() {\n    loader.once(() -\u003e {\n      JNE.loadLibrary(\"jtokyocabinet\");\n    });\n  }\n\n}\n```\n\nTo find a JDK 21 on your local system with a specific distribution:\n\n```java\nfinal JavaHome jdk21 = new JavaHomeFinder()\n    .jdk()\n    .version(21)\n    .preferredDistributions(JavaDistribution.ZULU)\n    .find();\n```\n\nTo build a native language model to help build native-specific targets, urls, etc.\n\n```java\nfinal NativeTarget nativeTarget = NativeTarget.detect();\nfinal NativeLanguageModel nlm = new NativeLanguageModel()\n    .add(\"version\", \"17.0.1\")\n    .add(OperatingSystem.MACOS, \"darwin\")\n    .add(HardwareArchitecture.X64, \"amd64\");\n\nfinal String fileName = nlm.format(\"restic_{version}_{os}_{arch}.bz2\", nativeTarget);\n```\n\n## Demo\n\nTo run a demo of a \"cat\" executable\n\n    mvn -e test-compile exec:java -Dexec.classpathScope=\"test\" -Dexec.mainClass=\"com.fizzed.jne.JneDemo\"\n\nWith overridden extract dir via system property:\n\n    mvn -e test-compile exec:java -Dexec.classpathScope=\"test\" -Dexec.mainClass=\"com.fizzed.jne.JneDemo\" -Djne.extract.dir=\"target/jne\"\n\n## Including resources as a jar\n\nIf using Maven then by default it will include everything in `src/main/resources`\nin a jar.  Let's say you wanted to package a \"cat\" executable for various platforms.\nYou can easily include these for use with JNE by putting them at\n\n    src/main/resources/jne/windows/x32/cat.exe\n    src/main/resources/jne/windows/x64/cat.exe\n    src/main/resources/jne/macos/x32/cat\n    src/main/resources/jne/macos/x64/cat\n    src/main/resources/jne/linux/x32/cat\n    src/main/resources/jne/linux/x64/cat\n    src/main/resources/jne/linux_musl/x64/cat\n    src/main/resources/jne/generic-resource.txt\n\nTo find and extract these resources for use in your app\n\n    File exeFile = JNE.findLibrary(\"cat\", options);\n\nYou'll probably want to package your executables as statically compiled (it\ndoes not rely on external DLLs / shared objects to be available on the runtime system).\nHowever, since this library does essentially build a \"bin\" directory by extracting\nresources, you could find all dependencies first before trying to execute it.\nFor example:\n\n    File libFile = JNE.findLibrary(\"mylib\", options);\n    File exeFile = JNE.findExecutable(\"myapp\", options);\n\nIf this was run on Linux with the extractDir as null (which then uses a temp dir)\nyou would have the following example result:\n\n    /tmp/1394227238992-0/mylib.so\n    /tmp/1394227238992-0/myapp\n\nTo extract a generic resource\n\n    File resourceFile = JNE.findFile(\"generic-resource.txt\", options);\n\n## Development\n\nYou can use an Ubuntu x86_64 host to test a wide variety of hardware architectures and operating systems. For more\ninformation on how this works, please visit https://github.com/fizzed/blaze-buildx#multiple-architecture-containers\n\nYou can test this library on a wide variety of operating systems and architectures\n\n    java -jar blaze.jar test\n\n## License\n\nCopyright (C) 2015+ Fizzed, Inc.\n\nThis work is licensed under the Apache License, Version 2.0. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffizzed%2Fjne","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffizzed%2Fjne","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffizzed%2Fjne/lists"}