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/bytedeco/javacpp 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 2mo ago
• 17 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 56% 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 bytedeco/javacpp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bytedeco/javacpp.

What it runs against: a local clone of bytedeco/javacpp — 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 bytedeco/javacpp | 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 ≤ 101 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bytedeco/javacpp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bytedeco/javacpp.git
#   cd javacpp
#
# 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 bytedeco/javacpp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bytedeco/javacpp(\\.git)?\\b" \\
  && ok "origin remote is bytedeco/javacpp" \\
  || miss "origin remote is not bytedeco/javacpp (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 "src/main/java/org/bytedeco/javacpp/Pointer.java" \\
  && ok "src/main/java/org/bytedeco/javacpp/Pointer.java" \\
  || miss "missing critical file: src/main/java/org/bytedeco/javacpp/Pointer.java"
test -f "src/main/java/org/bytedeco/javacpp/Loader.java" \\
  && ok "src/main/java/org/bytedeco/javacpp/Loader.java" \\
  || miss "missing critical file: src/main/java/org/bytedeco/javacpp/Loader.java"
test -f "src/main/java/org/bytedeco/javacpp/ClassProperties.java" \\
  && ok "src/main/java/org/bytedeco/javacpp/ClassProperties.java" \\
  || miss "missing critical file: src/main/java/org/bytedeco/javacpp/ClassProperties.java"
test -f "src/main/java/org/bytedeco/javacpp/FunctionPointer.java" \\
  && ok "src/main/java/org/bytedeco/javacpp/FunctionPointer.java" \\
  || miss "missing critical file: src/main/java/org/bytedeco/javacpp/FunctionPointer.java"
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 101 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~71d)"
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/bytedeco/javacpp"
  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).

JavaCPP is a bridge that allows Java code to directly call native C++ libraries via JNI without writing boilerplate JNI code or custom language bindings. It uses Java annotations and a code generator to automatically create the JNI glue layer, enabling seamless interop between Java and C++ with minimal overhead—similar to how cppyy works for Python but for the JVM. Monorepo with two main modules: src/main/java/org/bytedeco/javacpp/ contains the core runtime library (Pointer, Loader, FunctionPointer, and typed pointer classes like IntPointer, BytePointer), while platform/src/ houses platform-specific native binaries and build assembly configs. Integration tests live in src/it/osgi/ demonstrating OSGi-compatible usage with sample C headers (calc.h).

Java/JVM developers who need to integrate performance-critical C++ libraries (like OpenCV, TensorFlow, or custom DSP code) into their applications without learning JNI internals or maintaining separate C code. Also used by library maintainers (like OpenCV Java bindings) who want to expose C++ APIs to Java users.

Actively maintained and production-ready. The project has a well-established GitHub presence (bytedeco/javacpp), published on Maven Central with version 1.5.14-SNAPSHOT in the pom.xml, CI/CD via GitHub Actions and Travis CI, and comprehensive test suites (src/it/osgi integration tests). Last activity visible in workflow files and recent version numbering indicates ongoing active development.

Low risk for core functionality but specific build-system coupling: it's a single-maintainer project (Samuel Audet listed as sole developer) and requires platform-specific native compilers (C++) and JNI headers to work—binary distribution happens via javacpp-platform artifact. Breaking changes in Java/JNI APIs (e.g., Java 16+ module system) could require maintenance.

Version 1.5.14-SNAPSHOT indicates active development with likely improvements to JNI interop, platform support, or memory management. GitHub Actions workflows (javacpp.yml) run automated tests. No specific PR or milestone data visible, but the snapshot version suggests ongoing work toward a release.

git clone https://github.com/bytedeco/javacpp.git && cd javacpp && mvn clean install (builds the core library and platform artifacts). For local testing, mvn test runs unit tests; src/it/osgi/ requires OSGi runtime setup for integration testing.

Daily commands: mvn clean package generates javacpp.jar; to use in downstream projects, add <dependency><groupId>org.bytedeco</groupId><artifactId>javacpp</artifactId></dependency> to your pom.xml. The Loader class auto-extracts and loads native .so/.dll/.dylib binaries from platform-specific artifacts at runtime.

