.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" 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 turned on, 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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "File::ShareDir::Install 3pm" .TH File::ShareDir::Install 3pm "2016-09-11" "perl v5.22.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.11 .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 "CONTRIBUTOR" .IX Header "CONTRIBUTOR" Karen Etheridge .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.