Quickstart Guide To Hacking On Piledriver

tl;dr

1. ./Configure -des -Dusethreads (configure with threads)
2. make (build perl)
3. make test or make minitest (confirm everything works)
4. Make your change.
5. make test or make minitest

perl

Configure

Perl does not use the normal configure that other C programs use. It uses Configure with completely different options. Things like --prefix will not work. Instructions can be found scattered through INSTALL. The general configure command you want to run is...

./Configure -des -Dusethreads

-des will configure Perl with the defaults without prompting you. -Dusethreads will configure Perl with threads; it's important to have them on while developing because code which works without threads might not work with them.

Build

make works normally.

Test

make test works normally.

Parallel testing can be used with TEST_JOBS=N make test_harness. A good number is your number of cores + 1.

Individual tests can be run with ./perl -Ilib t/blah.t.

miniperl

Building all of Perl's standard libraries can take a while. If you're working on core Perl functionality, you can build and test miniperl. This can save a lot of time.

Build

Instead of make run make miniperl.

Test

Instead of make test run make minitest.

Special considerations about C functions

One does not simply walk into Mordor and one does not simply write C functions in Perl.

The Perl_ prefix

Non-static functions should be named with a Perl_ prefix to avoid collisions with other functions. They can usually be called without that prefix. If you define Perl_foo you can call it as just foo... sometimes.

Adding or removing a function, or changing its signature

Adding, removing or changing the signature of a C function must also be reflected in embed.fnc. Then you must rebuild a bunch of header files with make regen and then rebuild.

1. Add, remove or change the signature of a function.
2. Reflect that change in embed.fnc.
3. make regen and then make or make miniperl.

This system takes care of generating header files for embedding Perl and for XS use. It also adds an extra layer of argument checks on top of C's type system. It also takes care of the Perl_foo to foo conversion.

The documentation for what the various flags mean are is in embed.fnc.

It's not a very friendly system. Sorry.

pTHX_ and aTHX_

These are magic macros for Perl's threading. Rule of thumb is when declaring a function add pTHX_ in front of the signature.

SV *Perl_foo(pTHX_ SV *stuff) {
    ...
}

When calling a Perl_... function add aTHX_ to the argument list.

Perl_foo(aTHX_ things);

If you call a Perl_ function without the prefix, you don't need aTHX_.

foo(things);