• src/main/java/org/bytedeco/javacpp/Pointer.java — Core abstraction for memory pointers; all native memory interactions depend on this class's contract and JNI bindings.
• src/main/java/org/bytedeco/javacpp/Loader.java — Handles dynamic loading of native libraries across platforms; failure here breaks the entire bridge.
• src/main/java/org/bytedeco/javacpp/ClassProperties.java — Manages metadata for C++ class bindings and platform-specific configurations; drives code generation and library linking.
• src/main/java/org/bytedeco/javacpp/FunctionPointer.java — Enables Java callbacks into C++ function pointers; critical for event-driven native interactions.
• pom.xml — Maven configuration that orchestrates native compilation, platform detection, and artifact assembly.
• src/main/java/org/bytedeco/javacpp/PointerScope.java — Provides resource management for pointer lifetime and automatic cleanup; prevents memory leaks in JNI code.
• src/main/java/org/bytedeco/javacpp/annotation/Platform.java — Annotation-driven platform detection and conditional compilation flags; controls which native libraries load on each OS.

Add a new C++ class binding

1. Create a new Java class extending Pointer or implementing the desired interface (src/main/java/org/bytedeco/javacpp/YourClassName.java)
2. Apply @Name annotation to map Java methods to C++ symbols (src/main/java/org/bytedeco/javacpp/YourClassName.java (use @Name("MyClass")))
3. Use @ByRef, @ByPtr, or @ByVal annotations on parameters to control C++ marshalling semantics (src/main/java/org/bytedeco/javacpp/YourClassName.java (method signatures))
4. Apply @Properties to specify native library name and compiler flags (src/main/java/org/bytedeco/javacpp/YourClassName.java (class-level annotation))
5. Run Maven build which triggers code generation and JNI compilation (pom.xml (mvn clean install))

Add support for a new platform (OS/architecture)

1. Define platform detection criteria using @Platform annotation with regex patterns (src/main/java/org/bytedeco/javacpp/annotation/Platform.java (apply to class))
2. Add platform-specific compiler and linker flags in @Properties or ClassProperties (src/main/java/org/bytedeco/javacpp/ClassProperties.java)
3. Update platform/pom.xml with new OS/architecture combination for artifact assembly (platform/pom.xml)
4. Add native build scripts or CMake configuration for the new platform (src/main/assembly/bin.xml or build system integration)

Add a new typed pointer class for primitive types

1. Create new pointer class mirroring IntPointer or DoublePointer pattern (src/main/java/org/bytedeco/javacpp/YourTypePointer.java)
2. Extend Pointer and implement array indexing via JNI calls to get/put at specific offsets (src/main/java/org/bytedeco/javacpp/YourTypePointer.java (constructors and get/put methods))
3. Register the new pointer type in Loader for automatic discovery (src/main/java/org/bytedeco/javacpp/Loader.java)
4. Add unit tests covering allocation, indexing, and cleanup (src/test/java/org/bytedeco/javacpp/YourTypePointerTest.java)

Add a new C++ STL type wrapper

1. Create annotation class for the STL type (similar to StdString or StdVector) (src/main/java/org/bytedeco/javacpp/annotation/StdYourType.java)
2. Implement marshalling logic to convert between Java and C++ representations (src/main/java/org/bytedeco/javacpp/annotation/StdYourType.java)
3. Apply the annotation to method parameters or return types to enable automatic conversion (Your binding class using @StdYourType)
4. Update the Maven compiler plugin to recognize the new annotation in code generation phase (pom.xml (plugin configuration))

1. Native binary availability: Loader.java auto-downloads platform-specific .so/.dll binaries; if maven repositories are unreachable or your platform (e.g., custom ARM arch) is unsupported, you must build javacpp-platform manually from source. 2) JNI callback threading: FunctionPointer callbacks execute on the C++ thread that invokes them—Java code inside callbacks is not automatically GC-safe; you must manually call JNI AttachCurrentThread in multi-threaded scenarios. 3) Pointer lifecycle: Pointer.deallocate() is NOT automatically called; memory leaks occur if you forget to call it or wrap pointers in PointerScope. 4) Windows UAC/DLL search paths: On Windows, some native libraries may fail to load due to DLL search order; inspect System.loadLibrary error messages carefully.

