Documentation

Compiling & Running

Perla has four main modes of invocation:

All command-line flags

Optimization levels

Defaults to -O0 — optimized for compile speed during dev. For release builds, use -O2 or -O3.

On a medium-sized web app, the gcc phase goes from ~15s at -O0 to ~100s at -O2. Worth it for release; not worth it during iteration.

__C__ Blocks

__C__ { ... } drops raw C into the generated output. Perla doesn't parse or rewrite the block — it's emitted verbatim. Three valid positions:

File scope

Place outside any sub. Use for #includes, static state, and helper functions that you'll call from multiple __C__ blocks.

__C__ {
    #include <sys/time.h>
    #include <unistd.h>
    static int call_counter = 0;
}

Inside a sub

Emitted as a { ... } block inside the generated C function body.

sub add {
    my ($a, $b) = @_;
    my $sum = 0;
    __C__ {
        int64_t __a = strada_to_int(v_a);
        int64_t __b = strada_to_int(v_b);
        strada_decref(v_sum);
        v_sum = strada_new_int(__a + __b);
    }
    return $sum;
}

Expression context (GCC statement-expression)

my $pid = __C__ {
    ({ StradaValue *__r = strada_new_int((int64_t)getpid()); __r; })
};

Variable name mapping

Runtime helpers available

All strada_* and perla_* functions are in scope. The most useful:

Memory rules

1. Tagged-int guard. Integers in range -2^62..2^62-1 are encoded directly in pointers. Any code that reads sv->type/sv->value/sv->meta/sv->refcount must check STRADA_IS_TAGGED_INT(sv) first. The high-level helpers handle this for you.
2. strada_to_str allocates. Always free() the result. For no-alloc, use strada_to_str_buf with a stack buffer.
3. Decref before reassign. strada_decref(v_result); v_result = strada_new_int(42); — forgetting leaks; double-free is worse.
4. _take vs plain for container inserts. strada_hv_store_take(hv, "k", strada_new_str("v")) keeps refcount at 1; strada_hv_store increfs. Use _take for freshly-allocated values, plain store for existing variables.

Complete worked example

use strict;

__C__ {
    #include <sys/resource.h>
}

sub rss_bytes {
    my $r = 0;
    __C__ {
        struct rusage __u;
        if (getrusage(RUSAGE_SELF, &__u) == 0) {
            /* ru_maxrss is KB on Linux, bytes on macOS */
            strada_decref(v_r);
            v_r = strada_new_int((int64_t)__u.ru_maxrss * 1024);
        }
    }
    return $r;
}

printf "RSS: %d MB\n", int(rss_bytes() / 1024 / 1024);

For the complete __C__ reference including FFI examples, see the Markdown version on GitHub.

Module Search Paths

Perla has two separate search paths for use and require.

Compile-time path (consulted when parsing use X)

Built by _build_lib_paths, in search order:

1. Directory of the input file
2. Current directory (.)
3. $PERLA5LIB env var
4. $PERL5LIB (Perl compatibility)
5. $HOME/perla/lib (if it exists)
6. -I path CLI flags (prepended)
7. use lib "..." statements during parse

Not included by default: /opt/bzperl/... or any large CPAN tree. Including it would trigger transitive source parsing of every module in the tree, blowing compile time. Add it via use lib "..." in your script if you need it.

Runtime path (consulted for require and lazy-loads)

Baked into the executable at compile time. Plus at startup: $PERLA_LIB, ~/.perla/perla.conf, /etc/perla.conf. Also probes archlib subdirs (x86_64-linux/) for each path.

Dedup

Two layers prevent re-parsing:

• Name-keyed: use Foo::Bar twice gets caught by matching the Perl module name.
• Path-keyed: two different use statements resolving to the same file (lib-path collisions) get caught by matching the resolved path.

The precompile cache

perla -M Foo/Bar.pm writes:

• Foo/Bar.pm.o — object file for static linking
• Foo/Bar.pm.deps — transitive dependency list
• Foo/Bar.pm.so — shared library (if PERLA_BUILD_PM_SO=1 or --shared)

Subsequent compiles that use this module pick up the cached .pm.o instead of re-parsing. Useful for warming a module tree:

$ perla -M lib/          # recursively precompile every .pm under lib/

Auto-build heuristic

