Upgrading File::HomeDir might lose your config files

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'

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

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})'

$ perl -MFile::HomeDir -wE 'say File::HomeDir->my_dist_data("Foo-Bar", {create => 1})'

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.

This entry was posted in perl programming, toolchain and tagged , . Bookmark the permalink. Both comments and trackbacks are currently closed.


  1. Tatsuhiko Miyagawa
    Posted January 17, 2011 at 12:24 am | Permalink

    This is not the first time File::HomeDir->my_data gets broken (and thus CPAN config gets lost) - It used to return $HOME but at some point it started to return ~/Library/Application Support/.cpan for Mac OS X. I ranted about this many times on #p5p and CPAN::HandleConfig just special cases $^O eq 'darwin' case :/

  2. Adam Kennedy
    Posted January 20, 2011 at 7:29 am | Permalink

    And yet ~/Library/Application Support/.cpan is precisely the correct place for the .cpan directory...