1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
# NAME
File::ConfigDir - Get directories of configuration files
<div>
<a href="https://travis-ci.org/perl5-utils/File-ConfigDir"><img src="https://travis-ci.org/perl5-utils/File-ConfigDir.svg?branch=master" alt="Travis CI"/></a>
<a href='https://coveralls.io/github/perl5-utils/File-ConfigDir?branch=master'><img src='https://coveralls.io/repos/github/perl5-utils/File-ConfigDir/badge.svg?branch=master' alt='Coverage Status'/></a>
</div>
# 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];
# DESCRIPTION
This module is a helper for installing, reading and finding configuration
file locations. It's intended to work in every supported Perl5 environment
and will always try to Do The Right Thing(TM).
`File::ConfigDir` is a module to help out when perl modules (especially
applications) need to read and store configuration files from more than
one location. Writing user configuration is easy thanks to
[File::HomeDir](https://metacpan.org/pod/File::HomeDir), but what when the system administrator needs to place
some global configuration or there will be system related configuration
(in `/etc` on UNIX(TM) or `$ENV{windir}` on Windows(TM)) and some
network configuration in NFS mapped `/etc/p5-app` or
`$ENV{ALLUSERSPROFILE} . "\\Application Data\\p5-app"`, respectively.
`File::ConfigDir` has no "do what I mean" mode - it's entirely up to the
user to pick the right directory for each particular application.
# EXPORT
Every function listed below can be exported, either by name or using the
tag `:ALL`.
# SUBROUTINES/METHODS
All functions can take one optional argument as application specific
configuration directory. If given, it will be embedded at the right (TM)
place of the resulting path.
## system\_cfg\_dir
Returns the configuration directory where configuration files of the
operating system resides. 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 resides. 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](https://metacpan.org/pod/File::HomeDir). Without
File::HomeDir, nothing is returned.
## 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](https://metacpan.org/pod/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"](#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](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.
# 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](http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ConfigDir)
- AnnoCPAN: Annotated CPAN documentation
[http://annocpan.org/dist/File-ConfigDir](http://annocpan.org/dist/File-ConfigDir)
- CPAN Ratings
[http://cpanratings.perl.org/d/File-ConfigDir](http://cpanratings.perl.org/d/File-ConfigDir)
- Search CPAN
[http://search.cpan.org/dist/File-ConfigDir/](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`.
# 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](https://metacpan.org/pod/File::HomeDir), [File::ShareDir](https://metacpan.org/pod/File::ShareDir), [File::BaseDir](https://metacpan.org/pod/File::BaseDir) (Unices only)
|
