If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/java-native-access/jna shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 3w ago
• 20 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live java-native-access/jna repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/java-native-access/jna.

What it runs against: a local clone of java-native-access/jna — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in java-native-access/jna | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 54 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of java-native-access/jna. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/java-native-access/jna.git
#   cd jna
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of java-native-access/jna and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "java-native-access/jna(\\.git)?\\b" \\
  && ok "origin remote is java-native-access/jna" \\
  || miss "origin remote is not java-native-access/jna (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "build.xml" \\
  && ok "build.xml" \\
  || miss "missing critical file: build.xml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "common.xml" \\
  && ok "common.xml" \\
  || miss "missing critical file: common.xml"
test -f ".github/workflows/ci.yaml" \\
  && ok ".github/workflows/ci.yaml" \\
  || miss "missing critical file: .github/workflows/ci.yaml"
test -f "ant-tools-src/com/sun/jna/ant/ModuleGenerator.java" \\
  && ok "ant-tools-src/com/sun/jna/ant/ModuleGenerator.java" \\
  || miss "missing critical file: ant-tools-src/com/sun/jna/ant/ModuleGenerator.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 54 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~24d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/java-native-access/jna"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Java Native Access (JNA) is a Java library that enables Java programs to call native shared libraries (C/C++ code) directly without writing JNI or native code. It uses a small JNI stub to dynamically invoke native functions based on Java interfaces that describe the native API, making native platform access as simple as defining method signatures in Java—comparable to Python's ctypes or Windows' Platform/Invoke. Monorepo structure: core JNA library in root src/ (inferred), ant-tools-src/ for build-time code generation (ModuleGenerator.java, CalcAndroidVersion.java), contrib/ with sample demos (alphamaskdemo, balloonmanagerdemo showing Windows/Mac platform integration). Native stub code in C/Assembly (counted ~1.7MB C, ~465KB Assembly). Build-time module/export code generation via ant-tools to support Java 9+ modules.

Java developers building cross-platform applications who need access to native OS libraries (Windows APIs, POSIX system calls, custom C libraries) without the complexity of writing JNI boilerplate. Users range from Apache Cassandra maintainers to Mac developers using Rococoa bindings, and anyone needing platform-specific functionality (file I/O, system calls, graphics APIs).

Highly mature and production-ready. JNA has dozens of contributors and hundreds of commercial/non-commercial projects depending on it (Cassandra, major frameworks). The repo shows active CI/CD via GitHub Actions (ci.yaml, native-libraries-macOS.yaml), Travis, and AppVeyor; licensing under AL2.0 and LGPL2.1; and structured build system (build.xml, common.xml, ant-tools-src/). Version 5.18.1 javadoc published; CHANGES.md maintained.

Low risk for stability but medium risk for maintenance velocity. The dual-license model (AL2.0/LGPL2.1) may complicate enterprise use. Ant-based build (build.xml, common.xml) is older than Maven/Gradle standard, requiring Ant familiarity. Platform-specific native code (C, Assembly in file counts) means OS-specific bugs are harder to reproduce. No visible public issue backlog in file list, but multi-platform CI (Windows/macOS/Linux via GitHub Actions, Travis, AppVeyor) demands careful testing.

Actively maintained: recent CI workflow files (ci.yaml, native-libraries-macOS.yaml in .github/workflows/), Dependabot enabled (.github/dependabot.yml), multi-platform native library builds (macOS workflow suggests recent ARM/Apple Silicon work). CHANGES.md indicates version tracking. Build system maintained with modern Java module support (ant/ModuleGenerator.java).

Clone and build with Ant: git clone https://github.com/java-native-access/jna.git && cd jna && ant (see build.xml). Pre-requisites: Java SDK, Ant, C compiler for native stub (GCC/Clang/MSVC depending on OS). Run tests with ant test (implied by test suite in standard structure). Check README.md for platform-specific native build requirements.

Daily commands: ant (default target from build.xml builds the library). For examples, see contrib/ subdirectories: cd contrib/alphamaskdemo && ant builds Windows/GUI demo. No central dev server (this is a library, not an app). Integration: add built JAR to classpath and call JNA interfaces from Java code.

