QUICKSTART.md

Quick Start Guide

Get PerlOnJava running in 5 minutes.

Prerequisites

• Java Development Kit (JDK) 21 or later
• Git for cloning the repository
• Make (optional - can use Gradle directly)

Verify You Have JDK Installed

Check your Java version:

java -version

Should show version 21 or higher.

Important: Check you have the JDK (not just JRE):

javac -version

Should show the same version. If javac: command not found, you need to install a JDK.

Installing JDK:

• Use your system's package manager, or
• Download from a JDK provider (Adoptium, Oracle, Azul, Amazon Corretto, etc.)
• Common package manager commands:
  • macOS: brew install openjdk@21
  • Ubuntu/Debian: sudo apt install openjdk-21-jdk
  • Windows: Use package manager like Chocolatey or Scoop

Installation

1. Clone and Build

git clone https://github.com/fglock/PerlOnJava.git
cd PerlOnJava
make

The make command compiles the project and runs the fast unit tests. The complete build with tests typically completes in ~30 seconds.

Build troubleshooting: See Installation Guide

Debian/Ubuntu users: You can also build and install a .deb package:

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

This installs jperl systemwide. See Installation Guide for details.

2. Verify Installation

Linux/Mac

./jperl -E 'say "Hello from PerlOnJava!"'
./jperl -v  # Show version

Windows

jperl -E "say 'Hello from PerlOnJava!'"
jperl -v  # Show version

Basic Usage

Run a Perl Script

# One-liner
./jperl -E 'for (1..5) { say "Count: $_" }'

# Script file
echo 'use strict; use warnings; say "It works!";' > test.pl
./jperl test.pl

Use Core Modules

./jperl -MJSON -E 'say encode_json({hello => "world"})'
./jperl -MYAML::PP -E 'say Dump({foo => "bar"})'
./jperl -MData::Dumper -E 'print Dumper [1,2,3]'

More Examples

See One-liners Guide for practical examples.

Database Access with DBI

PerlOnJava includes the DBI module with JDBC support.

Quick Example

1. Download a JDBC driver (H2 database for testing):

wget https://repo1.maven.org/maven2/com/h2database/h2/2.2.224/h2-2.2.224.jar

2. Set CLASSPATH and run:

export CLASSPATH=/path/to/h2-2.2.224.jar
./jperl your_script.pl

3. Use DBI in your script:

use DBI;

my $dbh = DBI->connect("jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1")
    or die $DBI::errstr;

$dbh->do("CREATE TABLE users (id INT, name VARCHAR(50))");
$dbh->do("INSERT INTO users VALUES (1, 'Alice')");

my $sth = $dbh->prepare("SELECT * FROM users");
$sth->execute();

while (my $row = $sth->fetchrow_hashref) {
    say "$row->{id}: $row->{name}";
}

→ For PostgreSQL, MySQL, and other databases: See Database Access Guide

Using Perl from Java

PerlOnJava implements JSR-223 (Java Scripting API):

import javax.script.*;

public class TestPerl {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("perl");

        // Execute Perl code
        engine.eval("print 'Hello from Java!\\n'");

        // Pass variables
        engine.put("name", "World");
        engine.eval("say \"Hello, $name!\"");

        // Get results
        Object result = engine.eval("2 + 2");
        System.out.println("Result: " + result);
    }
}

Full guide: Java Integration Guide

Running in Docker

Quick start with Docker:

# Build image
docker build -t perlonjava .

# Run container
docker run -it perlonjava ./jperl -E 'say "Hello from Docker!"'

Full guide: Docker Guide

Next Steps

Learn More

• Feature Matrix - See what Perl features are supported
• One-liners - Practical Perl examples
• Module Porting - Port your favorite Perl modules

Get Help

• Support - Community resources
• GitHub Issues - Report bugs

Contribute

• CONTRIBUTING.md - How to contribute
• Roadmap - Future plans