Merge pull request #968 from fglock/fix/cpan-compiler-tooling-batch

Fix jcpan compiler and tooling blockers

Author: fglock

dev/design/jcpan-compiler-tooling-batch-20260815.md

@@ -0,0 +1,72 @@
+# jcpan Compiler and Tooling Batch
+
+## Goal
+
+Remove reusable compiler/runtime/tooling blockers found while testing:
+
+- `Dist::Zilla::Plugin::Manifest::Read`
+- `Plack::App::Proxy::Selective`
+- `Text::MetaText`
+- `Test::Class::Filter::Tags`
+- `Catmandu::Exporter::HTML`
+- `Map::Tube::Sydney`
+- `App::SQLiteUtils`
+- `Char::Latin2`
+
+Distributions which also fail under system Perl are recorded and excluded from
+PerlOnJava-specific fixes.
+
+## Progress Tracking
+
+### Current Status: implementation complete (2026-08-16)
+
+### Completed Phases
+
+- [x] Phase 1: System-Perl eligibility baseline (2026-08-15)
+  - `Dist::Zilla::Plugin::Manifest::Read` passes system Perl.
+  - `Plack::App::Proxy::Selective`, `Text::MetaText`,
+    `Test::Class::Filter::Tags`, `Catmandu::Exporter::HTML`, and
+    `Map::Tube::Sydney` fail in system Perl or in their prerequisite closure and
+    require no PerlOnJava-specific distribution workaround.
+  - `App::SQLiteUtils` is excluded because its required system-Perl closure
+    fails in Data::Sah/lib::filter and cannot provide a valid comparison.
+  - `Char::Latin2` passes system Perl (210 files / 5,725 tests).
+
+- [x] Phase 2: Shared Dist::Zilla blockers (2026-08-15)
+  - Added structural translation for supported `(*PRUNE)` regex forms.
+  - Made the Unix and Windows launchers cache and reuse an absolute Java path,
+    allowing nested `$^X` calls after build tools replace `PATH`.
+  - Preserved Perl's `((), @array)` iteration-list snapshot idiom in the parser
+    and both execution backends.
+  - Made direct array iteration follow the live array length when the loop body
+    mutates its structure.
+  - `Dist::Zilla::Plugin::Manifest::Read` now passes 2 files / 8 tests with its
+    complete CPAN prerequisite path.
+  - Files: `jperl`, `jperl.bat`, `RegexPreprocessor.java`, `ParseInfix.java`,
+    `EmitLiteral.java`, `BytecodeCompiler.java`, `InlineOpcodeHandler.java`,
+    `RuntimeArray.java`, `RuntimeList.java`, and focused tests.
+
+- [x] Phase 3: Char::Latin2 compatibility and final validation (2026-08-16)
+  - Reused the established Char::Latin7/Char::Windows1258 compatibility design
+    for the historical `jperl` executable-name collision and Perl regex-code
+    source transformer.
+  - Registered the generic patch through CPAN bootstrap configuration; no
+    installed-user preference edits are required.
+  - `Char::Latin2` passes PerlOnJava (210 files / 5,725 tests).
+  - A clean `jcpan -t Dist::Zilla::Plugin::Manifest::Read` passes (2 files / 8
+    tests) and exits successfully.
+  - Full `make` passes.
+
+### Next Steps
+
+1. Monitor pull-request CI.
+2. Merge after review when CI is green.
+
+### Open Questions
+
+- None.
+
+## Related Skills and Documents
+
+- `.agents/skills/debug-perlonjava/SKILL.md`
+- `AGENTS.md`

jperl

@@ -6,8 +6,15 @@
 # Repository: github.com/fglock/PerlOnJava
 #
 
