From 1383fde3457168ed759d6ed3b913dfae8a6085ef Mon Sep 17 00:00:00 2001
From: Martin Braun <martin.braun@ettus.com>
Date: Thu, 5 Mar 2020 16:23:07 -0800
Subject: 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
---
 host/docs/calibration.dox | 18 +++++++++---------
 host/docs/configfiles.dox |  6 +++---
 2 files changed, 12 insertions(+), 12 deletions(-)

(limited to 'host/docs')

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`
-- 
cgit v1.2.3