filesystem hierarchy standard for game developers
Ray
based on my "cold reading" of the FHS and my limited experience
with it, so I may have missed some important points. Would anyone
more familiar with the FHS and how it's actually interpreted like
to expand, critique or correct this?
Based on FHS 2.3, which is online at http://www.pathname.com/fhs/ .
This is my interpretation of that document as it pertains to games,
which may or may not be the same as others' interpretation. If I've
made any serious mistakes, please point them out.
This is strictly about the Unix filesystem hierarchy standard, which
is (all or mostly) shared by Linux and BSD. Other systems may have
different standards, but I'll leave documenting them to people who
care about those systems.
There are three installation scenarios we care about in installing
games: User-specific, local, and standard.
User-specific installation is installation of a game by a specific
user, for their own use. It may be someone who doesn't have root
priveleges on the machine. This puts all files in that user's
home directory and owned by that user. If the user's account (and
home directory) is deleted, the game is uninstalled.
The FHS imposes no internal structure on a user-specific installation;
a game developer may structure it however he or she likes. If you
support user-specific installation, then your installer should do it
if it detects that it is unable to get the privileges to write in
the directories it would use for a standard installation. User-
specific installations are particularly important to open-source
games because they are often favored by developers who want a personal
copy of the game and its files to scribble on, and these developers
are likely to contribute code.
Local installation is installation of a game by hand, by the
local site administrator. Generally it is used when the site
admin wants the local machine (or the local network) to run
a version of the game different from the standard installation.
This can be because the game had to be changed to fit the
local OS conventions or local censorship policy, or because
they don't want a tournament to be interrupted by an automated
package update, or because they are actively modifying the game
and don't want their experimentation to affect the standard
installation, etc.
A normal game package never does a local installation by
default: 'local' directories are reserved specifically for the
use of the site administrators. You may include an automated
way to make a local installation, but it must never be called
other than by the explicit and intentional command of a local
site administrator. In particular, ordinary package
installations, upgrades, downgrades, or removals must not affect
a local installation.
A standard installation is a game installed in a standard way -
typically by root in the course of updating or installing a
standard package, without any special effort.
I'm going to talk about a game named 'escheresqe' as an example.
Whenever you see that word in one of the directory or filenames
mentioned below, make an appropriate substitution for your game.
Where the FHS specifies a directory used only by a single game,
it doesn't specify the layout or filenames within the directory.
Thus, whenever this document talks about a set of files being
in a particular directory, you're allowed to name them anything
and lay them out however you like within that directory.
game binary:
Is the file /usr/games/escheresqe in a standard installation.
Is the file /usr/local/games/escheresqe in a local installation.
game man page:
Is the file /usr/share/man/man6/escheresqe.6 in a standard installation.
(note, the filename may be escheresqe.6.gz or something rather than
escheresqe.6 depending on man configuration and page storage format)
is the file /usr/local/man/man6/escheresqe.6 in a local installation.
(note, the filename may be escheresqe.6.gz rather than escheresqe.6, as
above)
note: /usr/local/share/man/ is the same directory as /usr/local/man
(one or the other is a symlink - which one may vary from system to
system).
Files of architecture-independent static game data: This is data that
does not change as a result of playing the game. It specifically
*DOES NOT* include high score tables, savefiles, logs, etc. If your
game reads script files that determine game behavior or probabilities,
etc, when initializing, those script files are included. If your game
displays help text that's stored in files, the files belong here.
Go in a directory named /usr/share/games/escheresqe in a standard
installation.
Go in a directory named /usr/local/share/games/escheresqe in a local
installation.
Note: Under ordinary circumstances, attempts to write these locations
usually fail. The game or user running it is not likely to be allowed
to write in these directories, and even if they are, the partition on
which they reside is likely to be mounted readonly in server locations,
or to reside on readonly media in a "live cd."
Note that /usr/share (and /usr/local/share) and its subdirectories
including the static game data and man pages may be on a drive mounted
by several different machines of different architectures which all run
the same version of the OS and "share" the installation data. If you
have data that makes sense on an i386 machine and doesn't make sense
on a SPARC machine, don't put it here.
Source code: Note that most standard game packages do not include
source code - usually it is packaged separately in another installer,
and sometimes it is not provided by the developer.
Goes in a directory named /usr/src/escheresqe in a standard
installation.
Goes in a directory named /usr/local/src/escheresqe in a local
installation.
Modifiable files including high score tables, game play logs,
savefiles, etc ...
Go in a directory named /var/games/escheresqe in a standard
installation.
Go in a directory named /var/local/games/escheresqe in a local
installation.
Configuration files: Site-wide "default" configuration file, if
singular, is the file /etc/escheresqe in both standard and local
installations.
Site-wide "default" configuration files, if there is more than one
file, all go in a directory named /etc/escheresqe in both standard and
local installations.
A per-player config file, if there's only one per player, is the file
.escheresqe in the user's home directory.
If there is more than one per-player config file, then all of them go
into a directory named '.escheresqe' in each player's home directory.
Note that per-player configuration files should not be created by the
installer. They should only be created when the player, having
actually invoked the game, makes a configuration change that differs
from the site-wide or default configuration. If non-players, or
players whose configuration is identical to the default or site-wide
configuration, have their own configuration files, it wastes disk
space.
Note that users' home directories are usually in /home/$username, but
the setup is site-specific, and some users (usually root at least)
don't use /home anyway. So don't rely on the directory named /home.
Use getenv("HOME") or getpwuid(geteuid())->pw_dir or whatever
equivalent you have on your system or in the libraries of your
preferred language to find the user's home directory. 999 times out
of a thousand it'll be in /home, but you never know.
Hope This Helps,
Bear