• build.xml — Primary Ant build configuration that orchestrates compilation, testing, and native library integration across all platforms—essential for understanding the build process and dependency management.
• README.md — High-level overview of JNA's purpose, architecture, and usage patterns that every contributor must read to understand the project's scope and design philosophy.
• common.xml — Shared Ant build properties and common targets referenced by build.xml; defines platform detection, compiler settings, and core build rules.
• .github/workflows/ci.yaml — Continuous integration pipeline defining test execution, artifact generation, and validation rules across multiple platforms and JVM versions.
• ant-tools-src/com/sun/jna/ant/ModuleGenerator.java — Core build-time code generator for Java module descriptors and platform-specific native bindings that enables multi-platform native library support.
• checkstyle.xml — Code quality and style enforcement rules that all Java code must follow; defines naming conventions, documentation requirements, and structural patterns.
• CHANGES.md — Release notes and API change history essential for understanding evolution, deprecations, and backward compatibility commitments.

Add a new platform-specific native library binding

1. Define platform detection and compiler flags in common.xml (e.g., new OS or architecture pattern) (common.xml)
2. Add a platform-specific Ant target in build.xml that compiles C/C++ sources and produces native .so/.dll/.dylib (build.xml)
3. Create or update a ModuleGenerator task in build.xml to generate Java stubs for the new platform (ant-tools-src/com/sun/jna/ant/ModuleGenerator.java)
4. Update CI workflow files to test the new platform in automated builds (.github/workflows/ci.yaml)
5. Add a checkstyle suppressions rule if platform-specific code violates standard style guidelines (checkstyle_suppressions.xml)

Add a new demo or example application

1. Create a new subdirectory under contrib/ (e.g., contrib/newdemo/) with .classpath and .project files (contrib)
2. Create build.xml in the demo folder referencing common patterns from existing demos (e.g., contrib/msoffice/build.xml) (contrib/msoffice/build.xml)
3. Implement demo Java classes in src/com/sun/jna/contrib/demo/ using JNA APIs to call native libraries (contrib/monitordemo/src/com/sun/jna/contrib/demo/MonitorInfoDemo.java)
4. Ensure all source files include the license header from checkstyle_header.txt (checkstyle_header.txt)

Update code style or quality enforcement rules

1. Modify checkstyle.xml to add or adjust style rules (naming, documentation, structure) (checkstyle.xml)
2. If the rule causes violations in existing code, add suppressions to checkstyle_suppressions.xml (checkstyle_suppressions.xml)
3. Document the change and any suppression rationale in CHANGES.md (CHANGES.md)
4. Verify the CI pipeline passes by pushing a test branch (validate in .github/workflows/ci.yaml) (.github/workflows/ci.yaml)

• Apache Ant (build.xml) — Provides fine-grained control over platform-specific native compilation, dynamic property substitution, and custom task development (ModuleGenerator) needed for cross-platform JNI library packaging.
• GitHub Actions (CI/CD) — Enables matrix-driven multi-platform testing (Linux, Windows, macOS across JVM versions) with native library compilation; integrates seamlessly with GitHub repository and workflow dispatch.
• Checkstyle (code quality) — Enforces consistent Java style, Javadoc coverage, and naming conventions across a large open-source project with many contributors; machine-readable configuration integrates into CI pipeline.
• JNI (Java Native Interface) + native C/C++ — Core technology enabling Java programs to call platform-specific native libraries (OS APIs, system libraries) with minimal wrapper overhead and maximum platform interoperability.
• Java 9+ modules (module-info.java) — Provides explicit API boundaries, encapsulation of platform-specific implementations, and compatibility with Java Platform Module System for secure JAR deployment.

• Dual licensing (Apache 2.0 + LGPL 2.1) instead of single permissive license

  • Why: Balances commercial adoption (Apache 2.0 permissiveness) with open-source compliance (LGPL copyleft for contributions), allowing broad ecosystem integration.
  • Consequence: Increases legal complexity for users; requires careful license disclosure in redistributions and derivative works; dual-license headers required in every source file.

• Build-time JNI code generation (ModuleGenerator) rather than runtime reflection

  • Why: Reduces JVM startup overhead, enables ahead-of-time compilation (GraalVM), and produces explicit module
  • Consequence: undefined

