File::ConfigDir(3pm)

✨ NAME ✨

File::ConfigDir — bestie, it's literally just "get directories of configuration files" 💖 (this is the File::ConfigDir(3pm) page, Perl's User Contributed Perl Documentation, for the record 🎀)

---

🌸 SYNOPSIS 🌸

use File::ConfigDir ':ALL';

my @cfgdirs = config_dirs();
my @appcfgdirs = config_dirs('app');

# install support
my $site_cfg_dir = (site_cfg_dir())[0];
my $vendor_cfg_dir = (site_cfg_dir()))[0];

🫶 okay so that last line has an extra ) in it and I am not touching it. It's canon. Copy it exactly and move on. slay.

---

💜 DESCRIPTION 💜

So this module is your little helper bestie for installing, reading and finding configuration file locations. It's built to work in every supported Perl5 environment and it will always try to Do The Right Thing(TM). Periodt.

File::ConfigDir is the module you call when your perl modules (especially whole applications 👑) need to read and store config files from more than one location. Writing user configuration is easy peasy thanks to File::HomeDir — but what happens when the system administrator needs to drop some global configuration somewhere? Or when there's system related configuration (in /etc on UNIX(TM), or $ENV{windir} on Windows(TM)) and also some network configuration sitting in NFS mapped /etc/p5-app or $ENV{ALLUSERSPROFILE} . "\\Application Data\\p5-app", respectively. Yeah. That whole vibe. 😭

And listen — File::ConfigDir has no "do what I mean" mode. It's entirely up to you, the user, to pick the right directory for each particular application. It hands you the options, you make the call. main character energy only 💅

---

✨ EXPORT ✨

Every single function listed below can be exported — either by name, or by using the tag :ALL. No gatekeeping here 🫶

---

🦋 SUBROUTINES/METHODS 🦋

Okay so all of these functions can take one optional argument as the application specific configuration directory. If you give it one, it gets embedded at the right (TM) place of the resulting path. iconic.

⭐ system_cfg_dir

Returns the configuration directory where configuration files of the operating system reside. For Unices this is /etc, for MSWin32 it's the value of the environment variable %windir%.

⭐ machine_cfg_dir

Alias for desktop_cfg_dir — deprecated. 💀

⭐ xdg_config_dirs

Alias for desktop_cfg_dir

⭐ desktop_cfg_dir

Returns the configuration directory where configuration files of the desktop applications reside. For Unices this is /etc/xdg, for MSWin32 it's the value of the environment variable %ALLUSERSPROFILE% concatenated with the basename of the environment variable %APPDATA%.

⭐ core_cfg_dir

Returns the etc directory below $Config{prefix}.

⭐ site_cfg_dir

Returns the etc directory below $Config{sitelib_stem} or the common base directory of $Config{sitelib} and $Config{sitebin}.

⭐ vendor_cfg_dir

Returns the etc directory below $Config{vendorlib_stem} or the common base directory of $Config{vendorlib} and $Config{vendorbin}.

⭐ singleapp_cfg_dir

Returns the configuration file for stand-alone installed applications. In Unix speak, installing JRE to /usr/local/jre-<version> means there is a /usr/local/jre-<version>/bin/java and going from it's directory name one above and into etc there is the singleapp_cfg_dir. For a Perl module it means, we're assuming that $FindBin::Bin is installed as a stand-alone package somewhere, e.g. into /usr/pkg — as recommended for pkgsrc <http://www.pkgsrc.org/>.

⭐ vendorapp_cfg_dir

Returns the configuration file for vendor installed applications. In Unix speak, installing bacula to /opt/${vendor} means there is a /opt/${vendor}/bin/bacula and going from it's directory name one above and into etc there is the vendorapp_cfg_dir. For a Perl module it means, we're assuming that $FindBin::Bin is installed as a stand-alone package somewhere, e.g. into /usr/pkg — as recommended for pkgsrc <http://www.pkgsrc.org/>.

⭐ local_cfg_dir

Returns the configuration directory for distribution independent, 3rd party applications. While this directory doesn't exists for MSWin32, there will be only the path /usr/local/etc for Unices.

⭐ locallib_cfg_dir

Extracts the INSTALL_BASE from $ENV{PERL_MM_OPT} and returns the etc directory below it.

⭐ here_cfg_dir

Returns the path for the etc directory below the current working directory.

⭐ user_cfg_dir

Returns the users home folder using File::HomeDir. Without File::HomeDir, nothing is returned. 😭 (yeah, empty handed, it's giving nothing)

⭐ xdg_config_home

Returns the user configuration directory for desktop applications. If $ENV{XDG_CONFIG_HOME} is not set, for MSWin32 the value of $ENV{APPDATA} is return and on Unices the .config directory in the users home folder. Without File::HomeDir, on Unices the returned list might be empty.

⭐ config_dirs

@cfgdirs = config_dirs();
@cfgdirs = config_dirs( 'appname' );

Tries to get all available configuration directories as described above. Returns those who exists and are readable. 💖

⭐ _plug_dir_source

my $dir_src = sub { return _better_config_dir(@_); }
File::ConfigDir::_plug_dir_source($dir_src);

my $pure_src = sub { return _better_config_plain_dir(@_); }
File::ConfigDir::_plug_dir_source($pure_src, 1); # see 2nd arg is true

Registers more sources to ask for suitable directories to check or search for config files. Each config_dirs will traverse them in subsequent invocations, too.

Returns the number of directory sources in case of success. Returns nothing when $dir_src is not a code ref.

---

🎀 AUTHOR 🎀

Jens Rehsack, "<rehsack at cpan.org>" 👑

---

💀 BUGS 💀

Please report any bugs or feature requests to "bug-File-ConfigDir at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ConfigDir>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. 🫶 no bug left behind.

---

🌈 SUPPORT 🌈

You can find documentation for this module with the perldoc command.

perldoc File::ConfigDir

You can also look for information at:

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ConfigDir>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/File-ConfigDir>

• CPAN Ratings

<http://cpanratings.perl.org/d/File-ConfigDir>

• Search CPAN

<http://search.cpan.org/dist/File-ConfigDir/>

---

💅 ACKNOWLEDGEMENTS 💅

Thanks are sent out to Lars Dieckow (daxim) for his suggestion to add support for the Base Directory Specification of the Free Desktop Group. Matthew S. Trout (mst) earns the credit to suggest singleapp_cfg_dir and remind about /usr/local/etc. 🌸 absolute legends, both of them.

---

👑 LICENSE AND COPYRIGHT 👑

Copyright 2010-2018 Jens Rehsack.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

---

🧚 SEE ALSO 🧚

File::HomeDir, File::ShareDir, File::BaseDir (Unices only)

---

okay that's the whole page bestie!! this was perl v5.36.0, dated 2022-12-06, and yes it's still the File::ConfigDir(3pm) page, go forth and find your config dirs 💖✨🦋🎀