Data directories: Difference between revisions
Line 17: | Line 17: | ||
== Default directories == | == Default directories == | ||
{{Notice|Currently Arx Libertatis requires | {{Notice|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 | 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 |
Revision as of 00:20, 26 May 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=.
File:Windows icon.png 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
File:Tux.png Linux
- user dir: '~/.local/share/arx/'
- config dir: '~/.config/arx/'
- data dir: '/usr/share/games/arx/' or '/usr/local/share/games/arx/'
File:Apple icon.png Mac OS X
- 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. (File:Windows icon.png Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\DataDir
registry key exists, use it's value.
4. (File:Windows icon.png 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.
- File:Windows icon.png Windows: default value for
DATA_DIR
is 'Arx Libertatis';DATA_DIR_PREFIXES
is not set - File:Tux.png Linux: default value for
DATA_DIR
is 'games/arx' - File:Tux.png Linux: default value for
DATA_DIR_PREFIXES
is '$XDG_DATA_DIRS
', which defaults to '/usr/local/share/:/usr/share/' at run-time - File:Apple icon.png Mac OS X: default value for
DATA_DIR
is 'ArxLibertatis' - File:Apple icon.png Mac OS X: 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.
3. (File:Windows icon.png Windows-only) If the HKEY_CURRENT_USER\Software\ArxLibertatis\UserDir
registry key exists, use it's value.
4. (File:Windows icon.png Windows-only) If the HKEY_LOCAL_MACHINE\Software\ArxLibertatis\UserDir
registry key exists, use it's value.
5. If a cmake -DUSER_DIR
and -DUSER_DIR_PREFIXES
options are given and USER_DIR
is a relative path after expanding environment variables, interpret USER_DIR_PREFIXES
as a colon-separated (windows: semicolon-seperated) list (after expanding environment variables) and search for USER_DIR
in each entry. Use the first match found.
- File:Windows icon.png Windows: default value for
USER_DIR
is 'Arx Libertatis' - File:Windows icon.png 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')
- File:Tux.png Linux: default value for
USER_DIR
is 'arx' - File:Tux.png Linux: default value for
USER_DIR_PREFIXES
is '$XDG_DATA_HOME
', which defaults to '$HOME
/.local/share' at run-time - File:Apple icon.png Mac OS X: default value for
USER_DIR
is 'ArxLibertatis' - File:Apple icon.png Mac OS X: value for
USER_DIR_PREFIXES
is '~/Library/Application Support'
6. If a cmake -DUSER_DIR
option was given, use it after expanding environment variables.
7. If a data directory has been found but no user directory and 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.
8. If a data directory has been found but no user directory and the preconditions for step 6 hold, create USER_DIR
.
9. 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.
- File:Windows icon.png Windows and File:Apple icon.png Mac OS X:
CONFIG_DIR
andCONFIG_DIR_PREFIXES
are not set - File:Tux.png Linux: default value for
CONFIG_DIR
is 'arx' - File:Tux.png 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: "."