.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "File::ShareDir::Install 3pm" .TH File::ShareDir::Install 3pm "2018-05-14" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::ShareDir::Install \- Install shared files .SH "VERSION" .IX Header "VERSION" version 0.13 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use ExtUtils::MakeMaker; \& use File::ShareDir::Install; \& \& install_share \*(Aqshare\*(Aq; \& install_share dist => \*(Aqdist\-share\*(Aq; \& install_share module => \*(AqMy::Module\*(Aq => \*(Aqother\-share\*(Aq; \& \& WriteMakefile( ... ); # As you normally would \& \& package MY; \& use File::ShareDir::Install qw(postamble); .Ve .SH "DESCRIPTION" .IX Header "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. .PP It is a port of Module::Install::Share to ExtUtils::MakeMaker with the improvement of only installing the files you want; \f(CW\*(C`.svn\*(C'\fR, \f(CW\*(C`.git\*(C'\fR and other source-control junk will be ignored. .PP Please note that this module installs read-only data files; empty directories will be ignored. .SH "EXPORT" .IX Header "EXPORT" .SS "install_share" .IX Subsection "install_share" .Vb 3 \& install_share $dir; \& install_share dist => $dir; \& install_share module => $module, $dir; .Ve .PP Causes all the files in \f(CW$dir\fR and its sub-directories to be installed into a per-dist or per-module share directory. Must be called before WriteMakefile. .PP The first 2 forms are equivalent; the files are installed in a per-distribution directory. For example \f(CW\*(C`/usr/lib/perl5/site_perl/auto/share/dist/My\-Dist\*(C'\fR. The name of that directory can be recovered with \*(L"dist_dir\*(R" in File::ShareDir. .PP The last form installs files in a per-module directory. For example \&\f(CW\*(C`/usr/lib/perl5/site_perl/auto/share/module/My\-Dist\-Package\*(C'\fR. The name of that directory can be recovered with \*(L"module_dir\*(R" in File::ShareDir. .PP The parameter \f(CW$dir\fR may be an array of directories. .PP The files will be installed when you run \f(CW\*(C`make install\*(C'\fR. However, the list of files to install is generated when Makefile.PL is run. .PP Note that if you make multiple calls to \f(CW\*(C`install_share\*(C'\fR on different directories that contain the same filenames, the last of these calls takes precedence. In other words, if you do: .PP .Vb 2 \& install_share \*(Aqshare1\*(Aq; \& install_share \*(Aqshare2\*(Aq; .Ve .PP And both \f(CW\*(C`share1\*(C'\fR and \f(CW\*(C`share2\*(C'\fR contain a file called \f(CW\*(C`info.txt\*(C'\fR, the file \&\f(CW\*(C`share2/info.txt\*(C'\fR will be installed into your \f(CW\*(C`dist_dir()\*(C'\fR. .SS "delete_share" .IX Subsection "delete_share" .Vb 3 \& delete_share $list; \& delete_share dist => $list; \& delete_share module => $module, $list; .Ve .PP Remove previously installed files or directories. .PP Unlike \*(L"install_share\*(R", the last parameter is a list of files or directories that were previously installed. These files and directories will be deleted when you run \f(CW\*(C`make install\*(C'\fR. .PP The parameter \f(CW$list\fR may be an array of files or directories. .PP 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. .PP .Vb 1 \& delete_share \*(Aq.\*(Aq; .Ve .PP You can also selectively remove some files from installation. .PP .Vb 4 \& install_share \*(Aqsome\-dir\*(Aq; \& if( ... ) { \& delete_share \*(Aqnot\-this\-file.rc\*(Aq; \& } .Ve .SS "postamble" .IX Subsection "postamble" This function must be exported into the \s-1MY\s0 package. You will normally do this with the following. .PP .Vb 2 \& package MY; \& use File::ShareDir::Install qw( postamble ); .Ve .PP If you need to overload postamble, use the following. .PP .Vb 2 \& 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 "\en", @ret; \& } .Ve .SH "CONFIGURATION" .IX Header "CONFIGURATION" Two variables control the handling of dot-files and dot-directories. .PP A dot-file has a filename that starts with a period (.). For example \&\f(CW\*(C`.htaccess\*(C'\fR. A dot-directory is a directory that starts with a period (.). For example \f(CW\*(C`.config/\*(C'\fR. Not all filesystems support the use of dot-files. .ie n .SS "$INCLUDE_DOTFILES" .el .SS "\f(CW$INCLUDE_DOTFILES\fP" .IX Subsection "$INCLUDE_DOTFILES" If set to a true value, dot-files will be copied. Default is false. .ie n .SS "$INCLUDE_DOTDIRS" .el .SS "\f(CW$INCLUDE_DOTDIRS\fP" .IX Subsection "$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. .SS "Note" .IX Subsection "Note" These variables only influence subsequent calls to \f(CW\*(C`install_share()\*(C'\fR. This allows you to control the behaviour for each directory. .PP For example: .PP .Vb 5 \& $INCLUDE_DOTDIRS = 1; \& install_share \*(Aqshare1\*(Aq; \& $INCLUDE_DOTFILES = 1; \& $INCLUDE_DOTDIRS = 0; \& install_share \*(Aqshare2\*(Aq; .Ve .PP The directory \f(CW\*(C`share1\*(C'\fR will have files in its dot-directories installed, but not dot-files. The directory \f(CW\*(C`share2\*(C'\fR will have files in its dot-files installed, but dot-directories will be ignored. .SH "SEE ALSO" .IX Header "SEE ALSO" File::ShareDir, Module::Install. .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker (or bug\-File\-ShareDir\-Install@rt.cpan.org ). .SH "AUTHOR" .IX Header "AUTHOR" Philip Gwyn .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Shoichi Kaji .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2009 by Philip Gwyn. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.