Data directories: Difference between revisions
(Use templates for OS icons) |
(Update user directory algorithm to reflect code changes) |
||
Line 65: | Line 65: | ||
=== User directory === | === User directory === | ||
1. If a <b><code>--user-dir=...</code> (<code>-u ...</code>) command-line option</b> is given, always use that user directory. If the requested directory doesn't exist, create it. | 1. If a <b><code>--user-dir=...</code> (<code>-u ...</code>) command-line option</b> is given, always use that user directory. If the requested directory doesn't exist, create it. If it could not be created, abort. | ||
3. ({{Windows}}-only) If the <b><code>HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir</code> registry key</b> exists, use | 3. ({{Windows}}-only) If the <b><code>HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir</code> registry key</b> exists, use its value. | ||
4. ({{Windows}}-only) If the <b><code>HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir</code> registry key</b> exists, use | 4. ({{Windows}}-only) If the <b><code>HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir</code> registry key</b> exists, use its value. | ||
5. If | 5. If <b>cmake <code>-DUSER_DIR_PREFIXES</code> and/or <code>-DUSER_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>USER_DIR_PREFIXES</code> + <code>USER_DIR</code> permutations. Use the first match found. | ||
* {{Windows}}: default value for <code>USER_DIR</code> is '<b>Arx Libertatis</b>' | * {{Windows}}: default value for <code>USER_DIR</code> is '<b>Arx Libertatis</b>' | ||
* {{Windows}}: default value for <code>USER_DIR_PREFIXES</code> is '<b>%FOLDERID_SavedGames%</b>' which expands to: | * {{Windows}}: default value for <code>USER_DIR_PREFIXES</code> is '<b>%FOLDERID_SavedGames%</b>' which expands to: | ||
Line 81: | Line 81: | ||
* {{MacOSX}}: value for <code>USER_DIR_PREFIXES</code> is '<b>~/Library/Application Support</b>' | * {{MacOSX}}: value for <code>USER_DIR_PREFIXES</code> is '<b>~/Library/Application Support</b>' | ||
6. If | 6. If the preconditions for step 5 hold, <b>create <code>USER_DIR</code> in the first directory of <code>USER_DIR_PREFIXES</code></b> that already exists. If none of the directories in <code>USER_DIR_PREFIXES</code> exist, create the first entry. | ||
7 | 7. Otherwise, use the <b>current working directory</b> as the user 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:30, 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.
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.
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.
3. ( Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir
registry key exists, use its value.
4. ( Windows-only) If the HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir
registry key exists, use its value.
5. If 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. 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'
6. If the preconditions for step 5 hold, create 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.
7. 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.
2. If a cmake -DCONFIG_DIR
and -DCONFIG_DIR_PREFIXES
options are given and CONFIG_DIR
is a relative path after expanding environment variables, interpret CONFIG_DIR_PREFIXES
as a colon-separated (windows: semicolon-seperated) list (after expanding environment variables) and search for CONFIG_DIR
in each entry. 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 a cmake -DCONFIG_DIR
option was given, use it after expanding environment variables.
4. If a data directory has been found but no config directory and the preconditions for step 2 hold, create 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.
5. If a data directory has been found but no config directory and the preconditions for step 3 hold, create CONFIG_DIR
.
6. Otherwise, use the user directory as the config directory.
If no user directory was found or could be created, quit.
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: "."