Example: Acme::Notes

Read this when you create SPc.pm or convert Build.PL. It is an application with a config file, templates, a state directory, and logs. A real-world variant is meon-Web (Build.PL with conffiles and srvdir).

Layout

Build.PL
MANIFEST
lib/Acme/Notes.pm
lib/Acme/Notes/SPc.pm
script/acme-notes
etc/acme-notes/notes.ini          -> sysconfdir, conffile
etc/cron.d/acme-notes             -> sysconfdir, conffile
share/acme-notes/templates/*.xsl  -> datadir
var/lib/acme-notes/.exists        -> sharedstatedir, created empty
var/log/acme-notes/.exists        -> logdir, created empty

lib/Acme/Notes/SPc.pm

package Acme::Notes::SPc;

use warnings;
use strict;

our $VERSION = '0.01';

use File::Spec;
use Sys::Path; # remove after install

sub _path_types {qw(
    prefix
    localstatedir
    sysconfdir
    datadir
    logdir
    sharedstatedir
)};

sub prefix        { Sys::Path->find_distribution_root(__PACKAGE__) };
sub localstatedir { File::Spec->catdir(__PACKAGE__->prefix, 'var') };

sub sysconfdir     { File::Spec->catdir(__PACKAGE__->prefix, 'etc') };
sub datadir        { File::Spec->catdir(__PACKAGE__->prefix, 'share') };
sub logdir         { File::Spec->catdir(__PACKAGE__->localstatedir, 'log') };
sub sharedstatedir { File::Spec->catdir(__PACKAGE__->localstatedir, 'lib') };

1;

After ./Build install with a /usr perl, the installed copy contains lines like sub sysconfdir { "/etc" }; and no longer loads Sys::Path.

Build.PL

use strict;
use warnings;
use Module::Build::SysPath;

my $builder = Module::Build::SysPath->new(
    module_name        => 'Acme::Notes',
    license            => 'perl',
    dist_author        => 'Jane Doe <jane@example.com>',
    dist_version_from  => 'lib/Acme/Notes.pm',
    configure_requires => {
        'Module::Build'          => '0.3607',
        'Module::Build::SysPath' => '0.19',
    },
    build_requires => {
        'Module::Build::SysPath' => '0.19',
    },
    script_files   => ['script/acme-notes'],
    add_to_cleanup => ['Acme-Notes-*'],
);

$builder->create_build_script();

Files under sysconfdir are conffiles automatically. To protect a file that lives under another type, add conffiles => [qw(share/acme-notes/x.conf)].

If notes.ini held a password, require 0.20 in configure_requires and build_requires (older versions ignore the option silently), and restrict it after install with file_modes => { 'etc/acme-notes/notes.ini' => 0640 }. Set its group outside the build, because a new file belongs to the installing user. From 0.20 on, upgrades keep that group.

Custom build actions

my $class = Module::Build::SysPath->subclass(code => <<'CUSTOM_BUILDER');
    sub ACTION_install {
        my $self = shift;
        $self->SUPER::ACTION_install(@_);
        # post-install step, for example notifying a running service
    }
CUSTOM_BUILDER

my $builder = $class->new(...);    # same arguments as above

Runtime lookup

use File::Spec;
use Acme::Notes::SPc;

sub config_file {
    File::Spec->catfile(Acme::Notes::SPc->sysconfdir, 'acme-notes', 'notes.ini');
}
sub notes_dir { File::Spec->catdir(Acme::Notes::SPc->sharedstatedir, 'acme-notes') }