File::ShareDir::Install - Install shared files
version 0.13
use ExtUtils::MakeMaker;
use File::ShareDir::Install;
install_share 'share';
install_share dist => 'dist-share';
install_share module => 'My::Module' => 'other-share';
WriteMakefile( ... ); # As you normally would
package MY;
use File::ShareDir::Install qw(postamble);
File::ShareDir::Install allows you to install read-only data files from a
distribution. It is a companion module to the File::ShareDir manpage, which
allows you to locate these files after installation.
It is a port of the Module::Install::Share manpage to the ExtUtils::MakeMaker manpage with the
improvement of only installing the files you want; .svn , .git and other
source-control junk will be ignored.
Please note that this module installs read-only data files; empty
directories will be ignored.
install_share $dir;
install_share dist => $dir;
install_share module => $module, $dir;
Causes all the files in $dir and its sub-directories to be installed
into a per-dist or per-module share directory. Must be called before
WriteMakefile.
The first 2 forms are equivalent; the files are installed in a per-distribution
directory. For example /usr/lib/perl5/site_perl/auto/share/dist/My-Dist . The
name of that directory can be recovered with dist_dir in the File::ShareDir manpage.
The last form installs files in a per-module directory. For example
/usr/lib/perl5/site_perl/auto/share/module/My-Dist-Package . The name of that
directory can be recovered with module_dir in the File::ShareDir manpage.
The parameter $dir may be an array of directories.
The files will be installed when you run make install . However, the list
of files to install is generated when Makefile.PL is run.
Note that if you make multiple calls to install_share on different
directories that contain the same filenames, the last of these calls takes
precedence. In other words, if you do:
install_share 'share1';
install_share 'share2';
And both share1 and share2 contain a file called info.txt , the file
share2/info.txt will be installed into your dist_dir() .
delete_share $list;
delete_share dist => $list;
delete_share module => $module, $list;
Remove previously installed files or directories.
Unlike install_share, the last parameter is a list of files or
directories that were previously installed. These files and directories will
be deleted when you run make install .
The parameter $list may be an array of files or directories.
Deletion happens in-order along with installation. This means that you may
delete all previously installed files by putting the following at the top of
your Makefile.PL.
delete_share '.';
You can also selectively remove some files from installation.
install_share 'some-dir';
if( ... ) {
delete_share 'not-this-file.rc';
}
This function must be exported into the MY package. You will normally do this
with the following.
package MY;
use File::ShareDir::Install qw( postamble );
If you need to overload postamble, use the following.
package MY;
use File::ShareDir::Install;
sub postamble {
my $self = shift;
my @ret = File::ShareDir::Install::postamble( $self );
# ... add more things to @ret;
return join "\n", @ret;
}
Two variables control the handling of dot-files and dot-directories.
A dot-file has a filename that starts with a period (.). For example
.htaccess . A dot-directory is a directory that starts with a
period (.). For example .config/ . Not all filesystems support the use
of dot-files.
If set to a true value, dot-files will be copied. Default is false.
If set to a true value, the files inside dot-directories will be copied.
Known version control directories are still ignored. Default is false.
These variables only influence subsequent calls to install_share() . This allows
you to control the behaviour for each directory.
For example:
$INCLUDE_DOTDIRS = 1;
install_share 'share1';
$INCLUDE_DOTFILES = 1;
$INCLUDE_DOTDIRS = 0;
install_share 'share2';
The directory share1 will have files in its dot-directories installed,
but not dot-files. The directory share2 will have files in its dot-files
installed, but dot-directories will be ignored.
the File::ShareDir manpage, the Module::Install manpage.
Bugs may be submitted through the RT bug tracker
(or bug-File-ShareDir-Install@rt.cpan.org).
Philip Gwyn <gwyn@cpan.org>
This software is copyright (c) 2009 by Philip Gwyn.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|