Data directories: Difference between revisions
Line 65: | Line 65: | ||
=== Config directory === | === Config directory === | ||
1. If a <b><code>--config-dir=...</code> (<code>-c ...</code>) command-line option</b> is given, always use that config directory. If the requested directory doesn't exist, create it. | 1. If a <b><code>--config-dir=...</code> (<code>-c ...</code>) command-line option</b> is given, always use that config directory. If the requested directory doesn't exist, create it. If it could not be created, abort. | ||
2. If | 2. If the <b>cmake <code>-DCONFIG_DIR_PREFIXES</code> and/or <code>-DCONFIG_DIR</code> options</b> are given, interpret them as a colon-separated (Windows: semicolon-seperated) lists after expanding <b>environment variables</b> and search for all <code>CONFIG_DIR_PREFIXES</code> + <code>CONFIG_DIR</code> permutations ordered by the prefix index first and the suffix index second. Use the first match found. | ||
* {{Windows}} and {{MacOSX}}: <code>CONFIG_DIR</code> and <code>CONFIG_DIR_PREFIXES</code> are not set | * {{Windows}} and {{MacOSX}}: <code>CONFIG_DIR</code> and <code>CONFIG_DIR_PREFIXES</code> are not set | ||
* {{Linux}}: default value for <code>CONFIG_DIR</code> is '<b>arx</b>' | * {{Linux}}: default value for <code>CONFIG_DIR</code> is '<b>arx</b>' | ||
* {{Linux}}: default value for <code>CONFIG_DIR_PREFIXES</code> is '<b><code>$XDG_CONFIG_HOME</code></b>', which defaults to '<b><code>$HOME</code>/.config</b>' at run-time | * {{Linux}}: default value for <code>CONFIG_DIR_PREFIXES</code> is '<b><code>$XDG_CONFIG_HOME</code></b>', which defaults to '<b><code>$HOME</code>/.config</b>' at run-time | ||
3. If | 3. If the preconditions for the previousstep hold, <b>create the first <code>CONFIG_DIR</code> in the first directory of <code>CONFIG_DIR_PREFIXES</code></b> that already exists. If none of the directories in <code>CONFIG_DIR_PREFIXES</code> exist, create the first entry. | ||
4 | 4. Otherwise, use the <b>user directory</b> as the config directory. | ||
If no user directory was found or could be created, quit. | If no user directory was found or could be created, quit. |
Revision as of 16:47, 4 August 2012
This page describes how data / config / save files are located by Arx Libertatis:
The game recognizes three different directories, a data directory, a user directory and a config directory.
- The data directory holds read-only asset data and possibly a cfg_default.ini. The data directory can be empty to only load data from the user directory.
- The user directory holds save games, screenshots, but can also hold asset data that takes priority over that from the data directory (like user-installed mods).
- The config directory holds cfg.ini.
This should allow the game run either from all files in the current directory or from a system-wide installation with per-user config and save files.
Goals
- It should be possible to load data, save and config files from the current working directory.
- Windows installers should be able to specify the directories in the registry.
- By default, linux installations should look in the directories specified by the XDG Base Directory Specification. Other systems should use their respective standard directories.
Default directories
ℹ️ Currently Arx Libertatis requires some filenames and directory names in the user, config and data directories to be lower-case, even on case-insensitive filesystems like Windows'.
This section provides a summary of the default directories. Besides the operating system-specific directories below, Arx Libertatis will use the current working directory as the user and config directory if no system-wide data directory has been found. This allows setting up portable installations of arx. If you want to force arx to use the current directory even if there is a system-wide installation, run it as
arx --no-data-dir --user-dir=. --config-dir=.
Windows
- user and config dir:
- XP: '
%USERPROFILE%
\My Documents\My Games\Arx Libertatis' - Vista and up: '
%USERPROFILE%
\Saved Games\Arx Libertatis'
- XP: '
- data dir: location stored in
HKCU\Software\ArxLibertatis\DataDir
orHKLM\Software\ArxLibertatis\DataDir
registry keys
Linux
- user dir: '~/.local/share/arx/'
- config dir: '~/.config/arx/'
- data dir: '/usr/share/games/arx/' or '/usr/local/share/games/arx/'
macOS
- user and config dir: '~/Library/Application Support/ArxLibertatis/'
- data dir: '/Applications/ArxLibertatis/'
Directory detection procedure
Here the complete detection procedure is detailed. For normal users the default directories described in the previous section should be enough, but the procedure has been designed to allow users to overwrite these directories to accommodate edge cases.
User directory
1. If a --user-dir=...
(-u ...
) command-line option is given, always use that user directory. If the requested directory doesn't exist, create it. If it could not be created, abort.
2. ( Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir
or HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir
registry key exists, use its value. If both exist, use first. If the directory doesn't exists create it. If it could not be created, continue with the next step.
3. If the cmake -DUSER_DIR_PREFIXES
and/or -DUSER_DIR
options are given, interpret them as a colon-separated (Windows: semicolon-seperated) lists after expanding environment variables and search for all USER_DIR_PREFIXES
+ USER_DIR
permutations ordered by the prefix index first and the suffix index second. Use the first match found.
- Windows: default value for
USER_DIR
is 'Arx Libertatis' - Windows: default value for
USER_DIR_PREFIXES
is '%FOLDERID_SavedGames%' which expands to:- Windows XP: the 'My Games' subdirectory in 'My Documents' (default: %USERPROFILE%\My Documents\My Games')
- Windows Vista and up: the standard Saved Games directory (default: '%USERPROFILE%\Saved Games')
- Linux: default value for
USER_DIR
is 'arx' - Linux: default value for
USER_DIR_PREFIXES
is '$XDG_DATA_HOME
', which defaults to '$HOME
/.local/share' at run-time - macOS: default value for
USER_DIR
is 'ArxLibertatis' - macOS: value for
USER_DIR_PREFIXES
is '~/Library/Application Support'
4. If the preconditions for the previousstep hold, create the first USER_DIR
in the first directory of USER_DIR_PREFIXES
that already exists. If none of the directories in USER_DIR_PREFIXES
exist, create the first entry.
5. Otherwise, use the current working directory as the user directory.
If no user directory was found or could be created, quit.
Config directory
1. If a --config-dir=...
(-c ...
) command-line option is given, always use that config directory. If the requested directory doesn't exist, create it. If it could not be created, abort.
2. If the cmake -DCONFIG_DIR_PREFIXES
and/or -DCONFIG_DIR
options are given, interpret them as a colon-separated (Windows: semicolon-seperated) lists after expanding environment variables and search for all CONFIG_DIR_PREFIXES
+ CONFIG_DIR
permutations ordered by the prefix index first and the suffix index second. Use the first match found.
- Windows and macOS:
CONFIG_DIR
andCONFIG_DIR_PREFIXES
are not set - Linux: default value for
CONFIG_DIR
is 'arx' - Linux: default value for
CONFIG_DIR_PREFIXES
is '$XDG_CONFIG_HOME
', which defaults to '$HOME
/.config' at run-time
3. If the preconditions for the previousstep hold, create the first CONFIG_DIR
in the first directory of CONFIG_DIR_PREFIXES
that already exists. If none of the directories in CONFIG_DIR_PREFIXES
exist, create the first entry.
4. Otherwise, use the user directory as the config directory.
If no user directory was found or could be created, quit.
Data directory
1. If a --data-dir=...
(-d ...
) command-line option is given, always use that data directory.
2. If a --no-data-dir
(-n
) command-line option is given, don't use a separate data directory.
3. ( Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\DataDir
registry key exists, use it's value.
4. ( Windows-only) If the HKEY_LOCAL_MACHINE\Software\ArxLibertatis\DataDir
registry key exists, use it's value.
5. If a cmake -DDATA_DIR
and -DDATA_DIR_PREFIXES
options are given and DATA_DIR
is a relative path after expanding environment variables, interpret DATA_DIR_PREFIXES
as a colon-separated (windows: semicolon-seperated) list (after expanding environment variables) and search for DATA_DIR
in each entry. Use the first match found.
- Windows: default value for
DATA_DIR
is 'Arx Libertatis';DATA_DIR_PREFIXES
is not set - Linux: default value for
DATA_DIR
is 'games/arx' - Linux: default value for
DATA_DIR_PREFIXES
is '$XDG_DATA_DIRS
', which defaults to '/usr/local/share/:/usr/share/' at run-time - macOS: default value for
DATA_DIR
is 'ArxLibertatis' - macOS: default value for
DATA_DIR_PREFIXES
is '/Applications'
6. If a cmake -DDATA_DIR
option was given, use it after expanding environment variables.
If a data directory was found but does not exist, clear it. If no data directory was found, that's ok - the user directory can contain all required files.
Troubleshooting
The --list-dirs
(-l
) command-line option can be used to print all the data and user directories considered by the game.
Example output under Linux without a system-wide installation:
Data directories (data files): - --data-dir (-d) command-line parameter - "games/arx" in one of "$XDG_DATA_DIRS" = "/usr/local/share:/usr/share": * "/usr/local/share/games/arx" * "/usr/share/games/arx" - "games/arx" selected: (none) User directories (save files, data files): - --user-dir (-u) command-line parameter - "arx" in one of "$XDG_DATA_HOME" = "/home/user/.local/share": * "/home/user/.local/share/arx" - "arx" - Current working directory selected: "." Config directories: - --config-dir (-c) command-line parameter - "arx" in one of "$XDG_CONFIG_HOME" = "/home/user/.config": * "/home/user/.config/arx" - "arx" - The selected user directory selected: "."