• Java Native Interface (JNI) — JavaCPP's entire purpose is to hide JNI complexity; you must understand JNI's type marshalling, method signatures (e.g., (I)V for int->void), and object references to debug interop issues
• Memory marshalling and pointer arithmetic — Pointer.java implements off-heap memory access; you need to understand byte ordering, type sizes, and address calculation to safely read/write C++ memory from Java
• Dynamic library loading (dlopen/LoadLibrary) — Loader.java uses System.load() and platform-specific mechanisms to load native .so/.dll files; understanding dynamic linking is critical for diagnosing load failures
• Call stack frames and thread-local JNI references — FunctionPointer callbacks require careful thread management; JNI AttachCurrentThread and DetachCurrentThread must be called explicitly when callbacks execute on non-Java threads
• Unsafe memory access and scope-based cleanup — PointerScope provides RAII-like semantics for JVM; understanding scope-based resource management prevents memory leaks when working with off-heap allocations
• Cross-platform binary distribution (multi-arch JAR artifacts) — platform/pom.xml packages native binaries for linux-x86_64, windows-x86_64, macosx-x86_64, etc.; you must understand classifier-based artifact resolution to support multiple platforms
• Function pointers and callback protocols — FunctionPointer maps Java methods to C++ function pointers; understanding calling conventions (cdecl, stdcall, etc.) is essential for event-driven C++ APIs

• bytedeco/javacv — Companion project that uses JavaCPP to expose OpenCV and other computer vision C++ libraries as easy-to-use Java APIs
• bytedeco/tensorflow-java — Builds on top of JavaCPP to provide Java bindings for TensorFlow; demonstrates how to use JavaCPP for deep learning library integration
• java-native-access/jna — Alternative to JavaCPP for JNI; uses dynamic JNI method lookup instead of code generation, lower boilerplate but also lower type safety
• gradle-native-pack/gradle-cpp-plugin — Complementary Gradle plugin for building native C++ artifacts that can be packaged as JavaCPP platform artifacts
• google/jni-bind — Google's modern JNI wrapper (template-based C++); represents an alternative C++-side approach to reducing JNI boilerplate

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 comprehensive unit tests for Pointer and PointerPointer classes

The core Pointer classes (Pointer.java, PointerPointer.java, BytePointer.java, IntPointer.java, etc.) lack dedicated unit tests in src/test. These are fundamental to JavaCPP's functionality, bridging Java and C++. A comprehensive test suite would validate memory management, allocation strategies, and boundary conditions across all pointer types.

• [ ] Create src/test/java/org/bytedeco/javacpp/PointerTest.java with tests for allocation, reallocation, and memory bounds
• [ ] Create src/test/java/org/bytedeco/javacpp/PointerPointerTest.java for nested pointer operations
• [ ] Add parameterized tests covering BytePointer, IntPointer, DoublePointer, CharPointer, ShortPointer, LongPointer, FloatPointer, BoolPointer, BooleanPointer, CLongPointer, and SizeTPointer
• [ ] Test edge cases: zero-size allocations, capacity limits, cross-platform compatibility
• [ ] Integrate tests into pom.xml and CI workflow (.github/workflows/javacpp.yml)

Add GitHub Actions workflow for multi-platform native compilation testing

The existing .github/workflows/javacpp.yml and .travis.yml suggest CI exists, but there's no visible cross-platform native build testing (Windows/Linux/macOS). JavaCPP bridges C++ code, so verifying native compilation on multiple platforms is critical. A dedicated Actions workflow would catch platform-specific compiler issues early.

• [ ] Create .github/workflows/native-build-test.yml with matrix strategy for ubuntu-latest, windows-latest, and macos-latest
• [ ] Add CMake/compiler checks for C++ standard compatibility (C++11, C++14, C++17)
• [ ] Test the OSGI integration build in src/it/osgi with platform-specific native compilation
• [ ] Include artifact uploads for compiled .so/.dll/.dylib files to verify cross-platform output
• [ ] Document platform-specific build requirements in a new NATIVE_BUILD.md guide

Create comprehensive annotation documentation with code examples

JavaCPP has 15+ annotations (Adapter.java, ByRef.java, ByVal.java, MemberGetter.java, etc.) in src/main/java/org/bytedeco/javacpp/annotation/ but no dedicated examples or usage guide. Contributors and users struggle to understand when to use @ByRef vs @ByVal, or how @Adapter chains with @Cast. A structured documentation file with real-world examples would reduce friction.

• [ ] Create docs/ANNOTATIONS_GUIDE.md documenting each of the 15+ annotations with signatures and use cases
• [ ] Create src/test/java/org/bytedeco/javacpp/annotation/AnnotationExamplesTest.java with concrete C++/Java binding examples for each annotation type
• [ ] Add cross-references in README.md linking to the annotation guide for new contributors
• [ ] Include a decision tree flowchart: 'When to use @ByRef, @ByVal, @ByPtr, @ByPtrRef' with performance implications