Native compilation required: Building from source requires platform-specific C compiler (MSVC on Windows, GCC/Clang on Unix). Pre-built JARs available but custom native binding requires Ant + compiler. Ant-based build: No Maven Central automatic deployment visible; requires understanding Ant quirks (property ordering, conditional targets). JNI fragility: Changes to JNI interface require recompilation of C stubs; ABI incompatibility across Java/OS versions can cause hard-to-debug crashes. Module system complexity: ModuleGenerator.java indicates Java 9+ module descriptor generation—misconfigurations break module path resolution. Platform-specific bugs: OS-specific behavior (Windows API quirks, macOS framework versions, Linux glibc versions) may not surface in local dev environment.

• Java Native Interface (JNI) — JNA's entire value proposition is hiding JNI boilerplate; understanding JNI (function signatures, type marshalling, JNIEnv) explains why JNA's interface-based approach is a paradigm shift
• Dynamic Proxy Pattern — JNA uses Java dynamic proxies to intercept method calls on user-defined interfaces and route them to native code; core to how JNA avoids code generation
• Foreign Function Interface (FFI) — JNA implements FFI semantics (calling external native code with type marshalling); related to Project Panama (Java 19+ foreign function API) which aims to standardize this pattern
• Type Marshalling — JNA automatically converts between Java types (int, String, Object) and native C types (int, char*, struct); understanding marshalling rules prevents crashes from type mismatches
• Application Binary Interface (ABI) — JNA's native stubs must match the ABI of target OS/architecture (calling conventions, register allocation, struct layout); ABI mismatches cause segfaults
• JPMS (Java Platform Module System) — JNA includes module descriptor generation (ModuleGenerator.java) for Java 9+ module path support; necessary for modern Java projects using module encapsulation
• Cross-platform Native Compilation — JNA's build system (build.xml, common.xml) handles platform-specific C compiler flags, ABI differences across Windows/macOS/Linux; understanding multiplatform native builds is essential for maintenance

• java-native-access/jna-gpl — GPL-licensed variant of JNA for projects requiring GPL compliance; same API, different licensing model
• iterate-ch/rococoa — macOS Cocoa framework bindings built on top of JNA; reference implementation of JNA for real-world platform integration
• graalvm/graal — GraalVM native-image compilation: JNA is critical for GraalVM polyglot and native-image projects needing native interop
• openjdk/jdk — OpenJDK source; JNA's JNI stub design mirrors OpenJDK's own native interop patterns; useful for understanding JNI limitations JNA works around
• swig/swig — SWIG is an alternative approach to JNI binding generation; contrast with JNA's interface-driven, zero-native-code philosophy

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for native library cross-platform testing

The repo has a native-libraries-macOS.yaml workflow but lacks comprehensive cross-platform native library testing for Linux and Windows. Given that JNA is fundamentally about native access across platforms, a complete CI/CD pipeline testing native bindings on all major OSes (Windows, Linux, macOS) would catch platform-specific regressions early. This is critical for a native interop library.

• [ ] Create .github/workflows/native-libraries-linux.yaml for Linux native library builds and tests
• [ ] Create .github/workflows/native-libraries-windows.yaml for Windows native library builds and tests
• [ ] Ensure workflows test against multiple architectures (x86_64, ARM64) where applicable
• [ ] Reference existing native-libraries-macOS.yaml as a template to maintain consistency
• [ ] Add test steps that verify native library loading works correctly on each platform

Add comprehensive unit tests for ant-tools-src build utilities

The ant-tools-src/ directory contains critical build-time code (BuildArmSoftFloatDetector.java, ModuleGenerator.java, CalcAndroidVersion.java, Exports.java, etc.) but there are no visible test files for these tools. These are essential for correct builds on different architectures and Android versions. Adding tests would prevent build system regressions and make contributions safer.

• [ ] Create test directory test/com/sun/jna/ant/ mirroring the source structure
• [ ] Add unit tests for CalcAndroidVersion.java covering various API level parsing scenarios
• [ ] Add unit tests for BuildArmSoftFloatDetector.java with mock processor detection
• [ ] Add unit tests for ModuleGenerator.java verifying correct module-info.java generation
• [ ] Add unit tests for Exports.java and Opens.java to verify manifest generation
• [ ] Update build.xml to include ant-tools tests in the test target