-# Get the directory where this script is located, resolving symlinks
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+# Get the directory where this script is located without depending on the
+# external dirname utility. CPAN build tools can intentionally replace PATH
+# with prerequisite script directories before launching a nested $^X.
+SCRIPT_SOURCE="${BASH_SOURCE[0]}"
+case "$SCRIPT_SOURCE" in
+    */*) SCRIPT_PARENT="${SCRIPT_SOURCE%/*}" ;;
+    *)   SCRIPT_PARENT="." ;;
+esac
+SCRIPT_DIR="$(cd "$SCRIPT_PARENT" && pwd -P)"
 
 # Get the full path to this script to set $^X correctly
 JPERL_PATH="$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "$SCRIPT_DIR/jperl")"
@@ -58,11 +65,24 @@ JVM_OPTS="--enable-native-access=ALL-UNNAMED"
 
 # Java 23+ warns about sun.misc.Unsafe usage (JEP 471). Add flag to suppress
 # warnings from transitive libraries (ASM, ICU4J, etc.) that still use it.
-if ! command -v java >/dev/null 2>&1; then
+JAVA_BIN="${PERLONJAVA_JAVA_BIN:-}"
+if [ -z "$JAVA_BIN" ] && [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ]; then
+    JAVA_BIN="$JAVA_HOME/bin/java"
+fi
+if [ -z "$JAVA_BIN" ]; then
+    JAVA_BIN="$(command -v java 2>/dev/null || true)"
+fi
+if [ -z "$JAVA_BIN" ] || [ ! -x "$JAVA_BIN" ]; then
     echo "ERROR: PerlOnJava requires Java 24 or later; java was not found in PATH." >&2
     exit 1
 fi
-JAVA_VERSION=$(java -version 2>&1 | head -1 | sed 's/.*version "\([0-9]*\).*/\1/')
+export PERLONJAVA_JAVA_BIN="$JAVA_BIN"
+JAVA_VERSION_OUTPUT="$("$JAVA_BIN" -version 2>&1)"
+if [[ "$JAVA_VERSION_OUTPUT" =~ version\ \"([0-9]+) ]]; then
+    JAVA_VERSION="${BASH_REMATCH[1]}"
+else
+    JAVA_VERSION=""
+fi
 if ! [[ "$JAVA_VERSION" =~ ^[0-9]+$ ]] || [ "$JAVA_VERSION" -lt 24 ]; then
     echo "ERROR: PerlOnJava requires Java 24 or later (found: ${JAVA_VERSION:-unknown})." >&2
     exit 1
@@ -77,4 +97,4 @@ if [ -n "$CLASSPATH" ]; then
 else
     CP="$PERLONJAVA_CP"
 fi
-exec java $JVM_OPTS ${JPERL_OPTS} -cp "$CP" org.perlonjava.app.cli.Main "$@"
+exec "$JAVA_BIN" $JVM_OPTS ${JPERL_OPTS} -cp "$CP" org.perlonjava.app.cli.Main "$@"

jperl.bat

@@ -32,15 +32,24 @@ rem Override via `JPERL_OPTS=-Xmx<size>` in the environment if needed.
 
 rem Java 23+ warns about sun.misc.Unsafe usage (JEP 471). Add flag to suppress
 rem warnings from transitive libraries (ASM, ICU4J, etc.) that still use it.
+if not defined PERLONJAVA_JAVA_BIN (
+    for /f "delims=" %%j in ('where java 2^>nul') do if not defined PERLONJAVA_JAVA_BIN set "PERLONJAVA_JAVA_BIN=%%j"
+)
+if not defined PERLONJAVA_JAVA_BIN (
+    echo ERROR: PerlOnJava requires Java 24 or later; java was not found in PATH. 1>&2
+    exit /b 1
+)
 set JAVA_VERSION=
-for /f "tokens=3" %%v in ('java -version 2^>^&1 ^| findstr /i "version"') do (
+rem CALL is required when a quoted absolute executable starts the command
+rem parsed by FOR /F; without it cmd.exe treats the nested quote as syntax.
+for /f "tokens=3" %%v in ('call "%PERLONJAVA_JAVA_BIN%" -version 2^>^&1') do if not defined JAVA_VERSION (
     for /f "tokens=1 delims=." %%m in ("%%~v") do (
         set JAVA_VERSION=%%m
         if %%m GEQ 23 set JVM_OPTS=%JVM_OPTS% --sun-misc-unsafe-memory-access=allow
     )
 )
 if not defined JAVA_VERSION (
-    echo ERROR: PerlOnJava requires Java 24 or later; java was not found in PATH. 1>&2
+    echo ERROR: PerlOnJava requires Java 24 or later; Java version could not be determined. 1>&2
     exit /b 1
 )
 if %JAVA_VERSION% LSS 24 (
@@ -63,4 +72,4 @@ if exist "%SCRIPT_DIR%target\perlonjava-5.44.0.jar" (
 )
 
 rem Launch Java
-java %JVM_OPTS% %JPERL_OPTS% -cp "%CLASSPATH%;%PERLONJAVA_CP%" org.perlonjava.app.cli.Main %*
+"%PERLONJAVA_JAVA_BIN%" %JVM_OPTS% %JPERL_OPTS% -cp "%CLASSPATH%;%PERLONJAVA_CP%" org.perlonjava.app.cli.Main %*

src/main/java/org/perlonjava/backend/bytecode/BytecodeCompiler.java

@@ -5554,7 +5554,11 @@ public void visit(ArrayLiteralNode node) {
         int listReg = allocateRegister();
         emit(Opcodes.CREATE_LIST);
         emitReg(listReg);
-        emit(node.elements.size()); // count
+        // A negative encoded count asks CREATE_LIST to flatten aggregate
+        // membership immediately. This preserves Perl's `((), @array)` copy
+        // idiom without cloning the scalar aliases themselves.
+        boolean forceListSnapshot = Boolean.TRUE.equals(node.getAnnotation("forceListSnapshot"));
+        emit(forceListSnapshot ? -node.elements.size() - 1 : node.elements.size()); // count
 
         // Emit register numbers for each element
         for (int elemReg : elementRegs) {
@@ -6986,7 +6990,7 @@ public void visit(ListNode node) {
             int listReg = allocateRegister();
             emit(Opcodes.CREATE_LIST);
             emitReg(listReg);
-            emit(1); // count = 1
+            emit(Boolean.TRUE.equals(node.getAnnotation("forceListSnapshot")) ? -2 : 1); // count = 1
             emitReg(elemReg);
             lastResultReg = listReg;
             return;

src/main/java/org/perlonjava/backend/bytecode/InlineOpcodeHandler.java

@@ -904,6 +904,10 @@ public static int executeScalarToList(int[] bytecode, int pc, RuntimeBase[] regi
     public static int executeCreateList(int[] bytecode, int pc, RuntimeBase[] registers) {
         int rd = bytecode[pc++];
         int count = bytecode[pc++];
+        boolean forceListSnapshot = count < 0;
+        if (forceListSnapshot) {
+            count = -count - 1;
+        }
 
         if (count == 0) {
             // Empty list - fastest path
@@ -912,15 +916,23 @@ public static int executeCreateList(int[] bytecode, int pc, RuntimeBase[] regist
             // Single element - avoid loop overhead
             int rs = bytecode[pc++];
             RuntimeList list = new RuntimeList();
-            list.add(registers[rs]);
+            if (forceListSnapshot) {
+                list.addSnapshot(registers[rs]);
+            } else {
+                list.add(registers[rs]);
+            }
             registers[rd] = list;
         } else {
             // Multiple elements - preallocate and populate
             RuntimeList list = new RuntimeList();
 
             for (int i = 0; i < count; i++) {
                 int rs = bytecode[pc++];
-                list.add(registers[rs]);
+                if (forceListSnapshot) {
+                    list.addSnapshot(registers[rs]);
+                } else {
+                    list.add(registers[rs]);
+                }
             }
 
             registers[rd] = list;

src/main/java/org/perlonjava/backend/jvm/EmitLiteral.java

@@ -512,6 +512,7 @@ public static void emitList(EmitterVisitor emitterVisitor, ListNode node) {
         // Stack: []
 
         // Populate the list with elements
+        boolean forceListSnapshot = Boolean.TRUE.equals(node.getAnnotation("forceListSnapshot"));
         for (Node element : node.elements) {
             // Generate code for the element with an empty operand stack so non-local control flow
             // cannot leak extra operands.
@@ -524,7 +525,12 @@ public static void emitList(EmitterVisitor emitterVisitor, ListNode node) {
             emitterVisitor.ctx.javaClassInfo.releaseSpillRef(elementRef);
 
             // Add the element to the list
-            addElementToList(mv, element, contextType);
+            if (forceListSnapshot) {
+                mv.visitMethodInsn(Opcodes.INVOKEVIRTUAL, RuntimeDescriptorConstants.LIST_CLASS,
+                        "addSnapshot", "(" + RuntimeDescriptorConstants.BASE_TYPE + ")V", false);
+            } else {
+                addElementToList(mv, element, contextType);
+            }
             // Stack: []
         }
 

src/main/java/org/perlonjava/frontend/parser/ParseInfix.java

@@ -206,6 +206,9 @@ public static Node parseInfixOperation(Parser parser, Node left, int precedence)
         switch (token.text) {
             case ",":
             case "=>":
+                boolean forceListSnapshot = token.text.equals(",")
+                        && left instanceof ListNode leftList
+                        && leftList.elements.isEmpty();
                 if (token.text.equals("=>") && left instanceof IdentifierNode) {
                     // Autoquote - Convert IdentifierNode to StringNode.
                     // Strip trailing "::" so that `Foo::Bar:: => ...` autoquotes to "Foo::Bar",
@@ -222,7 +225,15 @@ public static Node parseInfixOperation(Parser parser, Node left, int precedence)
                     return ListNode.makeList(left);
                 }
                 right = parser.parseExpression(precedence);
-                return ListNode.makeList(left, right);
+                ListNode combined = ListNode.makeList(left, right);
+                if (forceListSnapshot) {
+                    // Perl code uses `((), @array)` to force a structural copy of
+                    // the iteration list while retaining aliases to its scalar
+                    // elements.  Do not erase that distinction when flattening
+                    // the comma expression into a ListNode.
+                    combined.setAnnotation("forceListSnapshot", true);
+                }
+                return combined;
             case "?":
                 // Handle ternary operator
                 Node middle = parser.parseExpression(0);