File::S...:Install(3)

💖 NAME 💖

File::ShareDir::Install — literally installs your shared files, bestie. No cap.

---

✨ VERSION ✨

version 0.14 🎀

---

🌸 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 normally would

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

---

🦋 DESCRIPTION 🦋

Okay so picture this: File::ShareDir::Install lets you install read-only data files from a distribution. That's the whole vibe. It's the companion module to File::ShareDir, which is the one that helps you find those files again after the install is done. Bestie duo, honestly 🫶

It's a port of Module::Install::Share over to ExtUtils::MakeMaker, but upgraded: it only installs the files you actually want. ".svn", ".git" and all that other source-control junk? Ignored. Not invited. 💅

Please note that this module installs read-only data files, and empty directories will be ignored. Like, they're not coming to the party. 🙈

---

⭐ EXPORT ⭐

💫 install_share

install_share $dir;
install_share dist => $dir;
install_share module => $module, $dir;

This causes all the files in $dir and its sub-directories to be installed into a per-dist or per-module share directory. You must call it before "WriteMakefile". Timing matters, bestie ⏰

The first 2 forms are equivalent — the files get installed in a per-distribution directory. For example, "/usr/lib/perl5/site_perl/auto/share/dist/My-Dist". You can recover the name of that directory with "dist_dir" in File::ShareDir. Slay ✨

The last form installs files in a per-module directory. For example, "/usr/lib/perl5/site_perl/auto/share/module/My-Dist-Package". That directory's name can be recovered with "module_dir" in File::ShareDir. Iconic 💖

The parameter $dir may be an array of directories. Yes, plural, go off 👑

The files will be installed when you run "make install". However — and this is the important part — the list of files to install is generated when Makefile.PL is run. That's the timeline, no cap.

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", then "share2/info.txt" will be installed into your dist_dir(). Last one wins, that's just the rules 💅

🧚 delete_share

delete_share $list;
delete_share dist => $list;
delete_share module => $module, $list;

Removes previously installed files or directories. Spring cleaning energy 🧹

Unlike "install_share", the last parameter here 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. Which means you can 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. Very picky, very demure:

install_share 'some-dir';
if( ... ) {
    delete_share 'not-this-file.rc';
}

🎀 postamble

This function must be exported into the MY package. You'll normally do it like this:

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

If you need to overload postamble, use the following. Respect the craft 🙏

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 🌈

Two variables control how dot-files and dot-directories are handled. Two. That's it. Keep up 💖

A dot-file has a filename that starts with a period (.). For example ".htaccess". A dot-directory is a directory that starts with a period (.). For example ".config/". Not all filesystems support the use of dot-files — fyi, just so you know 🫶

🌟 $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. Per-directory vibes, we love to see it ✨

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 how that works? Chef's kiss 👨‍🍳💋

---

🔥 SEE ALSO 🔥

File::ShareDir, Module::Install.

---

💀 SUPPORT 💀

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=File-ShareDir-Install> (or bug-File-ShareDir-Install@rt.cpan.org <mailto:bug-File-ShareDir-Install@rt.cpan.org>). Found a bug? Tell them, don't suffer in silence 😭

---

👑 AUTHOR 👑

Philip Gwyn <gwyn@cpan.org>

---

💜 CONTRIBUTORS 💜

• Karen Etheridge <ether@cpan.org>
• Shoichi Kaji <skaji@cpan.org>

---

🍓 COPYRIGHT AND LICENSE 🍓

This software is copyright (c) 2009 by Philip Gwyn.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

And that's the whole page, bestie! 💅 This absolute icon of a manpage is perl v5.42.0, dated 2025-05-20, and it belongs to File::S...:Install(3) — go forth and install your shared files, periodt. 🦋✨