Part of mde: a Modular D game-oriented Engine
Copyright © 2007-2008 Diggory Hardy

This program is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License, version 2, as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */


### mde paths ###

+++ Basic directories +++
Note: multiple paths may be used for each "directory", with their contents merged upon loading.
Below, there is a list of each path to merge content from for each "directory", for each OS.
However, "A or B" doesn't mean merge from paths A and B, but use the first existing path out of A
and B only (creating A when necessary if neither exist), and merging this path with any other
existing entries. When writing data, it should be written to whichever path is most appropriate.

Marks:
    +   merged
    -   chosen between
    *   not applicable

* Binaries          Where the executables are located (not needed to be known by the engine).
+ Static data       Static data (translations, levels, meshes, sounds, and probably much more)
+ Configuration     Generally defined as variable data not tied to any particular save and not a
                        cache or log
- Cache             Generated and locally regeneratable data, either only dependant on static data
                        or specifying any variable data
- Log               Log file (may or may not be written depending on configuration). FILE not DIR.
- Save              Save games. Some type of grouping is needed where multiple users use the same
                    location for easier access, and auto/quick/manual saves are game specific
                    (grouped by game so that auto/quick saves from different games don't conflict).

Paths below are listed in the format:
# x   path
#     description
Where x is the priority of path; data loaded from paths with a higher priority overrides that of
lower priority paths (when merging applies), or is the preferred path to use.

Items described as optional are not normally used, however mde can be made to use them, in some
cases by creating the paths (and possibly removing higher priority locations) and in some cases via
configuration.

Items described as shared are system-specific and shared between users on that system.


+++ Common paths +++
(meaning common to a platform-dependant path)

STATIC
    System dependant base data directory. Falls back to current directory if all else fails.

USER
    A directory specific to the machine user-account and writable to that user.

Static data:
0   [STATIC]
    Base data dir (also contains supplied conf dir). Shared.
1   [USER]/data
    User-supplied static data (e.g. mods)

Configuration:
0   [STATIC]/conf
    Packaged/preconfigured config files (shared)
2   [USER]/conf
    User-specific config files

Cache:
0   [USER]/cache
    Alternate cache location

Log:
1   [USER]/log
    Optional log file location (logging in itself is optional)

Save:
1   [USER]/save
    Usual save-file directory



+++ Linux paths +++
--- Relevant policies (Filesystem Hierarchy Standard) ---
http://www.debian.org/doc/packaging-manuals/fhs/fhs-2.3.html

* /usr/local        mostly as for /usr, but for locally installed software
* /etc              configuration files/directory for local configuration (done by admin)
* $HOME             user-specific config in a file or under a directory starting with a dot
* /var/cache        Application cache data
* /var/crash        System crash dumps*
* /var/log          Log files and directories
* /var/local        Variable data for /usr/local

Game specific:
* /usr/games        binaries
* /usr/share/games  architechture-independant static data
* /var/games        non-static data, e.g. high scores, saves

--- what to use ---

USER:
*   (HOME)/.config/mde or (HOME)/.mde
    Base dir for user-specific data

STATIC:
*   /usr/share/games/mde or /usr/local/share/games/mde or ./data
    Base data dir (shared)

Binaries:
*   /usr/games or /usr/local/games
    All binaries (suggested locations only since it doesn't matter to mde)

Configuration:
1   /etc/mde
    Optional shared config files

Cache:
1   /var/cache/mde
    Shared cache. Use this location if possible, since system can handle the cache and it's shared.

Log:
0   /var/log/mde
    Optional shared log file location

Save:
0   /var/games/mde/save
    Optional shared save-file directory



+++ Windows paths +++
--- Relevant policies (?) ---
http://technet2.microsoft.com/windowsserver/en/library/093238f3-5064-470e-a281-0eb1c28b9cf01033.mspx?mfr=true

Note: Local Settings contains:
    Application settings and data that do not roam with the profile. Usually either machine specific, or too large to roam effectively.
Thus this is probably the best place for user data.

--- what to use ---

USER:
*   Docs&Settings/USER/Local Settings/Application data/mde
    Base dir for user-specific data

INSTALL:
*   [from registry] or .
    Base dir from install (shared)

STATIC:
*   [INSTALL]/data
    Base data dir (shared)

Binaries:
*   [INSTALL]/bin
    All binaries (suggested locations only since it doesn't matter to mde).

Configuration:
1   [INSTALL]/conf
    Optional shared config files

Cache:
1   [INSTALL]/cache
    Preferred cache location because it's shared.

Log:
0   [INSTALL]/log
    Optional shared log file location

Save:
0   [INSTALL]/save
    Optional shared save-file directory