NAME
File::ShareDir::Install - Install shared files
VERSION
version 0.14
SYNOPSIS
use
ExtUtils::MakeMaker;
install_share
'share'
;
install_share
dist
=>
'dist-share'
;
install_share
module
=>
'My::Module'
=>
'other-share'
;
WriteMakefile( ... );
# As you normally would
package
MY;
DESCRIPTION
File::ShareDir::Install allows you to install read-only data files from a distribution. It is a companion module to File::ShareDir, which allows you to locate these files after installation.
It is a port of Module::Install::Share to ExtUtils::MakeMaker 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.
EXPORT
install_share
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 File::ShareDir.
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 File::ShareDir.
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
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'
;
}
postamble
This function must be exported into the MY package. You will normally do this with the following.
package
MY;
If you need to overload postamble, use the following.
package
MY;
sub
postamble {
my
$self
=
shift
;
my
@ret
= File::ShareDir::Install::postamble(
$self
);
# ... add more things to @ret;
return
join
"\n"
,
@ret
;
}
CONFIGURATION
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.
$INCLUDE_DOTFILES
If set to a true value, dot-files will be copied. Default is false.
$INCLUDE_DOTDIRS
If set to a true value, the files inside dot-directories will be copied. Known version control directories are still ignored. Default is false.
Note
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.
SEE ALSO
File::ShareDir, Module::Install.
SUPPORT
Bugs may be submitted through the RT bug tracker (or bug-File-ShareDir-Install@rt.cpan.org).
AUTHOR
Philip Gwyn <gwyn@cpan.org>
CONTRIBUTORS
Karen Etheridge <ether@cpan.org>
Shoichi Kaji <skaji@cpan.org>
COPYRIGHT AND LICENSE
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.