Skip to content

installation.md

Latest commit

 

History

History
269 lines (202 loc) · 6.81 KB

installation.md

File metadata and controls

269 lines (202 loc) · 6.81 KB
Raw

Build and Execution Guide

Table of Contents

  1. Prerequisites
  2. Build Options
  3. Package Installation
  4. Dependencies
  5. Running PerlOnJava
  6. Database Integration
  7. Build Notes
  8. Java Library Upgrades
  9. Using Configure.pl
  10. Troubleshooting

Prerequisites

  • JDK 22 or later
  • Maven, or the included Gradle wrapper (recommended)
  • Optional: JDBC drivers for database connectivity

Build Options

Using Make

The project includes a Makefile that wraps Gradle commands for a familiar build experience:

make          # same as 'make build'
make build    # builds the project and runs unit tests
make test     # runs fast unit tests
make clean    # cleans build artifacts
make deb      # creates a Debian package (Linux only)

Using Maven

mvn clean package

Using Gradle

./gradlew clean build

Package Installation

Debian Package

For Debian-based systems (Ubuntu, Debian, Mint, etc.), you can create and install a .deb package:

Build the package:

make deb

This creates a Debian package in build/distributions/ with:

  • PerlOnJava installed under /opt/perlonjava/
  • jperl, jcpan, jperldoc, and jprove linked into /usr/local/bin/
  • All dependencies bundled
  • Systemwide availability

Install the package:

sudo dpkg -i build/distributions/perlonjava_*.deb

Usage after installation:

# jperl is now available systemwide
jperl -E 'say "Hello World"'
jperl myscript.pl

# No need for ./jperl - it's in your PATH

Uninstall:

sudo dpkg -r perlonjava

Benefits of Debian package:

  • Clean installation and removal
  • Systemwide availability (no need for ./jperl)
  • Automatic dependency tracking
  • Integrates with system package manager
  • Can be distributed to other Debian-based systems

Dependencies

  • JUnit: For testing
  • ASM: For bytecode manipulation
  • ICU4J: For Unicode support
  • SnakeYAML Engine: for YAML support

Running PerlOnJava

Platform-Specific Instructions

Unix/Linux/Mac:

./jperl -E 'print "Hello World"'
./jperl myscript.pl

Windows:

jperl -E "print 'Hello World'"
jperl myscript.pl

Common Options

  • -I lib: Add library path
  • --debug: Enable debug output
  • --help: Show all options

Database Integration

Adding JDBC Drivers

  1. Using Configure.pl:
./Configure.pl --search mysql-connector-java
  1. Using Java classpath (shown in platform-specific examples above)

Database Connection Example

SQLite is bundled with PerlOnJava — no additional installation needed:

use DBI;
my $dbh = DBI->connect("dbi:SQLite:dbname=:memory:", "", "");
$dbh->do("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)");

For other databases, add JDBC drivers via CLASSPATH or Configure.pl (see below).

See Database Access Guide for detailed connection examples and supported databases.

Build Notes

  • Maven builds use maven-shade-plugin for creating the shaded JAR
  • Gradle builds use the Shadow plugin
  • Both configurations target Java 22

Java Library Upgrades

Maven:

mvn versions:use-latest-versions.

Gradle:

./gradlew useLatestVersions.

Using Configure.pl

The Configure.pl script manages configuration settings and dependencies for PerlOnJava.

Run Configure.pl directly from the repository root. It uses the system Perl specified by its shebang and requires the Perl modules imported at the top of the script.

Common Tasks

View current configuration:

./Configure.pl

Add JDBC driver (search):

./Configure.pl --search mysql
make  # Rebuild to include driver

Add JDBC driver (direct):

./Configure.pl --direct com.mysql:mysql-connector-j:8.2.0
make  # Rebuild to include driver

Update configuration:

./Configure.pl -D version=5.44.0

Upgrade all dependencies:

./Configure.pl --upgrade

Available Options

  • -h, --help - Show help message
  • -D key=value - Set configuration value
  • --search keyword - Search Maven Central for artifacts
  • --direct group:artifact:version - Add dependency with Maven coordinates
  • --verbose - Enable verbose output
  • --upgrade - Upgrade dependencies to latest versions

Important Notes

  1. Rebuild required: After adding dependencies with --search or --direct, you must run make to download and bundle them
  2. Alternative approach: Instead of bundling drivers, you can use CLASSPATH: 
    CLASSPATH=/path/to/driver.jar ./jperl script.pl

→ See Configure.pl Reference for complete documentation

Troubleshooting

"Unsupported class file major version" errors

Problem: When building with Java 25 or later, you see:

BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 69
> Unsupported class file major version 69

Cause: The build is using an older Gradle installation that cannot run on your JDK.

Solution: Use the repository's Gradle wrapper instead of a system-installed Gradle. Confirm the configured version, then rebuild:

./gradlew --version
make wrapper
make clean
make

On Windows, use gradlew.bat --version. The wrapper version is defined in gradle/wrapper/gradle-wrapper.properties; that file is the source of truth.

Java Version Compatibility

PerlOnJava compiles for Java 22 and requires JDK 22 or later. Use the included wrapper so the Gradle version stays aligned with the project. For compatibility details beyond the checked-in wrapper, consult Gradle's Java compatibility matrix.

"JAVA_HOME is not set"

Make sure you have a JDK installed and JAVA_HOME is set:

# Linux/macOS (add to ~/.bashrc or ~/.zshrc)
export JAVA_HOME=/path/to/jdk

# Windows (System Properties > Environment Variables)
set JAVA_HOME=C:\path\to\jdk

Build Takes Too Long

The default make target builds the runnable JAR and runs the fast unit suite. For a targeted test during development, run the relevant .t file with ./jperl, then run make before committing.