• Add unit tests for edge cases in PointerPointer.java (test null pointer dereference, bounds checking, and address arithmetic) to improve robustness of nested pointer handling.
• Document the Loader.cacheDirectory and platform-specific JAR structure in a dedicated doc file (currently only in README); add examples showing how to package custom native libraries as platform artifacts.
• Create a test harness in src/test/java that validates JNI method signature generation for all *Pointer types (BoolPointer, CharPointer, SizeTPointer, CLongPointer) against actual compiled C++ symbols to catch signature mismatches early.

JavaCPP is a framework that inherently carries security risks due to its nature as a Java-to-C++ bridge. The main concerns are: (1)

• Medium · Native Code Bridge Security Risks — src/main/java/org/bytedeco/javacpp/Pointer.java, src/main/java/org/bytedeco/javacpp/Loader.java. JavaCPP is a bridge between Java and native C++ code. This introduces potential security risks including: (1) Buffer overflow vulnerabilities in native code could crash the JVM or allow code execution, (2) Memory safety issues in C++ are not caught by Java's garbage collector, (3) Native code may have different security models than Java's sandbox. Fix: Implement strict input validation at the Java-C++ boundary, use memory-safe wrappers, conduct thorough security audits of native code, use address sanitizers and static analysis tools on C++ code, implement bounds checking on all pointer operations.
• Medium · Dynamic Native Library Loading — src/main/java/org/bytedeco/javacpp/Loader.java. The Loader.java class dynamically loads native libraries at runtime. If the library path is not properly validated or if an attacker can control the library search path, they could potentially load malicious native libraries. Fix: Validate all library paths before loading, use absolute paths where possible, set restrictive file permissions on library directories, avoid searching in user-writable directories, implement a whitelist of allowed libraries.
• Medium · Pointer Arithmetic Without Bounds Checking — src/main/java/org/bytedeco/javacpp/Pointer.java, src/main/java/org/bytedeco/javacpp/BytePointer.java. The Pointer class and its variants (BytePointer, IntPointer, etc.) allow direct pointer arithmetic operations. Without proper bounds checking, this could lead to out-of-bounds memory access, information disclosure, or crashes. Fix: Implement bounds checking on all pointer operations, track allocated buffer sizes, validate array indices before access, use container-based abstractions where possible, consider implementing safe pointer wrappers.
• Medium · FunctionPointer Callback Security — src/main/java/org/bytedeco/javacpp/FunctionPointer.java. FunctionPointer.java allows creating callbacks to Java code from native code. Malicious native code could invoke callbacks with unexpected arguments, causing crashes or exploiting callback implementation vulnerabilities. Fix: Validate all arguments passed to callbacks, implement type checking and sanitization, limit the privileges of callback functions, use try-catch blocks to prevent exceptions from propagating to native code, document callback security requirements clearly.
• Low · Incomplete Maven POM Configuration — platform/pom.xml. The provided pom.xml snippet appears truncated (property tag cut off at 'javacpp.platform.extensio'). This could indicate a malformed build configuration that might be exploited or cause unexpected behavior. Fix: Ensure all XML files are well-formed and complete, validate POM syntax before committing, use Maven validation plugins in CI/CD pipeline, review all build configuration for typos or incomplete properties.
• Low · Missing Security-Related Annotations Documentation — src/main/java/org/bytedeco/javacpp/annotation/. Multiple security-sensitive annotations exist (@Cast, @Const, @Raw, etc.) but their security implications are not clearly documented in the provided file structure. Developers might misuse these annotations, leading to security issues. Fix: Add comprehensive security documentation for all annotations, particularly regarding memory safety and native code interaction, include examples of secure and insecure usage patterns, create security guidelines for JavaCPP usage.
• Low · Insufficient Null/Safety Checks in Type Conversion — src/main/java/org/bytedeco/javacpp/PointerPointer.java, src/main/java/org/bytedeco/javacpp/annotation/Cast.java. Pointer type conversions and casting operations may not perform sufficient null or type safety checks, potentially leading to type confusion or null pointer dereferences. Fix: Add null checks before all pointer dereferences, validate type conversions, use generics where possible to enforce type safety, implement defensive copying for sensitive data transfers.

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.