Using XDG-compliant Config Files - wxWidgets
Skip to content
Using XDG-compliant Config Files
Posted on January 07, 2024
XDG Base Directory Specification has been a standard for organizing<br>application data files under Linux for a long time. Unfortunately, wxWidgets<br>has been around for even longer, and when support for configuration files was<br>added to it back in 1997, the usual convention was still to put these<br>so-called “dot files” directly in the user home directory, which is why an<br>application called myapp would use ~/.myapp as its configuration file by<br>default and this default couldn’t be just changed because this would make the<br>existing applications “lose” their configuration files, annoying their users.
However if this wasn’t a concern, applications can (and this isn’t exactly new<br>as this function exists since many years – thanks to Martin Kögler for<br>contributing it) call
wxStandardPaths::Get().SetFileLayout(wxStandardPaths::FileLayout_XDG);
to have their new files created in XDG-compliant ~/.config directory (or<br>$XDG_CONFIG_HOME if this variable is defined, of course).
This was an easy, and recommended way to use the standard locations for the<br>new programs. However it didn’t completely solve the problem because you had<br>to know about it in order to do add this call to a new application and for the<br>other ones there was still the vexing question of what to do with their<br>existing installations.
So, here is the good news: two recent changes in wxWidgets do, finally, solve<br>this problem fully. First of all, since wxWidgets 3.3.0 wxFileConfig<br>defaults to creating new files under ~/.config by default, even without<br>using FileLayout_XDG, if there is no existing dot file in the home<br>directory. Unlike changing the file layout globally for all functions, this<br>is broadly backwards-compatible because the existing installations are not<br>affected: if there already was a dot file in the home directory, it will still<br>be used. But if the application runs on a new system for the first time, it<br>will behave correctly and avoid polluting the home directory with its files,<br>creating them under ~/.config instead.
And, second, if you’d like to change the configuration file location to the<br>recommended one even for the existing users of your application, this is now<br>as simple as just calling the new wxFileConfig::MigrateLocalFile()<br>function: it does what its name implies and migrates the existing local<br>configuration file to the new location. It is not limited just to this, but<br>the intended use case is, of course, for the applications not already using<br>XDG to call it with wxCONFIG_USE_XDG flag, as following:
// Execute this early during the application startup, before the<br>// global wxConfig object is created.<br>const auto res = wxFileConfig::MigrateLocalFile("myapp", wxCONFIG_USE_XDG);
This will do nothing if there is no existing ~/.config/.myapp file and will<br>move this file to the new location, i.e. ~/.config/myapp/myapp.conf, if it<br>does exist. Or, rather, it will try to move it, but it might fail, so you will<br>also want to check for errors, e.g. like this:
if ( !res.oldPath.empty() ) {<br>if ( res.error.empty() )<br>wxLogMessage("Config file moved from \"%s\" to \"%s\"", res.oldPath, res.newPath);<br>else<br>wxLogWarning("Migrating old config failed: %s.", res.error);
And if it did succeed, which should normally be the case, wxFileConfig will<br>use the file in the new, XDG-compliant, location by default, you don’t have<br>anything special to do.
To summarize, wxFileConfig default behaviour has now changed to be what most<br>people would expect and creating new files in the correct location doesn’t<br>require any effort at all, while moving the existing ones to it is as simple<br>as adding a single function call. However if, for some reason, you’d like to<br>keep the old behaviour, you now need to specify the new wxCONFIG_USE_HOME<br>flag when creating wxFileConfig to force using home directory for the<br>configuration files, no matter what.
Hopefully this will help wx applications to stop using configuration files in<br>the home directory in 2024!
Comments
Please enable JavaScript to view the comments.
Blog Archive
Quick Links
Hello World in wxWidgets
Online Manual
Community Wiki
Report a Bug
GitHub Repository
Development Roadmap
Follow Us
News RSS Feed
Developer Blog
Solutions