special_dir.hpp File Reference

Well-known per-user, per-machine and per-bundle directories. More...

#include <array>
#include <filesystem>
#include <functional>
#include <optional>
#include <string>
#include <string_view>

Go to the source code of this file.

Classes
struct	pulp::platform::SpecialDirInputs
	Everything the resolver may read, so every platform's layout can be computed (and tested) on any host. More...

Namespaces
namespace	pulp
namespace	pulp::platform
	Device capability vocabulary: one tier ladder, one thermal ladder, and the projection from observed inputs onto them.

Enumerations
enum class	pulp::platform::SpecialDir {   pulp::platform::home , pulp::platform::documents , pulp::platform::desktop , pulp::platform::music ,   pulp::platform::app_data , pulp::platform::app_data_shared , pulp::platform::config , pulp::platform::temp ,   pulp::platform::cache , pulp::platform::logs , pulp::platform::current_executable , pulp::platform::bundle_dir ,   pulp::platform::user_presets }
enum class	pulp::platform::SpecialDirOs {   pulp::platform::macos , pulp::platform::ios , pulp::platform::windows , pulp::platform::linux_desktop ,   pulp::platform::android , pulp::platform::web }
	Operating system a path is shaped for. More...

Functions
std::string_view	pulp::platform::special_dir_name (SpecialDir kind) noexcept
	Stable lower_snake_case name, for diagnostics and tests.
std::filesystem::path	pulp::platform::special_dir (SpecialDir kind)
	Resolve kind for the running process. Empty when unavailable.
void	pulp::platform::set_special_dir_override (SpecialDir kind, std::filesystem::path path)
	Replace the resolved location for kind (a mobile host that learns its sandbox paths late, a test that must not touch the real home).
void	pulp::platform::clear_special_dir_overrides ()
SpecialDirOs	pulp::platform::host_special_dir_os () noexcept
	The host OS this binary was built for.
std::string	pulp::platform::special_dir_for (SpecialDirOs os, SpecialDir kind, const SpecialDirInputs &inputs)
	Resolve kind for os from inputs alone. Empty string when unavailable.

Variables
constexpr std::array< SpecialDir, 13 >	pulp::platform::kAllSpecialDirs

Detailed Description

Well-known per-user, per-machine and per-bundle directories.

special_dir(kind) is the single place that knows where each platform keeps the user's home, documents, application data, caches, logs and so on, so settings, presets, content and log code do not each carry their own #ifdef ladder.

Every function returns an empty path when the location is unknown (no home in the environment, a mobile hook that has not run yet, a kind that does not exist on that platform). Callers must treat empty as "unavailable" and fail closed rather than fall back to a world-shared location such as /tmp. Nothing here creates a directory or checks that it exists.

Thread safety: all functions are safe to call from any thread. They read the environment, so they are not realtime-safe.

Per-platform shape (<name> is whatever the caller appends):

kind	macOS / iOS	Windows	Linux
home	$HOME	USERPROFILE%	$HOME
documents	~/Documents	Documents known folder	$XDG_DOCUMENTS_DIR or ~/Documents
desktop	~/Desktop (macOS only)	Desktop known folder	$XDG_DESKTOP_DIR or ~/Desktop
music	~/Music (macOS only)	Music known folder	$XDG_MUSIC_DIR or ~/Music
app_data	~/Library/Application Support	APPDATA%	$XDG_DATA_HOME or ~/.local/share
app_data_shared	/Library/Application Support (macOS only)	ProgramData%	/usr/share
config	~/Library/Application Support	APPDATA%	$XDG_CONFIG_HOME or ~/.config
temp	$TMPDIR or /tmp	TMP% / TEMP%	$TMPDIR or /tmp
cache	~/Library/Caches	LOCALAPPDATA%	$XDG_CACHE_HOME or ~/.cache
logs	~/Library/Logs	LOCALAPPDATA%\Logs	$XDG_STATE_HOME or ~/.local/state, plus /logs
current_executable	the running executable (a file)	same	same
bundle_dir	<bundle>/Contents/Resources (macOS), <bundle> (iOS)	<name>.vst3\Contents\Resources, else the module's folder	same as Windows
user_presets	~/Library/Audio/Presets	APPDATA%	$XDG_CONFIG_HOME or ~/.config

Android resolves everything under the app files directory supplied by the existing set_app_data_dir hook (the Kotlin PulpFileProvider calls it at startup), so every kind is empty until that hook has run. WebAssembly has no real file system: the kinds resolve inside the in-memory (MEMFS) tree rooted at /home/web_user, with /tmp for temp and / for bundle_dir.

bundle_dir names the resource root of the code that contains pulp-platform, so a plugin gets its own bundle rather than the host's. It falls back to the folder holding the module when the module is not inside a bundle. current_executable is the host process for a plugin.