From c396090412e30410a300f362927c0b1e05f54953 Mon Sep 17 00:00:00 2001
From: Joseph Walton-Rivers <joseph@walton-rivers.uk>
Date: Fri, 2 Sep 2022 03:12:05 +0100
Subject: [PATCH] document platform paths
---
fggl/platform/fallback/paths.cpp | 2 +
fggl/platform/linux/paths.cpp | 2 +
include/fggl/platform/fallback/paths.hpp | 52 +++++++++++++++++++++---
include/fggl/platform/paths.hpp | 3 +-
4 files changed, 52 insertions(+), 7 deletions(-)
diff --git a/fggl/platform/fallback/paths.cpp b/fggl/platform/fallback/paths.cpp
index 1bc8de9..30a9ff4 100644
--- a/fggl/platform/fallback/paths.cpp
+++ b/fggl/platform/fallback/paths.cpp
@@ -16,6 +16,8 @@
// Created by webpigeon on 26/06/22.
//
+#define FGGL_PLATFORM_PATHS fallback
+
#include <cstdlib>
#include "fggl/platform/fallback/paths.hpp"
diff --git a/fggl/platform/linux/paths.cpp b/fggl/platform/linux/paths.cpp
index a414ff1..df68782 100644
--- a/fggl/platform/linux/paths.cpp
+++ b/fggl/platform/linux/paths.cpp
@@ -18,6 +18,8 @@
#include <cstdlib>
+#define FGGL_PLATFORM_PATHS linux
+
#include "fggl/platform/linux/paths.hpp"
#include "fggl/debug/logging.hpp"
diff --git a/include/fggl/platform/fallback/paths.hpp b/include/fggl/platform/fallback/paths.hpp
index f4c3a1e..8526940 100644
--- a/include/fggl/platform/fallback/paths.hpp
+++ b/include/fggl/platform/fallback/paths.hpp
@@ -18,8 +18,8 @@
// see https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
//
-#ifndef FGGL_PLATFORM_LINUX_PATHS_HPP
-#define FGGL_PLATFORM_LINUX_PATHS_HPP
+#ifndef FGGL_PLATFORM_FALLBACK_PATHS_HPP
+#define FGGL_PLATFORM_FALLBACK_PATHS_HPP
#include "fggl/platform/paths.hpp"
@@ -30,20 +30,60 @@
namespace fggl::platform {
+ /**
+ * The environment variable used for containing user configurations.
+ *
+ * The directory mentioned by this environment variable should be read/writeable.
+ * The directory should be used for storing user-editable configuration options (eg. preferences).
+ */
constexpr const char *ENV_USER_CONFIG = "FGGL_CONFIG_HOME";
- constexpr const char *ENV_USER_DATA = "FGGL_DATA_HOME";
- constexpr const char *ENV_USER_CACHE = "FGGL_CACHE_HOME";
- // fallback user paths defined in the XDG spec
+ /**
+ * Fallback user configuration directory.
+ *
+ * Default user configuration directory if none is set by the environment variable.
+ */
constexpr const char *DEFAULT_USER_CONFIG = "user_config";
+
+ /**
+ * The environment variable used for containing engine data.
+ *
+ * This directory is used for storing persistent user data and therefore should be read/writable.
+ * The directory should be used for storing user-modifiable state (eg, save files) or downloaded modifications.
+ */
+ constexpr const char *ENV_USER_DATA = "FGGL_DATA_HOME";
+
+ /**
+ * Fallback user data directory.
+ *
+ * Default user data directory if none is set by the environment variable.
+ */
constexpr const char *DEFAULT_USER_DATA = "user_data";
+ /**
+ * The environment variable used for containing semi-persistent user data.
+ *
+ * The application should be able to expect this directory to exist while the application is running, but otherwise
+ * cannot expect the data to be persistent. It MAY be persistent but the application should not rely on this.
+ * It should be used for resources which can be re-generated if needed, but can be useful if already present.
+ */
+ constexpr const char *ENV_USER_CACHE = "FGGL_CACHE_HOME";
+
struct EnginePaths {
std::filesystem::path userConfig;
std::filesystem::path userData;
std::filesystem::path userCache;
};
+ /**
+ * Fallback implementation of calc engine paths.
+ *
+ * For operating systems we don't know about, this simply uses the environment variables defined above and some
+ * sane defaults to construct the paths used to locate our data and user configuration.
+ *
+ * @param base an application-unique string used to construct the paths.
+ * @return the generated paths, for use with the rest of the engine.
+ */
EnginePaths calc_engine_paths(const char *base);
// search routines for finding data and configuration files
@@ -53,4 +93,4 @@ namespace fggl::platform {
}
-#endif //FGGL_PLATFORM_LINUX_PATHS_HPP
+#endif //FGGL_PLATFORM_FALLBACK_PATHS_HPP
diff --git a/include/fggl/platform/paths.hpp b/include/fggl/platform/paths.hpp
index 6fe099e..c8443a4 100644
--- a/include/fggl/platform/paths.hpp
+++ b/include/fggl/platform/paths.hpp
@@ -23,9 +23,10 @@
#include <vector>
#ifdef __linux__
+ #define FGGL_PLATFORM_PATHS linux
#include "fggl/platform/linux/paths.hpp"
-
#else
+ #define FGGL_PLATFORM_PATHS fallback
#include "fggl/platform/fallback/paths.hpp"
#endif
--
GitLab