Create platform-specific test suites in contrib/ modules

The contrib/ directory has multiple demo/test modules (alphamaskdemo, balloonmanagerdemo, dnddemo, etc.) but there are no organized platform-specific integration tests verifying these work correctly on Windows, macOS, and Linux. Adding proper test suites with platform detection would validate that native integrations actually work end-to-end on each OS.

• [ ] Create test/com/sun/jna/contrib/platform/ directory for platform-specific tests
• [ ] Add @Requires annotation/skip logic for platform-specific tests (Windows-only, macOS-only, etc.)
• [ ] Create WindowsPlatformTest.java testing Windows-specific JNA features from contrib modules
• [ ] Create MacOSPlatformTest.java testing macOS-specific JNA features
• [ ] Create LinuxPlatformTest.java testing Linux-specific JNA features
• [ ] Document in contrib/README which demos/features require which platforms

• Add unit tests for contrib/alphamaskdemo/com/sun/jna/contrib/demo/AlphaMaskDemo2.java: currently no test file exists in visible structure; write JUnit tests covering native function calls to exercise the demo's Windows API bindings.
• Expand checkstyle.xml with rules for native code (C): current checkstyle_*.xml only cover Java; add or document C coding standards for consistency in jni/ or native/ stubs (e.g., naming conventions, indentation).
• Document platform-specific build requirements in README.md: file list shows native code (C, Assembly) but README snippet lacks step-by-step instructions for macOS (Clang), Windows (MSVC), and Linux (GCC) setup; add a 'Building from Source' section with version constraints.

The JNA project demonstrates a reasonable security posture as a well-established native access library. Primary concerns relate to the inherent risks of native library loading, lack of visible automated dependency scanning in CI/CD pipelines, and missing artifact code signing mechanisms. No hardcoded credentials or obvious injection vulnerabilities were identified in the visible file structure. The project maintains dual licensing (Apache 2.0 and LGPL 2.1), which should be clearly documented. Recommendations focus on strengthening supply chain security through dependency scanning, artifact signing, and enhanced CI/CD security controls.

• Medium · Potential Insecure Native Library Loading — Core JNA library loading mechanism. JNA (Java Native Access) dynamically loads native libraries at runtime. While this is the intended functionality, there is inherent risk if library paths are not properly validated or if the library search path can be manipulated by an attacker, potentially leading to arbitrary native code execution. Fix: Ensure native libraries are loaded from secured, verified locations. Implement strict path validation and consider using absolute paths rather than relative paths. Verify integrity of native libraries using cryptographic signatures.
• Medium · Missing Security Headers in Build Configuration — .github/workflows/ci.yaml, build.xml, common.xml. The CI/CD configuration (.github/workflows) and build files do not explicitly specify security scanning or dependency vulnerability checking in the visible build process. Fix: Integrate automated dependency scanning tools (e.g., OWASP Dependency-Check, Snyk) into the CI/CD pipeline. Add SBOM generation and security policy enforcement.
• Low · Multiple License Formats Present — AL2.0, LGPL2.1, LICENSE, OTHERS files. The project contains multiple license files (AL2.0, LGPL2.1, LICENSE, OTHERS). While not a direct security vulnerability, inconsistent licensing could lead to compliance issues and potential legal risks if license terms are not properly communicated. Fix: Clearly document which license applies to which components. Consider consolidating to a single primary license if possible, or ensure dual/multi-licensing is explicitly documented.
• Low · No Visible Code Signing Configuration — build.xml, build-ant-tools.xml, .github/workflows. Build artifacts (JARs, native libraries) do not show evidence of code signing configuration in visible build files, which could impact supply chain security and artifact integrity verification. Fix: Implement code signing for all build artifacts. Configure Maven Central or alternative distribution mechanisms to verify artifact signatures. Document the signing process and publish public keys.
• Low · Potential Information Disclosure in Build Artifacts — contrib/ directory, contrib subdirectories. The presence of multiple demo applications and contrib modules suggests potentially verbose build outputs and debug information that could be exposed in compiled artifacts. Fix: Ensure debug symbols are stripped from release builds. Implement build output filtering to prevent sensitive information leakage. Review demo applications for hardcoded sensitive data.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.