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
`-W`	Enable all warnings, even under ‘no warnings’
`-X`	Disable all warnings, even under ‘use warnings’
`-s`	Turn the program’s -name[=value] arguments into variables
`-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`	Interactive REPL (psh) - NOT IMPLEMENTED YET; the switch is reserved and currently exits non-zero
`-h, -?, --help`	Show this help message

pperl-specific options#

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

Runtime options#

Flag	Description
`--no-jit`	Disable JIT compilation (on by default)
`--no-regex-jit`	Disable only the regex JIT, leaving the op JIT on
`--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)

Regex JIT#

The regex JIT is separate from the op JIT and on by default. It compiles a pattern only after that pattern has matched against 64 KiB of subject, and only for the shapes it supports; anything else runs on the standard engine and is refused once, at pattern-compile time.

Flag	Description
`--no-regex-jit`	Disable the regex JIT, leaving the op JIT on. Costs nothing to leave on for workloads it helps, but a program whose patterns are ALL refused still pays a small per-match dispatch cost (~3%); turning it off removes that path completely. –no-jit disables it too, along with the op JIT.
`PPERL_RXJIT=0`	The same switch as an environment variable, for wrapping a program you cannot pass flags to. PPERL_RXJIT=1 forces it ON even under –no-jit (a diagnostic, not a normal posture).
`PPERL_RXJIT_STATS=1`	Report, per pattern, whether it was admitted, refused (with the reason) or compiled. Run this FIRST: it is what tells you whether a given workload is one of the ones worth disabling.

Module installation#

Flag	Description
`--cpan MODULE...`	Install CPAN distributions for pperl. Everything after this flag goes to the installer. Pure Perl only: pperl runs no XS. Modules built into the binary are reported as already installed, so they are never rebuilt.
`--cpan --system`	Install into the system overlay instead of the per-user tree ($PPERL_HOME, default ~/.pperl)
`--native-manifest=DIR`	Write pperl’s built-in module inventory as stub .pm files, so any installer’s on-disk version probe reads pperl’s inventory instead of the host perl’s. Put it on an INSTALLER’s path only, never on PPERL5LIB.

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. With a script file that means reusing its cached compiled image; the script itself stays a normal argument: pperl –via-daemon myscript.pl (PPERL_DAEMON=2 does the same without the flag)
`--via-daemon=trunk`	Force the shared zygote: fork a ready interpreter but compile the script every run. For testing the daemon; it saves little. Same as PPERL_DAEMON=1
`--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/

Report bugs at: https://github.com/petamem/pperl-bugtracker/issues

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 (`no` 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.