RPNXCortado

(This project is AI generated)

RPNXCortado

RPNXCortado is a C++23 toolkit for lossless JVM class-file parsing, serialization, validation, transformation, generation, and JAR packaging. It targets Java SE 26 class files (major versions 45 through 70), follows the RPNX System Standards, and exposes metadata on owning aggregates with RPNX_MEMBER_METADATA.

The exact wire model includes every constant-pool entry, every defined JVM instruction, the legacy jsr/ret forms, the three named reserved opcodes, and all 30 predefined attributes. Known attributes have context-specific variants, so a standard attribute cannot be placed in an invalid field, method, class, Code, or record-component context through the typed API. Unknown attributes retain their original name index and payload and remain valid in strict mode.

Recursive signature, descriptor, and annotation nodes use heap-backed rpnx::variant. This permits the recursive grammar without adding an artificial empty state; ordinary non-recursive discriminated domains use std::variant. Actual JVM quantities such as counts, lengths, stack sizes, local indexes, dimensions, and constant-pool slot counts remain integers.

Public interface

#include <rpnx/cortado/builders.hpp>
#include <rpnx/cortado/jar.hpp>
#include <rpnx/cortado/validation.hpp>
 
std::vector<std::byte> class_bytes = rpnx::cortado::serialize_class_file(class_model);
rpnx::cortado::class_file decoded_class = rpnx::cortado::deserialize_class_file(class_bytes);
rpnx::cortado::validation_report report = rpnx::cortado::validate_class_file(decoded_class);
 
std::vector<std::byte> jar_bytes = rpnx::cortado::serialize_jar(archive);
rpnx::cortado::jar_file decoded_jar = rpnx::cortado::deserialize_jar(jar_bytes);
 
rpnx::cortado::serialize_iter(class_model, std::back_inserter(class_bytes));
rpnx::cortado::deserialize_iter(decoded_class, class_bytes.cbegin(), class_bytes.cend());

The class-file and bytecode iterator overloads follow the serial4 convention and accept the same strict/tooling options as the span APIs. Strict mode rejects malformed structures, reserved instructions, invalid version combinations, incorrect constant kinds, misplaced/cardinality-invalid standard attributes, bad descriptors/signatures, invalid branch targets, and invalid stack-map structures. Tooling mode preserves an entire method body as raw_code if an unknown opcode prevents reliable instruction-boundary recovery. It never silently rewrites the body.

constant_pool_builder performs deterministic first-insertion interning. code_builder owns symbolic labels and instructions, selects compact or wide local forms, selects ldc width, widens goto/jsr, rewrites far conditionals, stabilizes switch alignment, computes max_stack and max_locals, and generates verifier frames. It also resolves symbolic exception regions, line numbers, and local scopes. Reference merges request a class_hierarchy_resolver_ref only when two distinct reference types actually require hierarchy knowledge. Exact manual stack maps and max values are available as explicit bypasses; automatic analysis rejects legacy subroutine bytecode.

The exact instruction variant has compile-time uniqueness and coverage assertions for all 205 defined or reserved opcode values. Symbolic mnemonic conveniences cover no-operand instructions, branches, compact/wide locals, field and method references, classes, strings, and switches; the typed append(instruction) operation covers every exact encoding.

JAR support covers ordinary non-Zip64 archives using stored or raw-DEFLATE entries and validates local headers, declared sizes, and CRC-32 values while reading. Encrypted, split, and Zip64 archives are rejected explicitly. Configurable resource limits bound untrusted input.

Hello world example

The rpnx_cortado_generate_hello_world example uses class_file_builder and code_builder to write both a class file and an executable JAR:

./rpnx_cortado_generate_hello_world ./hello-world-output
java -Xverify:all -jar ./hello-world-output/hello-world.jar

The Java process prints hello world and exits normally. The generated class can also be run directly with java -cp ./hello-world-output HelloWorld.

Build and test

The RPNXCortado CMake package exports RPNX::cortado from both build and install trees. It requires RPNXMetalib, RPNXDataStructures, RPNXCompress, and a C++23 toolchain. From the included cbuild workspace:

cd dev-workspace
cbuild test -c Debug -t cortado

When a JDK is available, the Debug suite compiles representative Java sources, requires byte-identical parse/serialize round trips, inspects the output with javap -verbose, and executes ordinary and modular fixtures with java -Xverify:all. The final safety configuration is:

cbuild test -c DebugASAN -t cortado

API documentation

The reference includes an architecture and data-model guide, a getting-started guide, the complete public-header API, and the generated Hello World example. To generate the HTML reference directly with Doxygen:

doxygen Doxyfile

Open build/documentation/index.html after generation completes. CMake users can alternatively enable RPNX_CORTADO_BUILD_DOCUMENTATION and build the cortado_documentation target. Documentation generation is opt-in and does not add Doxygen as a dependency for normal builds or package consumers.