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

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 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.

AUTHOR

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

COPYRIGHT AND LICENSE

       Copyright (C) 2009-2014 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.