NAME
Module::Build::SysPath - install files to system folders according to
FHS (or Sys::Path settings)
SYNOPSIS
use Module::Build::SysPath;
my $builder = Module::Build::SysPath->new(
...
DESCRIPTION
A subclass of Module::Build using Sys::Path to determine the system
folders. Help in task of installing files into system folders and
keeping the option to work in local distribution files while developing
the module.
See Acme::SysPath for example usage of a module that needs a
configuration and a folder to store templates in.
USAGE
module-starter
module-starter --builder=Module::Build --module=Acme::NewModule --author="Pod" --email=pod@pod
cd Acme-NewModule/
perl -lane 's/Module::Build-/Module::Build::SysPath-/; print $_;' -i Build.PL
vim Build.PL
# s/Module::Build-/Module::Build::SysPath-/
# add "configure_requires => { 'Module::Build::SysPath' => 0.10 },"
# add "Module::Build::SysPath' => 0.10," to build_requires
create SPc.pm
copy http://github.com/jozef/Sys-Path/blob/master/examples/SPc.pm and
add it to your source tree. Clean up the paths that you don't need.
Local distribution folder names can be changed to anyones taste. For
example:
sub sysconfdir { File::Spec->catdir(__PACKAGE__->prefix, 'conf') };
'conf' is the name of a folder with conffiles. All file put to this
folder will be installed to Sys::Path->sysconfdir().
use the SPc.pm
Calling Acme::NewModule::SPc->sysconfdir before the distribution is
installed will return path to the 'conf' folder in the distribution
root folder. Calling it after install the distribution will return
Sys::Path->sysconfdir().
EXAMPLE
See Acme::SysPath for a really simple, Test::Daily for a real world
example.
new
Populates:
$builder->{'properties'}->{$path_type.'_files'} = ...;
$builder->{'properties'}->{'install_path'}->{$path_type} = ...;
$builder->add_build_element($path_type);
To install files located in:
sysconfdir
datadir
docdir
localedir
webdir
srvdir
Folders in:
cachedir
logdir
spooldir
rundir
lockdir
sharedstatedir
are skipped during the installation. Add .exists to this folders if you
want them to be created during `./Build install`.
Configuration files get a special (Debian like) treatment. All files in
sysconfdir and all files specified as
$builder->{'properties'}->{'conffiles'} are configuration files. Using
"install_checksums" in Sys::Path the c<conffile>s checksums are
tracked. Here are the model situations:
conffile was never installed jet
The file is just copied in place (to sysconfdir) as it is. MD5 is
recorded.
distribution ships new version, no change in system
The distribution changed the conffile (for example by adding new
values), but the conffile was untouched in the system. Then the new
version from distribution replaces the one in the system.
distribution conffile wasn't changed, conffile changed in system
Already installed distribution is getting upgrade. Distribution
conffiles form installed and the new version didn't change. But the
conffile was changed in the system. No prompt and the conffile is
kept intact.
distribution conffile change, conffile changed in system
Already installed distribution is getting upgrade. When both the
distribution changed the conffile and the conffile was changed in the
system. User will be prompted what to do:
Installing new version of config file /etc/SOMEFILE ...
Configuration file `/etc/SOMEFILE'
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are:
Y or I : install the package maintainer's version
N or O : keep your currently-installed version
D : show the differences between the versions
Z : background this process to examine the situation
The default action is to keep your current version.
*** /etc/SOMEFILE (Y/I/N/O/D/Z) ?
If N or O is selected distribution files is installed with -spc
suffix. If Y or I is selected the system conffile is renamed by
adding suffix -old and distribution conffile is installed.
ACTION_install
This action is responsible for renaming files, replacing SPc.pm paths
to systems once from Sys::Path. Also makes files writable (chmod 0644).
And stores the checksums of conffiles.
AUTHOR
Jozef Kutej, <jkutej at cpan.org>
CONTRIBUTORS
The following people have contributed to the Sys::Path by commiting
their code, sending patches, reporting bugs, asking questions,
suggesting useful advices, nitpicking, chatting on IRC or commenting on
my blog (in no particular order):
Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
Emmanuel Rodriguez
Slaven Rezić
COPYRIGHT & LICENSE
Copyright 2009 Jozef Kutej, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.