File::ShareDir::Install(3pm)

1File::ShareDir::InstallU(s3e)r Contributed Perl DocumentaFtiiloen::ShareDir::Install(3)
2
3
4

NAME

6       File::ShareDir::Install - Install shared files
7

VERSION

9       version 0.13
10

SYNOPSIS

12           use ExtUtils::MakeMaker;
13           use File::ShareDir::Install;
14
15           install_share 'share';
16           install_share dist => 'dist-share';
17           install_share module => 'My::Module' => 'other-share';
18
19           WriteMakefile( ... );       # As you normally would
20
21           package MY;
22           use File::ShareDir::Install qw(postamble);
23

DESCRIPTION

25       File::ShareDir::Install allows you to install read-only data files from
26       a distribution. It is a companion module to File::ShareDir, which
27       allows you to locate these files after installation.
28
29       It is a port of Module::Install::Share to ExtUtils::MakeMaker with the
30       improvement of only installing the files you want; ".svn", ".git" and
31       other source-control junk will be ignored.
32
33       Please note that this module installs read-only data files; empty
34       directories will be ignored.
35

EXPORT

37   install_share
38           install_share $dir;
39           install_share dist => $dir;
40           install_share module => $module, $dir;
41
42       Causes all the files in $dir and its sub-directories to be installed
43       into a per-dist or per-module share directory.  Must be called before
44       WriteMakefile.
45
46       The first 2 forms are equivalent; the files are installed in a per-
47       distribution directory.  For example
48       "/usr/lib/perl5/site_perl/auto/share/dist/My-Dist".  The name of that
49       directory can be recovered with "dist_dir" in File::ShareDir.
50
51       The last form installs files in a per-module directory.  For example
52       "/usr/lib/perl5/site_perl/auto/share/module/My-Dist-Package".  The name
53       of that directory can be recovered with "module_dir" in File::ShareDir.
54
55       The parameter $dir may be an array of directories.
56
57       The files will be installed when you run "make install".  However, the
58       list of files to install is generated when Makefile.PL is run.
59
60       Note that if you make multiple calls to "install_share" on different
61       directories that contain the same filenames, the last of these calls
62       takes precedence.  In other words, if you do:
63
64           install_share 'share1';
65           install_share 'share2';
66
67       And both "share1" and "share2" contain a file called "info.txt", the
68       file "share2/info.txt" will be installed into your "dist_dir()".
69
70   delete_share
71           delete_share $list;
72           delete_share dist => $list;
73           delete_share module => $module, $list;
74
75       Remove previously installed files or directories.
76
77       Unlike "install_share", the last parameter is a list of files or
78       directories that were previously installed.  These files and
79       directories will be deleted when you run "make install".
80
81       The parameter $list may be an array of files or directories.
82
83       Deletion happens in-order along with installation.  This means that you
84       may delete all previously installed files by putting the following at
85       the top of your Makefile.PL.
86
87           delete_share '.';
88
89       You can also selectively remove some files from installation.
90
91           install_share 'some-dir';
92           if( ... ) {
93               delete_share 'not-this-file.rc';
94           }
95
96   postamble
97       This function must be exported into the MY package.  You will normally
98       do this with the following.
99
100           package MY;
101           use File::ShareDir::Install qw( postamble );
102
103       If you need to overload postamble, use the following.
104
105           package MY;
106           use File::ShareDir::Install;
107
108           sub postamble {
109               my $self = shift;
110               my @ret = File::ShareDir::Install::postamble( $self );
111               # ... add more things to @ret;
112               return join "\n", @ret;
113           }
114

CONFIGURATION

116       Two variables control the handling of dot-files and dot-directories.
117
118       A dot-file has a filename that starts with a period (.).  For example
119       ".htaccess". A dot-directory is a directory that starts with a period
120       (.).  For example ".config/".  Not all filesystems support the use of
121       dot-files.
122
123   $INCLUDE_DOTFILES
124       If set to a true value, dot-files will be copied.  Default is false.
125
126   $INCLUDE_DOTDIRS
127       If set to a true value, the files inside dot-directories will be
128       copied.  Known version control directories are still ignored.  Default
129       is false.
130
131   Note
132       These variables only influence subsequent calls to "install_share()".
133       This allows you to control the behaviour for each directory.
134
135       For example:
136
137           $INCLUDE_DOTDIRS = 1;
138           install_share 'share1';
139           $INCLUDE_DOTFILES = 1;
140           $INCLUDE_DOTDIRS = 0;
141           install_share 'share2';
142
143       The directory "share1" will have files in its dot-directories
144       installed, but not dot-files.  The directory "share2" will have files
145       in its dot-files installed, but dot-directories will be ignored.
146

SUPPORT

151       Bugs may be submitted through the RT bug tracker
152       <https://rt.cpan.org/Public/Dist/Display.html?Name=File-ShareDir-
153       Install> (or bug-File-ShareDir-Install@rt.cpan.org <mailto:bug-File-
154       ShareDir-Install@rt.cpan.org>).
155

AUTHOR

157       Philip Gwyn <gwyn@cpan.org>
158

CONTRIBUTORS

160       •   Karen Etheridge <ether@cpan.org>
161
162       •   Shoichi Kaji <skaji@cpan.org>
163

COPYRIGHT AND LICENSE

165       This software is copyright (c) 2009 by Philip Gwyn.
166
167       This is free software; you can redistribute it and/or modify it under
168       the same terms as the Perl 5 programming language system itself.
169
170
171
172perl v5.32.1                      2021-01-27        File::ShareDir::Install(3)