CLI options#

pperl accepts a small set of command-line flags. Most are perl-compatible; a handful are pperl-specific (JIT, parallelism). The authoritative list is whatever pperl --help prints; the tables below show those flags, extracted from the interpreter source and rendered here on every documentation build.

Note

The actual pperl --help output on the terminal is always in English - the binary does not localise help strings. Translated documentation shows the same flags with descriptions in the page’s language so readers can study what each flag does; flag tokens (-T, --threads=N, …) are always verbatim.

PetaPerl - Next-generation Perl 5 runtime

Usage#

pperl [OPTIONS] [--] [SCRIPT [ARGS...]]
pperl -e 'code'
pperl -E 'code'

Perl-compatible options#

Flag	Description
`-e 'code'`	Execute one-liner
`-E 'code'`	Like -e, but enable all optional features (say, …)
`-Mmodule`	use module before executing (-MO=Deparse, -Mstrict)
`-mmodule`	use module () before executing (no imports)
`-Idirectory`	Prepend directory to @INC
`-c`	Check syntax only, don’t execute
`-w`	Enable warnings
`-n`	Loop over input lines (no auto-print), like while(<>)
`-p`	Loop over input lines and auto-print, like a sed filter
`-a`	Autosplit each line into @F (with -n or -p)
`-F pattern`	Set the -a split pattern (implies -a)
`-l[octal]`	Auto-chomp input, set output record separator
`-0[octal]`	Set input record separator (-0 = NUL, -00 = paragraph)
`-i[ext]`	Edit files in place (optional backup extension)
`-T`	Taint mode (forced)
`-t`	Taint warnings
`-v`	Show version information
`-V`	Show configuration summary, %ENV and @INC
`-V:key`	Show the value of a Config key, e.g. -V:archname
`--interactive`	Launch interactive REPL (requires ‘shell’ feature)
`-h, -?, --help`	Show this help message

Pperl-specific options#

Flag	Description
`--stats, -s`	Show performance statistics (time, memory)

Runtime options#

Flag	Description
`--no-jit`	Disable JIT compilation (on by default)
`--no-parallel`	Disable auto-parallelization (on by default)
`--threads=SPEC`	Parallel thread count. SPEC is one of:
`phys`	all physical cores (DEFAULT)
`log`	all logical cores (hyperthreads)
`phys-N`	physical minus N (min 1)
`log-N`	logical minus N (min 1)
`P%`	P percent of logical cores
`N`	an explicit count
`--parallel-threshold=N`	Minimum iterations to parallelize (default: 100)
`--jit-stats`	Print JIT summary to stderr at exit (see also PPERL_JIT_LOG)

Daemon options#

Flag	Description
`--daemon`	Run the fast-start daemon in the foreground
`--daemon=start`	Start the daemon in the background
`--daemon=stop`	Stop the running daemon for this binary
`--daemon=status`	Show daemon status and cached script templates
`--daemon-idle=SECS`	Daemon exits after SECS without a request (default: 900)
`--daemon-max-scripts=N`	Cache at most N script templates (default: 100)
`--daemon-reset`	Drop all cached script templates
`--daemon-reset=FILE`	Drop the cached template for FILE only
`--via-daemon`	Route this run through the daemon, same as PPERL_DAEMON=1
`--via-daemon=script`	Reuse a per-script template, same as PPERL_DAEMON=2
`--build-id`	Print the binary identity that keys the daemon socket

Examples#

pperl script.pl

Execute a Perl script

pperl -E 'say "Hello!"'

Execute a one-liner (-E enables say, state, etc.)

pperl -c script.pl

Check script syntax without executing

pperl script.pl arg1 arg2

Pass arguments to script (@ARGV)

For more information, see: https://perl.petamem.com/docs/eng/

Module search paths: `-I`, `PERL5LIB`, `@INC`#

-I dir prepends dir to @INC, exactly like perl. Entries from -I and from the PERL5LIB environment variable (PERLLIB as the fallback; both ignored under taint mode) are additionally expanded: if the directory has versioned children (5.44.99, 5.40.0, …), those are added around the entry, nearest perl version first. This makes local::lib- and Carton-style trees built by a real perl work unmodified.

Two deliberate differences from perl:

No architecture subdirectories. perl would also add dir/5.44/x86_64-linux-style children; pperl never does. It runs no compiled XS objects, so those directories hold nothing it could use, and skipping them avoids loading .pm wrappers that would die trying to bootstrap .so files.
Native modules win over every @INC entry. Modules built into the pperl binary (see PPERL_MODS below) are served directly by require; a same-name .pm on disk is never loaded in front of them, no matter what -I says.

Two pperl-private search locations exist for parallel installations, so a module can be provided to pperl WITHOUT touching the shared perl trees:

The PPERL5LIB environment variable: same syntax and expansion as PERL5LIB, honored immediately before it.
The pperl overlay trees, probed before every host perl tree: /usr/local/share/pperl/site_perl (local overrides), /usr/share/pperl/site_perl and /usr/share/pperl/vendor_perl (packaged), each optionally with versioned children.

A .pm in either location outranks all host trees for pperl only - the host perl never looks there. Neither can outrank a module built into the binary.

The rest of @INC is built by probing the host’s standard library trees (Arch, Debian and Fedora layouts) rather than baking one distribution’s paths into the binary; pperl -V prints the real result. Details and rationale: differences from upstream and the @INC reference in program input.

Environment variables#

pperl sets several environment variables inside the process it runs, so scripts can introspect the running interpreter:

Variable	Meaning
`PPERL`	Version string (same as `pperl -v`)
`PPERL_FEATURES`	Comma-separated list of compiled-in Cargo features
`PPERL_MODS`	Comma-separated `Name/version` pairs for every native module
`PPERL_SHELL`	Shell integration flavor (empty if `shell` feature off)
`PPERL_STATIC`	`yes` if the binary is musl-statically linked, else `no`

Run pperl -V to see all values for the current binary.