Skip to content

Add XS fallback mechanism and DateTime Java implementation#337

Merged
fglock merged 13 commits into
masterfrom
feature/xs-fallback-datetime
Mar 19, 2026
Merged

Add XS fallback mechanism and DateTime Java implementation#337
fglock merged 13 commits into
masterfrom
feature/xs-fallback-datetime

Conversation

@fglock
Copy link
Copy Markdown
Owner

@fglock fglock commented Mar 19, 2026

Summary

This PR enables CPAN modules with XS code to work on PerlOnJava through automatic fallback mechanisms.

Core Changes

  1. XSLoader compatibility - Error message now matches /loadable object/ pattern that modules expect for PP fallback
  2. MakeMaker handling - Always installs .pm files for XS modules (with warning); runtime decides fallback
  3. Version checking - XSLoader warns (but continues) if Java XS version differs from requested version

DateTime Java Implementation

Full Java XS implementation using java.time APIs:

  • JulianFields.RATA_DIE for Rata Die calculations
  • Year.isLeap() for leap year checking
  • Custom leap seconds table (Java uses smoothed leap seconds)
  • All 10 XS functions implemented

Documentation

  • New: docs/reference/xs-compatibility.md - Central reference for XS module compatibility
  • Updated: docs/guides/using-cpan-modules.md - Added jcpan, XS fallback mechanism
  • Updated: Cross-references between all related docs

Files Changed

Java:

  • XSLoader.java - Error message + version checking
  • DateTime.java - New Java XS implementation

Perl:

  • MakeMaker.pm - Simplified XS module handling

Docs:

  • docs/reference/xs-compatibility.md (new)
  • docs/guides/using-cpan-modules.md
  • docs/guides/module-porting.md
  • docs/reference/feature-matrix.md
  • docs/README.md

How It Works

XSLoader::load('Module::Name', '1.00')
  ├─→ Java class found?
  │     ├─→ Version check (warn if mismatch)
  │     └─→ Use Java implementation (fast path)
  └─→ Not found?
        └─→ Error matches 'loadable object'
              └─→ Module catches error → loads PP fallback

Test Plan

  • XSLoader error matches fallback pattern
  • Version mismatch produces warning but continues
  • Modules without XS_VERSION work silently
  • DateTime Java XS loads and works
  • All unit tests pass (make)

Generated with Devin

fglock and others added 8 commits March 19, 2026 13:34
This enables CPAN modules with XS code to work on PerlOnJava:

1. XSLoader: Error message now matches /loadable object/ pattern
   - Modules like DateTime catch this and use their PP fallback
   - Unmodified .pm files work correctly

2. MakeMaker: Always installs .pm files for XS modules
   - Prints warning that XS cannot be compiled
   - Runtime decides: Java XS → PP fallback → error

3. DateTime.java: Full Java XS implementation
   - Uses java.time.JulianFields.RATA_DIE for Rata Die calculations
   - Uses java.time.Year.isLeap() for leap year checking
   - Custom leap seconds table for _day_length functions
   - All 10 XS functions implemented

Design document: dev/design/xs_fallback.md

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
- Add jcpan as the primary installation method
- Document the XS fallback mechanism (Java XS -> PP fallback -> error)
- Update built-in Java implementations table
- Clarify module compatibility and troubleshooting
- Remove outdated XS handling information

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
- Add XS_VERSION constant to DateTime.java (1.65)
- XSLoader::load now checks version if provided as second argument
- Warns (to stderr) if major versions differ, but continues loading
- Modules without XS_VERSION skip the check silently
- Compatible versions (same major) produce no warning

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
- Create docs/reference/xs-compatibility.md with:
  - Modules with Java XS implementations
  - Modules with built-in PP fallbacks
  - Guide for adding new Java XS implementations
- Update using-cpan-modules.md to reference the new doc
- Add DateTime to built-in Java implementations table

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
- docs/README.md: Add XS Compatibility to Reference section
- docs/guides/using-cpan-modules.md: Add See Also section
- docs/guides/module-porting.md: Add See Also section
- docs/reference/feature-matrix.md: Link to xs-compatibility.md
- docs/reference/xs-compatibility.md: Expand See Also section

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Socket.java:
- Add SO_ERROR, IPPROTO_IP, IPPROTO_IPV6, IP_TOS, IP_TTL constants
- Add getnameinfo() function
- Use empty prototype '' for constants (fixes parser issue with ternary)

Socket.pm:
- Export new constants and getnameinfo

Net/Ping.pm:
- Import from perl5 core (required by CPAN::Mirrors)
- Added to dev/import-perl5/config.yaml

CPAN/Config.pm (new):
- Default CPAN configuration for PerlOnJava
- Uses ~/.perlonjava/cpan for CPAN home (consistent with other paths)
- Works cross-platform (Windows/Unix)
- No first-time configuration required

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
These modules already have pure Perl fallback when XS is unavailable,
so they do not need protection - they work unmodified in PerlOnJava:
- Unicode/Normalize.pm
- Data/Dumper.pm
- Sys/Hostname.pm

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@fglock fglock force-pushed the feature/xs-fallback-datetime branch from eada4c6 to 1db8a80 Compare March 19, 2026 14:08
fglock and others added 5 commits March 19, 2026 15:11
Create Unix.pm.patch to add jar: path recognition in file_name_is_absolute().
This allows sync.pl to keep the file in sync with upstream while applying
the PerlOnJava-specific modification.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Phase 11 investigation found:
- DateTime fails due to dependency chain issues
- Root cause: ${ $Package::{NAME} } returns empty instead of value
- This blocks Module::Implementation -> Specio -> DateTime
- Also B::Hooks::EndOfScope (XS) blocks namespace::autoclean

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Bug: ${ $Foo::{NAME} } returned empty instead of the variable value.
This blocked Module::Implementation, Specio, and DateTime dependency chain.

Fix: Added GLOB case to scalarDeref() and scalarDerefNonStrict() in
RuntimeScalar.java to return the scalar slot when dereferencing a glob.

Now working:
- Module::Implementation
- Specio
- Params::ValidationCompiler

Still blocked (documented in xsloader.md):
- B::Hooks::EndOfScope (XS module, needs stub)
- namespace::autoclean (depends on B::Hooks::EndOfScope)
- DateTime full install (depends on namespace::autoclean)

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Uses PerlOnJava's existing defer infrastructure:
- DeferBlock wraps callback for scope-exit execution
- DynamicVariableManager manages deferred block stack
- Callbacks execute in LIFO order (same as Perl)

Files added:
- BHooksEndOfScope.java - Java XS implementation
- B/Hooks/EndOfScope.pm - Perl wrapper with XSLoader

Limitation: requires on_scope_end(sub { }) syntax instead of
on_scope_end { } bare block. Parser special-case could fix this.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
on_scope_end { BLOCK } now works correctly with the & prototype.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@fglock fglock merged commit ae43a56 into master Mar 19, 2026
2 checks passed
@fglock fglock deleted the feature/xs-fallback-datetime branch March 19, 2026 14:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant