J2C Java to C++

J2C Modern Edition

J2C translates Java source code to C++. This repository packages the standalone command-line translator and the J2C Java to C++ VS Code extension. It is a modernized continuation of arnetheduck/j2c, whose original Eclipse plugin remains in that repository.

Preview: J2C is a source translator, not a complete Java compiler or

runtime. Java feature support is incremental. Generated C++ may need manual

changes and a compatible implementation of Java runtime behavior. Do not

assume that arbitrary Java programs compile or preserve all JVM semantics.

Requirements

• Java 11 or newer to run the CLI and VS Code extension.
• Maven to build the CLI from source.
• A C++20 compiler for generated Makefiles and C++ output.
• Node.js 22 or newer and npm to package the VS Code extension.

CLI

Build the executable JAR from the repository root:

mvn package

Create an output directory and translate a Java file or source directory:

mkdir generated

java -jar target/j2c-cli.jar \ --output generated \ --sourcepath test/src \ test/src/se/arnetheduck/j2c/test/Hello.java

Use the platform path separator between multiple source roots or classpath entries (; on Windows, : on macOS/Linux). Source paths help resolve Java source dependencies; classpath entries should identify dependency JARs or class directories. If --sourcepath is omitted, J2C infers roots from the selected inputs.

The --sealed-types policy defaults to advisory. Sealed declarations are translated using ordinary C++ inheritance and generated comments list permitted direct subtypes; C++ does not enforce Java's `permits` restriction. Choose --sealed-types reject to stop translation when sealed or non-sealed declarations are encountered.

Additional optional arguments are --classpath , --name , --sealed-types advisory|reject, and --encoding . Java sources are read as UTF-8 unless --encoding says otherwise; generated C++ is always written as UTF-8.

Translate against the J2C runtime so the program runs without writing any C++:

java -jar target/j2c-cli.jar --runtime bundled --output generated test/runtime/hello

make -C generated all mains && generated/bin/Hello

--runtime bundled uses the runtime packaged in the CLI JAR (and in the VS Code extension), so no repository checkout is needed: on first use it is extracted to ~/.j2c/cache/runtime- - (or J2C_CACHE_DIR), reused while its files are intact, and replaced when they are not. --runtime uses another runtime directory, such as a checkout's runtime/ (name a directory called bundled as ./bundled). Without --runtime, the default, java.* comes from the running JDK and every JDK class is a stub that fails at run time; with it, java.* comes from the runtime, so JDK classes it does not provide are compile errors that --check lists. See runtime/README.md for what it covers.

j2c run translates, builds and runs a program in one step, runs the same main class on the JVM, and compares the two:

java -jar target/j2c-cli.jar run --output generated test/runtime/hello -- one "two words"

java -jar target/j2c-cli.jar run --output generated --format json --main Stdin --stdin test/runtime/stdin/input.txt test/runtime/stdin test/runtime/hello

