/ 
File-ShareDir-Install-0.06
River stage four • 477 direct dependents • 7190 total dependents
/ File::ShareDir::Install

NAME

File::ShareDir::Install - Install shared files

SYNOPSIS

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 normaly would

package MY;
use File::ShareDir::Install qw(postamble);

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 will be installed when you run make install.

To locate the files after installation so they can be used inside your module, see File::ShareDir.

my $dir = File::ShareDir::module_dir( $module );

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 fill called info, the file share2/info will be installed into your dist_dir().

postamble

Exported into the MY package. Only documented here if you need to write your own postamble.

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;
}

CONFIGURATION

2 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 (or dot-dir) is a directory that starts with a period (.). For example .config/. Not all OSes 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 influences 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.

AUTHOR

Philip Gwyn, <gwyn-AT-cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2009-2011 by Philip Gwyn

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.