By default, a module used in your program is only auto-precompiled if its source matches an import-installing pattern (sub import, our @EXPORT, *{$M.import}). Everything else is left for runtime require. This prevents runaway cascade compiles.

To precompile every dependency, use --precompile-deps.

Debugging & Diagnostics

--debug output vocabulary

Common failure modes

sh: 1: foo: not found after compile

The compiled binary wasn't on $PATH. Recent Perla prefixes ./ automatically; if you see this, rebuild Perla.

redefinition of 'perla_sub_Foo_bar' at link

Either the source defines the same sub twice (Perla now matches Perl's last-wins semantic — rebuild Perla), or a dependency cycle re-parses the file (caught by path-keyed dedup).

undefined reference to perla_mod_init_Xxx at link

A precompiled .pm.o was built with the wrong module name. Re-run perla -M /full/path/to/module.pm or set PERLA_MODULE_NAME=Foo::Bar explicitly.

Can't locate object method X via package "REF(0x0x...)"

A blessed ref was stringified for use as a class name. perla_bless should unwrap this via perla_class_name — rebuild Perla if you see this today.

Compile works but program behaves weirdly

Run with --keep, grep the generated .c for the affected sub. Usually a codegen issue with a specific Perl idiom.

Environment variables

Perl Compatibility

What works

• Core syntax: sigils, arrays, hashes, regex (=~, s///, m// with /i, /s, /x, /g, /e), foreach/map/grep/sort, push/pop/shift/unshift, slice syntax, string interpolation, heredoc, qw//.
• OO: bless, @ISA, SUPER::, AUTOLOAD, multiple inheritance with Perl's method resolution order, overload ("", ==, arithmetic, etc.).
• Moose-ish: has, extends, with, before/after/around, isa, meta, auto-accessors — native C runtime implementation (not Class::MOP).
• Exception handling: eval { }, die, $@, Try::Tiny, typed catch.
• Core modules: strict, warnings, Carp, Data::Dumper, JSON, YAML, URI::Escape, File::Spec, File::Temp, File::Find, List::Util, Scalar::Util, Time::HiRes, Encode, Digest::MD5/SHA, MIME::Base64, HTTP::Date, Storable::dclone.
• DBI: connection, prepare, execute, bind, fetchrow_hashref/array, selectrow_array, etc. MySQL and SQLite drivers via native implementation.
• DBIx::Class: a minimal stub in your lib/DBIx/Class/ provides has_one/has_many/belongs_to, ResultSet::search/first/all, Bootstrap::Simple. Not the real DBIC — it's a re-implementation of its public API.
• Drogo (web framework): works, including Drogo::Server::Cannoli.

What doesn't work (yet)

• eval STRING at runtime. Has an opt-in path via core::full_eval_on() but it shells out to a child perla compile — slow and not ergonomic. eval BLOCK works normally for exception handling.
• XS modules without native implementations. Detected and silently skipped. Wrap the C library yourself via __C__ or find a Perl equivalent.
• DynaLoader. Not wired up; XS bootstrap would need a separate project.
• Threads (Perl's threads module). Perla is single-threaded per process; use fork for concurrency (async::* helpers work).
• Source filters. Parse happens before any runtime, so source filters that modify the source at use-time don't apply.
• Some corner-case Perl idioms. Tie, symbol-table trickery (beyond @ISA/@EXPORT), local on magical vars. Most work; a fraction don't. Report them.

Cannoli Integration

Cannoli is the Strada-native preforking HTTP server. Perla-compiled apps load into it via the cannoli_perla.so bridge.

$ cd /path/to/cannoli/lib/perla
$ make                            # builds cannoli_perla.so
$ make demo                       # builds Demo.pm.so
$ /path/to/cannoli/cannoli \
    --library "./cannoli_perla.so:\
        so=$(pwd)/Demo.pm.so;\
        init=perla_mod_init_Demo;\
        handler=perla_sub_Demo_hello" \
    --dev -p 8080

$ curl http://127.0.0.1:8080/
Hello from a Perla-compiled handler!

The bridge parses three config options:

• so= — path to the Perla-compiled .pm.so (handler module)
• init= — module init function to call once at startup (usually perla_mod_init_Foo)
• handler= — per-request handler function (usually perla_sub_Foo_handle)

See the cannoli_perla source for full detail. Cannoli ships with a parallel cannoli_perl.so for running real Perl (via libperl) if you'd rather stay in that world.

More