uhd: paths: Harmonize around XDG Base Directory specification

Up until now, we completely ignore the XDG specification.

This commit does the following to change that:

- It uses XDG_DATA_HOME and XDG_CONFIG_HOME for cal and config data,
  respectively.
- If config data is in ~/.uhd/uhd.conf, that is still accepted, but if
  it conflicts with $XDG_CONFIG_HOME/uhd.conf, it is ignored and a
  warning is displayed
- The default location for cal data is thus ${HOME}/.local/share/uhd/cal
  on Unix, and %LOCALAPPDATA%\uhd\cal on Windows. This is a change in
  location!
- The UHD_CONFIG_DIR environment variable was confusingly named and is
  now removed. It provided an alternative location than the home
  directory. The same purpose is now much better served by XDG_DATA_HOME
  and XDG_CONFIG_HOME.

The specification can be found here:
specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

9 files changed, 159 insertions, 60 deletions

diff --git a/host/CMakeLists.txt b/host/CMakeLists.txt
index 95f110e9e..2d966fd22 100644
--- a/host/CMakeLists.txt
+++ b/host/CMakeLists.txt
@@ -130,9 +130,9 @@ set(PKG_MAN_DIR share/man/man1)
 # UHD config files
 ########################################################################
 set(UHD_USER_CONF_FILE
-    ".uhd/uhd.conf"
+    "uhd.conf"
     CACHE STRING
-    "Location of the user-specific UHD configuration file, relative to APPDATA (or HOME)"
+    "Location of the user-specific UHD configuration file, relative to APPDATA (or XDG_CONFIG_HOME)"
 )
 if(UNIX)
     set(UHD_SYS_CONF_FILE
diff --git a/host/docs/calibration.dox b/host/docs/calibration.dox
index 764060bb8..4807515a6 100644
--- a/host/docs/calibration.dox
+++ b/host/docs/calibration.dox
@@ -60,20 +60,20 @@ daughterboard's EEPROM:
 \subsection calibration_data Calibration Data
 
 By default, calibration files are stored in the user's home/application
-directory:
+directory (`$XDG_DATA_HOME`):
 
--   **Linux:** `${HOME}/.uhd/cal/`
--   **Windows:** `%APPDATA%\.uhd\cal\`
+-   **Linux:** `${HOME}/.local/share/uhd/cal/`
+-   **Windows:** `%LOCALAPPDATA%\uhd\cal\`
 
-If you would like to specify a custom directory, you can do so with the
-`$UHD_CONFIG_DIR` environment variable:
+Calibration files are binary files with a `.cal` file extension.
 
--   **Custom (any OS):** `${UHD_CONFIG_DIR}/.uhd/cal/`
+If you would like to specify a custom directory, you can do so with the
+`$UHD_CAL_DATA_PATH` environment variable.
 
 Calibration files can easily be moved from one machine to another by copying the
-"cal" directory. Re-running a calibration utility will replace the existing
-calibration file. The old calibration file will be renamed so it may be
-recovered by the user.
+"cal" directory, or individual files therein.  Re-running a calibration utility
+will replace the existing calibration file. The old calibration file will be
+renamed so it may be recovered by the user.
 
 \subsection calibration_data_csv Converting UHD 3.x calibration data to UHD 4
 
diff --git a/host/docs/configfiles.dox b/host/docs/configfiles.dox
index bc210eba9..f32274e73 100644
--- a/host/docs/configfiles.dox
+++ b/host/docs/configfiles.dox
@@ -55,9 +55,9 @@ directly.
    <b><tt>\%programdata%/uhd/uhd.conf</tt></b>. The default can be overwritten
    at compile time by setting `UHD_SYS_CONF_FILE` through CMake.
 2. A user-specific configuration file. On Unix systems, it defaults to
-   `$APPDATA/.uhd/uhd.conf`, where `$APPDATA` is usually the same as the user's
-   home directory, unless `$APPDATA` or `$USER_CONFIG_DIR` are defined. On
-   Windows systems, it simply resolves to <b><tt>\%appdata%</tt></b>.
+   `$XDG_CONFIG_HOME/uhd.conf`, where `$XDG_CONFIG_HOME` is usually the same as
+   `$HOME/.config`. On Windows systems, it also checks
+   <b><tt>\%localappdata%</tt></b> and <b><tt>\%appdata%</tt></b>.
    The default can be overwritten at compile time by setting
    the `UHD_USER_CONF_FILE` through CMake.
 3. A configuration file specified by the environment variable `UHD_CONFIG_FILE`
diff --git a/host/include/uhd/utils/paths.hpp b/host/include/uhd/utils/paths.hpp
index f55f584a5..8bcf22171 100644
--- a/host/include/uhd/utils/paths.hpp
+++ b/host/include/uhd/utils/paths.hpp
@@ -20,9 +20,6 @@ namespace uhd {
 //! Get a string representing the system's temporary directory
 UHD_API std::string get_tmp_path(void);
 
-//! Get a string representing the system's appdata directory
-UHD_API std::string get_app_path(void);
-
 //! Get a string representing the system's library directory
 UHD_API std::string get_lib_path(void);
 
diff --git a/host/lib/include/uhdlib/utils/paths.hpp b/host/lib/include/uhdlib/utils/paths.hpp
index 7caac8a7d..cff9299d6 100644
--- a/host/lib/include/uhdlib/utils/paths.hpp
+++ b/host/lib/include/uhdlib/utils/paths.hpp
@@ -7,6 +7,7 @@
 #ifndef INCLUDED_UHDLIB_UTILS_PATHS_HPP
 #define INCLUDED_UHDLIB_UTILS_PATHS_HPP
 
+#include <boost/filesystem.hpp>
 #include <string>
 
 namespace uhd {
@@ -18,8 +19,29 @@ namespace uhd {
  */
 std::string path_expandvars(const std::string& path);
 
+//! Compatibility function for deprecated CSV file reader. Remove this when CSV
+// format for IQ/DC cal gets removed.
 std::string get_appdata_path(void);
 
+//! Return a path to XDG_DATA_HOME
+//
+// https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+//
+// Even on non-Linux systems, this should return the place where app data is
+// written to. For UHD, this is data such as calibration data.
+boost::filesystem::path get_xdg_data_home();
+
+//! Return a path to XDG_CONFIG_HOME
+//
+// https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+//
+// Even on non-Linux systems, this should return the place where the
+// configuration file can be stored.
+boost::filesystem::path get_xdg_config_home();
+
+//! Return a path to ~/.uhd
+boost::filesystem::path get_legacy_config_home();
+
 } /* namespace uhd */
 
 #endif /* INCLUDED_UHDLIB_UTILS_PATHS_HPP */
diff --git a/host/lib/utils/paths.cpp b/host/lib/utils/paths.cpp
index 3ecd5fe38..54b8e0323 100644
--- a/host/lib/utils/paths.cpp
+++ b/host/lib/utils/paths.cpp
@@ -35,6 +35,8 @@
 
 namespace fs = boost::filesystem;
 
+static constexpr char UHD_CAL_DATA_PATH_VAR[] = "UHD_CAL_DATA_PATH";
+
 /*! Get the value of an environment variable.
  *
  * The returned std::string is the full environment variable string, and thus
@@ -128,6 +130,89 @@ static std::string expand_home_directory(std::string path)
 }
 #endif
 
+fs::path uhd::get_xdg_data_home()
+{
+    std::string xdg_data_home_str = get_env_var("XDG_DATA_HOME", "");
+    fs::path xdg_data_home(xdg_data_home_str);
+    if (!xdg_data_home_str.empty()) {
+        return fs::path(xdg_data_home_str);
+    }
+#ifdef UHD_PLATFORM_WIN32
+    const std::string localappdata = get_env_var("LOCALAPPDATA", "");
+    if (!localappdata.empty()) {
+        return fs::path(localappdata);
+    }
+    const std::string appdata = get_env_var("APPDATA", "");
+    if (!appdata.empty()) {
+        return fs::path(appdata);
+    }
+#endif
+    const std::string home = get_env_var("HOME", "");
+    if (home.empty()) {
+#ifdef UHD_PLATFORM_WIN32
+        const std::string err_msg =
+            "get_xdg_data_home(): Unable to find \%HOME\%, \%XDG_DATA_HOME\%, "
+            "\%LOCALAPPDATA\% or \%APPDATA\%.";
+#else
+        const std::string err_msg =
+            "get_xdg_data_home(): Unable to find $HOME or $XDG_DATA_HOME.";
+#endif
+        throw uhd::runtime_error(err_msg);
+    }
+    return fs::path(home) / ".local" / "share";
+}
+
+fs::path uhd::get_xdg_config_home()
+{
+    std::string xdg_config_home_str = get_env_var("XDG_CONFIG_HOME", "");
+    fs::path xdg_config_home(xdg_config_home_str);
+    if (!xdg_config_home_str.empty()) {
+        return fs::path(xdg_config_home_str);
+    }
+#ifdef UHD_PLATFORM_WIN32
+    const std::string localappdata = get_env_var("LOCALAPPDATA", "");
+    if (!localappdata.empty()) {
+        return fs::path(localappdata);
+    }
+    const std::string appdata = get_env_var("APPDATA", "");
+    if (!appdata.empty()) {
+        return fs::path(appdata);
+    }
+#endif
+    const std::string home = get_env_var("HOME", "");
+    if (home.empty()) {
+#ifdef UHD_PLATFORM_WIN32
+        const std::string err_msg =
+            "get_xdg_config_home(): Unable to find \%HOME\%, \%XDG_CONFIG_HOME\%, "
+            "\%LOCALAPPDATA\% or \%APPDATA\%.";
+#else
+        const std::string err_msg =
+            "get_xdg_config_home(): Unable to find $HOME or $XDG_CONFIG_HOME.";
+#endif
+        throw uhd::runtime_error(err_msg);
+    }
+    return fs::path(home) / ".config";
+}
+
+fs::path uhd::get_legacy_config_home()
+{
+#ifdef UHD_PLATFORM_WIN32
+    const std::string localappdata = get_env_var("LOCALAPPDATA", "");
+    if (!localappdata.empty()) {
+        return fs::path(localappdata) / ".uhd";
+    }
+    const std::string appdata = get_env_var("APPDATA", "");
+    if (!appdata.empty()) {
+        return fs::path(appdata) / ".uhd";
+    }
+#endif
+    const std::string home = get_env_var("HOME", "");
+    if (home.empty()) {
+        throw uhd::runtime_error("Unable to find $HOME.");
+    }
+    return fs::path(home) / ".uhd";
+}
+
 /***********************************************************************
  * Implement the functions in paths.hpp
  **********************************************************************/
@@ -173,23 +258,6 @@ std::string uhd::get_tmp_path(void)
 #endif
 }
 
-std::string uhd::get_app_path(void)
-{
-    const std::string uhdcalib_path = get_env_var("UHD_CONFIG_DIR");
-    if (not uhdcalib_path.empty())
-        return uhdcalib_path;
-
-    const std::string appdata_path = get_env_var("APPDATA");
-    if (not appdata_path.empty())
-        return appdata_path;
-
-    const std::string home_path = get_env_var("HOME");
-    if (not home_path.empty())
-        return home_path;
-
-    return uhd::get_tmp_path();
-}
-
 // Only used for deprecated CSV file loader. Delete this once CSV support is
 // removed.
 std::string uhd::get_appdata_path(void)
@@ -242,21 +310,14 @@ std::string uhd::get_lib_path(void)
 
 std::string uhd::get_cal_data_path(void)
 {
-    const std::string uhdcalib_path = get_env_var("UHD_CAL_DATA_PATH");
+    // The easy case: User has set the environment variable
+    const std::string uhdcalib_path = get_env_var(UHD_CAL_DATA_PATH_VAR);
     if (not uhdcalib_path.empty()) {
         return uhdcalib_path;
     }
 
-    std::string xdg_data_home_str = get_env_var("XDG_DATA_HOME", "");
-    fs::path xdg_data_home(xdg_data_home_str);
-    if (xdg_data_home_str.empty()) {
-        const std::string home = get_env_var("HOME", "");
-        xdg_data_home          = fs::path(home) / ".local" / "share";
-    }
-
-    // FIXME: This needs to check if paths make sense, work on Windows, etc.
-
-    fs::path cal_data_path = fs::path(xdg_data_home) / "uhd" / "cal_data";
+    // If not, we use the default location
+    const fs::path cal_data_path = get_xdg_data_home() / "uhd" / "cal";
     return cal_data_path.string();
 }
 
diff --git a/host/lib/utils/paths_python.hpp b/host/lib/utils/paths_python.hpp
index fb91ec373..f738904ca 100644
--- a/host/lib/utils/paths_python.hpp
+++ b/host/lib/utils/paths_python.hpp
@@ -12,9 +12,9 @@
 void export_paths(py::module& m)
 {
     m.def("get_tmp_path", &uhd::get_tmp_path);
-    m.def("get_app_path", &uhd::get_app_path);
-    m.def("get_pkg_path", &uhd::get_pkg_path);
     m.def("get_lib_path", &uhd::get_lib_path);
+    m.def("get_pkg_path", &uhd::get_pkg_path);
+    m.def("get_cal_data_path", &uhd::get_cal_data_path);
     m.def("get_images_dir", &uhd::get_images_dir);
     m.def("find_image_path", &uhd::find_image_path);
     m.def("find_utility", &uhd::find_utility);
diff --git a/host/lib/utils/prefs.cpp b/host/lib/utils/prefs.cpp
index 72a9c9eea..58c47f730 100644
--- a/host/lib/utils/prefs.cpp
+++ b/host/lib/utils/prefs.cpp
@@ -17,7 +17,7 @@ using namespace uhd;
 namespace {
 constexpr char UHD_CONF_FILE_VAR[] = "UHD_CONFIG_FILE";
 
-inline void _update_conf_file(
+inline bool _update_conf_file(
     const std::string& path, const std::string& config_type, config_parser& conf_file)
 {
     if (not path.empty()) {
@@ -27,15 +27,19 @@ inline void _update_conf_file(
                 conf_file.read_file(path);
                 UHD_LOG_DEBUG(
                     "PREFS", "Loaded " << config_type << " config file " << path);
+                return true;
             } catch (...) {
                 UHD_LOG_DEBUG(
                     "PREFS", "Failed to load " << config_type << " config file " << path);
+                return false;
             }
         } else {
             UHD_LOG_TRACE(
                 "PREFS", "No " << config_type << " config file found at " << path);
+            return false;
         }
     }
+    return false;
 }
 
 void update_from_key(
@@ -76,10 +80,26 @@ config_parser& uhd::prefs::get_uhd_config()
         UHD_LOG_TRACE("CONF", "Initializing config file object...");
         const std::string sys_conf_file = path_expandvars(UHD_SYS_CONF_FILE);
         _update_conf_file(sys_conf_file, "system", _conf_files);
+        // prefer .config/uhd.conf
+        // otherwise ~/.uhd/uhd.conf
         const std::string user_conf_file =
-            (boost::filesystem::path(get_app_path()) / std::string(UHD_USER_CONF_FILE))
-                .string();
-        _update_conf_file(user_conf_file, "user", _conf_files);
+            (get_xdg_config_home() / std::string(UHD_USER_CONF_FILE)).string();
+        const bool user_conf_loaded =
+            _update_conf_file(user_conf_file, "user", _conf_files);
+        // Config files can be in ~/.config/ or in ~/.uhd. The latter is
+        // considered deprecated. We load from there (if we have not already
+        // loaded from ~/.config), but we show a warning.
+        if (!user_conf_loaded
+            && _update_conf_file(
+                   (get_legacy_config_home() / std::string(UHD_USER_CONF_FILE)).string(),
+                   "user",
+                   _conf_files)) {
+            UHD_LOG_WARNING("PREFS",
+                "Loaded config from " << get_legacy_config_home().string()
+                                      << ". This location is considered deprecated, "
+                                         "consider moving your config file to "
+                                      << get_xdg_config_home().string() << " instead.");
+        }
         std::string env_conf_file;
         try { // getenv into std::string can fail
             if (std::getenv(UHD_CONF_FILE_VAR) != NULL) {
diff --git a/host/tests/paths_test.cpp b/host/tests/paths_test.cpp
index 5115891b0..930b34ec8 100644
--- a/host/tests/paths_test.cpp
+++ b/host/tests/paths_test.cpp
@@ -41,19 +41,18 @@ BOOST_AUTO_TEST_CASE(test_get_paths)
 {
     using namespace uhd;
 
-    const std::string tmp_path = get_tmp_path();
-    const std::string app_path = get_app_path();
-    const std::string pkg_path = get_pkg_path();
-    const std::string cal_path = get_cal_data_path();
-    const auto module_paths    = get_module_paths();
+    std::cout << "tmp_path: " << get_tmp_path() << std::endl;
+    BOOST_CHECK(true);
+    std::cout << "pkg_path: " << get_pkg_path() << std::endl;
+    BOOST_CHECK(true);
+    std::cout << "cal_path: " << get_cal_data_path() << std::endl;
+    BOOST_CHECK(true);
 
-    std::cout << "tmp_path: " << tmp_path << std::endl;
-    std::cout << "app_path: " << app_path << std::endl;
-    std::cout << "pkg_path: " << pkg_path << std::endl;
-    std::cout << "cal_path: " << cal_path << std::endl;
+    const auto module_paths    = get_module_paths();
     for (const auto& module_path : module_paths) {
         std::cout << "module path: " << module_path << std::endl;
     }
+    BOOST_CHECK(true);
 
     const std::string images_dir_search_path = "";
     const std::string images_dir             = get_images_dir(images_dir_search_path);