It translates against the runtime (--runtime, default bundled) with --line-directives, builds the main class's binary (make bin/ , run as j2c build runs make, so a failed build reports the compiler's errors at their Java lines), runs it in a fresh working directory with the arguments after -- and the bytes of --stdin as standard input, compiles the same sources with the javac of the JDK running J2C, and runs the class with java (in WSL when the build ran there: --java , else J2C_WSL_JAVA, else java on WSL's PATH, else the Windows JDK running J2C, with a note). It compares standard output, standard error without the JVM's stack frames, and the exit code, and prints the C++ program's output, how each run ended and the first line that differs. --main chooses among several classes with a main method, --no-compare only runs the C++ program, --timeout (default 60, 0 for none) stops each run and everything it started, and --output-limit (default 20000) caps the output reported for each stream. With --format json the result has status (ok, differs, failed, crashed, timeout or build-failed), cpp and jvm (exit code, signal, timedOut, durationMillis, stdout and stderr with their byte counts and whether they were truncated), comparison (equal, differs or skipped, with firstDifference of each stream: line, cpp and jvm) and build.

Check whether code can be translated before writing anything:

java -jar target/j2c-cli.jar --check --sourcepath src/main/java src/main/java

--check takes the same inputs as a translation but no --output. It prints every compile error and unsupported construct in the selected files as file:line: message, followed by a summary per kind, and writes no files. Select a source root to check a whole project. --version prints the CLI version.

Maven and Gradle projects

Pass a project directory (one with a pom.xml, build.gradle(.kts) or settings.gradle(.kts)) and J2C sets itself up from the build:

java -jar target/j2c-cli.jar --check .

java -jar target/j2c-cli.jar --tests --output generated .

• Source roots: Maven's src/main/java (or ) of every module listed in , plus roots added by build-helper-maven-plugin; Gradle's src/main/java of the root project and each included subproject, or the source sets Gradle reports. With --tests, the test roots (src/test/java, ) too.
• Class path: J2C runs the project's wrapper (mvnw, gradlew) or else mvn/gradle from the PATH. Maven runs dependency:build-classpath (compile scope, or test scope with --tests); in a multi-module build whose modules depend on each other it also runs the compile phase with compilation skipped, so plugins bound to earlier phases run. Gradle gets an init script (--init-script) that prints compileClasspath and testCompileClasspath, retried with --offline if it fails. The build may download dependencies. Other modules' output is left out, because their sources are translated.
• What was detected, and the command run, is printed to stderr, and is in the JSON output as projects. Resolved class paths are cached in ~/.j2c/cache (or J2C_CACHE_DIR), keyed by a hash of the build files.
• If the tool is missing or fails, J2C still uses the source roots and reports the warning J2C-PROJECT-CLASSPATH-UNRESOLVED (in warnings in JSON); dependency types then fail to resolve.

--no-build-tool never runs Maven or Gradle (a cached class path is still used). --project none turns detection off, and --project uses that directory's build for other inputs, such as one file in it. Detection only looks at the input directories themselves, never at their parents.

The output directory must be empty or earlier J2C output, which is marked with a .j2c-output file. Translation first moves the directory's current contents to a backup in the temporary folder, so J2C refuses other non-empty directories unless you pass --force. Every selected file is checked before that: when one has problems, the translation fails with all of them and leaves the directory as it was. The build's objects and libraries (obj/ and bin/) stay, and a generated file that comes out the same keeps its earlier modification time, so make (and j2c build, j2c run and j2c test) compiles again only what changed: after the first build, a run against the runtime no longer compiles it all again. Changing the compiler or its flags (CXX, CFLAGS) compiles everything again.

Files that are only dependencies (found on the source path, not selected) and do not compile are translated like library classes, as a header and stubs without an implementation, with the warning J2C-DEPENDENCY-ERRORS (in warnings in JSON) instead of an error.

Each problem has a stable ID (such as J2C-LAMBDA-ANONYMOUS-THIS). j2c explain describes it and how to fix it; j2c explain lists them all. --format json makes translation and --check print a single JSON object (problems with ID, file, line, column, message and hint; or the generated files). j2c capabilities prints the supported features and limitations as JSON.

Some problems have a mechanical fix, which j2c fix makes in the Java source:

java -jar target/j2c-cli.jar fix src/main/java           # preview as a unified diff

java -jar target/j2c-cli.jar fix --apply src/main/java # write the fixes

It takes the same inputs and options as --check (except --output, --name and --force). The preview prints a diff on stdout that git apply accepts; --apply writes the fixes, checks again, and repeats until no fixable problem is left. Fixes exist for J2C-LAMBDA-ANONYMOUS-THIS (a var self = this; local used in the lambda), J2C-LAMBDA-INTERFACE-SUPER (the Iface.super.m() call moved into a private method), J2C-PATTERN-OUTSIDE-METHOD (the field initializer moved into a private method), J2C-TEST-TIMEOUT (the timeout removed) and J2C-TEST-PRIVATE-METHOD (private removed). With --format json, every problem lists its fixes as exact edits (file, a range with 1-based line and column, and newText).

j2c report assesses a migration before you start it:

java -jar target/j2c-cli.jar report . > migration-report.md      # Markdown

java -jar target/j2c-cli.jar report --format json src/main/java # JSON

It takes the same inputs and options as --check (and --runtime) and shows the files, types and methods that translate as they are (no problem from --check lies within them), the blockers by problem ID and by package with their top locations and how many j2c fix can fix, test-feature blockers with --tests, the JDK types and members the code uses compared with what the J2C runtime provides (the rest would be stubs that fail at run time), and next steps.

--line-directives adds #line directives to the generated C++, so compiler errors and debuggers (gdb: break Foo.java:21, list) refer to Java files and lines. Each C++ line maps to the Java statement it came from, also in lambdas; generated boilerplate keeps its C++ file and line. Paths in the directives are relative to the output directory, where make runs. Without the option the generated files are unchanged.

j2c build compiles translated code and reports the compiler's errors at their Java lines:

java -jar target/j2c-cli.jar build --output build/cpp src/main/java  # translate with directives, then make

java -jar target/j2c-cli.jar build --output build/cpp --format json # build earlier J2C output

It runs make -k in the output directory (in WSL on Windows when make is not on the PATH; --wsl auto|always|never, --wsl-distro , --make , --target , --jobs , or the variables J2C_MAKE, J2C_WSL and J2C_WSL_DISTRO), parses GCC and Clang diagnostics, and prints each at its Java file and line with its C++ location. A diagnostic in generated code outside any Java statement is reported in C++ with the nearest Java line before it. With --format json the result has status, exitCode, diagnostics (severity, message, java, cpp, mapped, notes, includedFrom), summary and the end of the log.

The CLI exits with status 0 on success (or a clean check), 1 when translation fails or a check finds problems, and 2 for invalid arguments. j2c build exits with 0 when