{ "mode": "perldoc", "parameter": "File::ShareDir", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/File%3A%3AShareDir/json", "generated": "2026-06-11T23:23:21Z", "synopsis": "use File::ShareDir ':ALL';\n# Where are distribution-level shared data files kept\n$dir = distdir('File-ShareDir');\n# Where are module-level shared data files kept\n$dir = moduledir('File::ShareDir');\n# Find a specific file in our dist/module shared dir\n$file = distfile( 'File-ShareDir', 'file/name.txt');\n$file = modulefile('File::ShareDir', 'file/name.txt');\n# Like modulefile, but search up the inheritance tree\n$file = classfile( 'Foo::Bar', 'file/name.txt' );", "sections": { "NAME": { "content": "File::ShareDir - Locate per-dist and per-module shared files\n", "subsections": [] }, "SYNOPSIS": { "content": "use File::ShareDir ':ALL';\n\n# Where are distribution-level shared data files kept\n$dir = distdir('File-ShareDir');\n\n# Where are module-level shared data files kept\n$dir = moduledir('File::ShareDir');\n\n# Find a specific file in our dist/module shared dir\n$file = distfile( 'File-ShareDir', 'file/name.txt');\n$file = modulefile('File::ShareDir', 'file/name.txt');\n\n# Like modulefile, but search up the inheritance tree\n$file = classfile( 'Foo::Bar', 'file/name.txt' );\n", "subsections": [] }, "DESCRIPTION": { "content": "The intent of File::ShareDir is to provide a companion to Class::Inspector and File::HomeDir,\nmodules that take a process that is well-known by advanced Perl developers but gets a little\ntricky, and make it more available to the larger Perl community.\n\nQuite often you want or need your Perl module (CPAN or otherwise) to have access to a large\namount of read-only data that is stored on the file-system at run-time.\n\nOn a linux-like system, this would be in a place such as /usr/share, however Perl runs on a wide\nvariety of different systems, and so the use of any one location is unreliable.\n\nPerl provides a little-known method for doing this, but almost nobody is aware that it exists.\nAs a result, module authors often go through some very strange ways to make the data available\nto their code.\n\nThe most common of these is to dump the data out to an enormous Perl data structure and save it\ninto the module itself. The result are enormous multi-megabyte .pm files that chew up a lot of\nmemory needlessly.\n\nAnother method is to put the data \"file\" after the DATA compiler tag and limit yourself to\naccess as a filehandle.\n\nThe problem to solve is really quite simple.\n\n1. Write the data files to the system at install time.\n\n2. Know where you put them at run-time.\n\nPerl's install system creates an \"auto\" directory for both every distribution and for every\nmodule file.\n\nThese are used by a couple of different auto-loading systems to store code fragments generated\nat install time, and various other modules written by the Perl \"ancient masters\".\n\nBut the same mechanism is available to any dist or module to store any sort of data.\n", "subsections": [ { "name": "Using Data in your Module", "content": "\"File::ShareDir\" forms one half of a two part solution.\n\nOnce the files have been installed to the correct directory, you can use \"File::ShareDir\" to\nfind your files again after the installation.\n\nFor the installation half of the solution, see File::ShareDir::Install and its \"installshare\"\ndirective.\n\nUsing File::ShareDir::Install together with File::ShareDir allows one to rely on the files in\nappropriate \"distdir()\" or \"moduledir()\" in development phase, too.\n" } ] }, "FUNCTIONS": { "content": "\"File::ShareDir\" provides four functions for locating files and directories.\n\nFor greater maintainability, none of these are exported by default and you are expected to name\nthe ones you want at use-time, or provide the ':ALL' tag. All of the following are equivalent.\n\n# Load but don't import, and then call directly\nuse File::ShareDir;\n$dir = File::ShareDir::distdir('My-Dist');\n\n# Import a single function\nuse File::ShareDir 'distdir';\ndistdir('My-Dist');\n\n# Import all the functions\nuse File::ShareDir ':ALL';\ndistdir('My-Dist');\n\nAll of the functions will check for you that the dir/file actually exists, and that you have\nread permissions, or they will throw an exception.\n\ndistdir\n# Get a distribution's shared files directory\nmy $dir = distdir('My-Distribution');\n\nThe \"distdir\" function takes a single parameter of the name of an installed (CPAN or otherwise)\ndistribution, and locates the shared data directory created at install time for it.\n\nReturns the directory path as a string, or dies if it cannot be located or is not readable.\n\nmoduledir\n# Get a module's shared files directory\nmy $dir = moduledir('My::Module');\n\nThe \"moduledir\" function takes a single parameter of the name of an installed (CPAN or\notherwise) module, and locates the shared data directory created at install time for it.\n\nIn order to find the directory, the module must be loaded when calling this function.\n\nReturns the directory path as a string, or dies if it cannot be located or is not readable.\n\ndistfile\n# Find a file in our distribution shared dir\nmy $dir = distfile('My-Distribution', 'file/name.txt');\n\nThe \"distfile\" function takes two parameters of the distribution name and file name, locates\nthe dist directory, and then finds the file within it, verifying that the file actually exists,\nand that it is readable.\n\nThe filename should be a relative path in the format of your local filesystem. It will simply\nadded to the directory using File::Spec's \"catfile\" method.\n\nReturns the file path as a string, or dies if the file or the dist's directory cannot be\nlocated, or the file is not readable.\n\nmodulefile\n# Find a file in our module shared dir\nmy $dir = modulefile('My::Module', 'file/name.txt');\n\nThe \"modulefile\" function takes two parameters of the module name and file name. It locates the\nmodule directory, and then finds the file within it, verifying that the file actually exists,\nand that it is readable.\n\nIn order to find the directory, the module must be loaded when calling this function.\n\nThe filename should be a relative path in the format of your local filesystem. It will simply\nadded to the directory using File::Spec's \"catfile\" method.\n\nReturns the file path as a string, or dies if the file or the dist's directory cannot be\nlocated, or the file is not readable.\n\nclassfile\n# Find a file in our module shared dir, or in our parent class\nmy $dir = classfile('My::Module', 'file/name.txt');\n\nThe \"modulefile\" function takes two parameters of the module name and file name. It locates the\nmodule directory, and then finds the file within it, verifying that the file actually exists,\nand that it is readable.\n\nIn order to find the directory, the module must be loaded when calling this function.\n\nThe filename should be a relative path in the format of your local filesystem. It will simply\nadded to the directory using File::Spec's \"catfile\" method.\n\nIf the file is NOT found for that module, \"classfile\" will scan up the module's @ISA tree,\nlooking for the file in all of the parent classes.\n\nThis allows you to, in effect, \"subclass\" shared files.\n\nReturns the file path as a string, or dies if the file or the dist's directory cannot be\nlocated, or the file is not readable.\n", "subsections": [] }, "EXTENDING": { "content": "", "subsections": [ { "name": "Overriding Directory Resolution", "content": "\"File::ShareDir\" has two convenience hashes for people who have advanced usage requirements of\n\"File::ShareDir\" such as using uninstalled \"share\" directories during development.\n\n#\n# Dist-Name => /absolute/path/for/DistName/share/dir\n#\n%File::ShareDir::DISTSHARE\n\n#\n# Module::Name => /absolute/path/for/Module/Name/share/dir\n#\n%File::ShareDir::MODULESHARE\n\nSetting these values any time before the corresponding calls\n\ndistdir('Dist-Name')\ndistfile('Dist-Name','some/file');\n\nmoduledir('Module::Name');\nmodulefile('Module::Name','some/file');\n\nWill override the base directory for resolving those calls.\n\nAn example of where this would be useful is in a test for a module that depends on files\ninstalled into a share directory, to enable the tests to use the development copy without\nneeding to install them first.\n\nuse File::ShareDir;\nuse Cwd qw( getcwd );\nuse File::Spec::Functions qw( rel2abs catdir );\n\n$File::ShareDir::MODULESHARE{'Foo::Module'} = rel2abs(catfile(getcwd,'share'));\n\nuse Foo::Module;\n\n# internal calls in Foo::Module to modulefile('Foo::Module','bar') now resolves to\n# the source trees share/ directory instead of something in @INC\n" } ] }, "SUPPORT": { "content": "Bugs should always be submitted via the CPAN request tracker, see below.\n\nYou can find documentation for this module with the perldoc command.\n\nperldoc File::ShareDir\n\nYou can also look for information at:\n\n* RT: CPAN's request tracker\n\n\n\n* AnnoCPAN: Annotated CPAN documentation\n\n\n\n* CPAN Ratings\n\n\n\n* CPAN Search\n\n\n\nWhere can I go for other help?\nIf you have a bug report, a patch or a suggestion, please open a new report ticket at CPAN (but\nplease check previous reports first in case your issue has already been addressed).\n\nReport tickets should contain a detailed description of the bug or enhancement request and at\nleast an easily verifiable way of reproducing the issue or fix. Patches are always welcome, too.\n\nWhere can I go for help with a concrete version?\nBugs and feature requests are accepted against the latest version only. To get patches for\nearlier versions, you need to get an agreement with a developer of your choice - who may or not\nreport the issue and a suggested fix upstream (depends on the license you have chosen).\n", "subsections": [ { "name": "Business support and maintenance", "content": "For business support you can contact the maintainer via his CPAN email address. Please keep in\nmind that business support is neither available for free nor are you eligible to receive any\nsupport based on the license distributed with this package.\n" } ] }, "AUTHOR": { "content": "Adam Kennedy \n\nMAINTAINER\nJens Rehsack \n", "subsections": [] }, "SEE ALSO": { "content": "File::ShareDir::Install, File::ConfigDir, File::HomeDir, Module::Install,\nModule::Install::Share, File::ShareDir::PAR, Dist::Zilla::Plugin::ShareDir\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2005 - 2011 Adam Kennedy, Copyright 2014 - 2018 Jens Rehsack.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThe full text of the license can be found in the LICENSE file included with this module.\n", "subsections": [] } }, "summary": "File::ShareDir - Locate per-dist and per-module shared files", "flags": [], "examples": [], "see_also": [] }