Upgrading File::HomeDir might lose your config files

Reading time: 2 minutes

If you use File::HomeDir, or anything on CPAN that depends on File::HomeDir, you should be aware of a change in behavior in version 0.91 that might create problems.

Specifically, 0.91 is the first production release that adds support for FreeDesktop.org standards for data, config, cache, etc. directories.

Here’s an example of how your config file locations might change by upgrading:

$ cpanm -q ADAMK/File-HomeDir-0.89.tar.gz
$ perl -MFile::HomeDir -E 'say File::HomeDir->my_data'
/home/david

$ cpanm -q ADAMK/File-HomeDir-0.91.tar.gz
$ perl -MFile::HomeDir -E 'say File::HomeDir->my_data'
/home/david/.local/share

So if you upgrade File::HomeDir and your config files aren’t found, that might be the problem. (If you only use File::HomeDir->my_home, you should be OK.)

As a developer, you should think long and hard whether and how you want to use File::HomeDir. On the one hand, it helps you put things in “correct” locations on different operating systems. On the other hand, the definition of “correct” has changed over time. It is supposed to be more stable now, but you have no guarantees.

For projects that already use File::HomeDir, to avoid inconveniencing users with older versions of it, you probably need to add some logic for different versions of File::HomeDir, possibly replicating code in older releases of File::HomeDir so you can find old config files or data. You might also want to bump your File::HomeDir minimum version prerequisite soon and get users past the pain quickly.

For new projects, just make sure your minimum File::HomeDir prerequisite is at least 0.91 and hope that you don’t have to add version-specific code in the future. Or you could limit yourself to just File::HomeDir->my_home, which has been pretty stable, and ignore the content-specific directories, but that sort of defeats the whole purpose of using File::HomeDir in the first place.

If you’re starting from scratch (or if you decide to force users to upgrade and swallow the pain), you should be aware of the new my_dist_config and my_dist_data methods added in File::HomeDir 0.93:

$ cpanm -q ADAMK/File-HomeDir-0.93.tar.gz

$ perl -MFile::HomeDir -wE 'say File::HomeDir->my_dist_config("Foo-Bar", {create => 1})'
/home/david/.config/Perl/Foo-Bar

$ perl -MFile::HomeDir -wE 'say File::HomeDir->my_dist_data("Foo-Bar", {create => 1})'
/home/david/.local/share/Perl/dist/Foo-Bar

That buries everything a little further down under a “Perl” or “Perl/dist” directory, but saves you the extra work of assembling a path under my_config or my_data.

•      •      •

If you enjoyed this or have feedback, please let me know by or