\chapter{To Every Man a Linux Distribution}
\label{ch:gameinstall}

\index{distributions (of Linux)}
You've probably noticed that there are a \emph{lot} of Linux distributions floating around the Internet. Some of these are major commercial operations (Red Hat, SuSE, Caldera), some are massive community efforts (Debian), and some don't really fit into either category (my personal favorite, Slackware). Competition is good, but this assortment sometimes leads to incompatibilities between distributions, which you'll have to contend with when you release your work to the public.

Once your game is ready to see the light of day, you'll need to come up with a way for users to install it. This could be as simple as a \filename{.tar.gz} archive (\firstterm{tarball}) containing your game's source code and data files, or it could be as complex as a CD-ROM-based graphical setup system. Whatever you decide to do, you'd be well advised to respect the Linux filesystem standard and account for the differences between various Linux distributions. If you don't, you'll irritate users at the very least and possibly cause serious problems. On the brighter side, a well-packaged program can make a good first impression.

\section{Source or Binary?}
\index{source versus binary distribution}
\index{binary versus source distribution}
\index{open source}\index{free software}
The first decision you'll have to make is whether you want to release the source code to your game. Generally speaking, it's a nice thing to do, and it's more or less a requirement if you're using libraries covered under the GNU General Public License.\footnote{The GNU GPL is much stricter in this sense than the LGPL. See \ulink{http://www.gnu.org} for more information on these licenses. SDL is released under the LGPL, which can be used in closed games, under certain conditions.} Releasing the source code to your project means that bugs will probably turn up much more quickly (since everyone will be able to pitch in and help you track them down), and other programmers will have the opportunity to learn from your code. Linux exists because of its open source development model, and many Linux advocates feel strongly about open versus closed source. For various viewpoints on free software, open source software, and the rationale of each, refer to the \website{Free Software Foundation}{http://www.fsf.org} and the \website{Open Source Initiative}{http://www.opensource.org}.

Sometimes it's either impossible or impractical to release the code to a project. For instance, nondisclosure agreements, publishing contracts, and game engine licenses might prevent you from making a project's code available to the public. In this case you'll have to settle for a binary distribution of your game. Unfortunately, in doing so, you'll probably alienate a certain number of hard-core open source and free software advocates.

\longpage
Binary-only distribution is possible, but you'll have to give a bit of thought to preparing the binary files. Binary distribution under Linux is a bit different than binary distribution under Windows (where source distribution is almost unheard of). With source distribution, a user can adjust the game to work well on a particular machine (and can modify the game to his or her liking), but binary releases are generally one-size-fits-all. Since various Linux distributions ship with different versions of basic supporting software (in particular the C library), a given binary might not get along with some systems.\footnote{Microsoft Windows has the same problem. Most application vendors fix this by shipping basic system libraries (the MFC runtime, the Visual Basic library, and the Visual \cplusplus{} runtime in particular) with each copy of the application. You're likely to find several copies of the same library on any given Windows system, and Windows users sometimes run into problems with incorrect library versions.}


\section{Local Configuration}
\index{distributions (of Linux)}
As we've said, each Linux distribution is slightly different, with its own ideas about how the Linux filesystem standard should be implemented (more on this later), and with a slightly different \filename{etc/} directory tree. In addition, users are generally given a choice of which libraries and other supporting packages to install, meaning that you can't count on the presence of any particular development library. For these reasons, getting a large program to compile and link correctly on a given Linux installation can be quite a challenge.

There are several ways to approach this problem. Some developers opt to specify local configuration options directly in a project's makefile. For instance, the following lines might show up in a makefile for an OpenGL-based project:

\begin{codesegment}
\begin{verbatim}
# Configuration section

CC=      gcc
CFLAGS=  -O2 -W -Wall -pedantic
X11LIBS= -L/usr/X11R6/lib -lX11 -lXt -lXext
GLLIBS=  -lGL -lGLU -lglut

# End of configuration.
\end{verbatim}
\end{codesegment}

This is a bit of a hack, but it's sufficient in some cases. All of the necessary libraries are listed in an easy-to-find spot in the makefile, so that a user can quickly configure the project to compile on his or her system. The program would presumably come with a \filename{README} file explaining how to do this. Users who don't know anything about makefiles, C, or programming in general might find this solution a bit intimidating, however.

\index{Autoconf}\index{GNU Autoconf}
A better option is the GNU Autoconf facility. Autoconf is a sophisticated set of m4 scripts\footnote{m4 is a very simple but powerful macro language that people seem to either love or hate.} that automatically configure source trees for compilation on a variety of systems. Based on information in \filename{Makefile.am} files throughout a source tree, Autoconf (more specifically the Automake program) generates a script called \filename{configure} that will configure the project's makefiles to correctly build and install everything for the current system. Ideally, Autoconf-enabled programs are very easy to install, with a sequence of commands like the following:

\begin{shell}
\begin{verbatim}
$ tar xvfz fooblaster-1.1.tar.gz
$ cd fooblaster-1.1
$ ./configure
$ make
$ make install
\end{verbatim}
\end{shell}
% $

\index{configure script|see{GNU Autoconf}}
If you've ever installed software on a Linux system, this probably looks familiar. Of course this example is just meant to illustrate how convenient Autoconf can be---it's probably a bad idea to install a program blindly without reading the docs (or without typing \code{./configure --help} to get a list of configuration options).

What exactly does this black box of a script do? You may have noticed that Autoconf-enabled source trees are full of files called \filename{Makefile.in}. The \code{configure} script first gathers information about the local system, and then goes through the source directory and converts these files into final makefiles for the project. As it copies each \filename{Makefile.in} to a corresponding \filename{Makefile}, \code{configure} adds a bunch of environment variables that describe the system, as well as special preprocessor symbols that C programs can use for customization. A simple invocation of the Make utility can then build the fully configured program. It's worth noting that you should never need to alter a \code{configure} script by hand; the proper way to make changes is to edit \filename{Makefile.am} and generate a new script.

Autoconf can be fairly complex to set up, and we'll leave a discussion of its specifics to other sources. Learning Autoconf is definitely worth the effort if you plan to make a large source tree available to your users.


\section{Linux Isn't Alone: Supporting FreeBSD}
\index{FreeBSD!supporting|(}
Linux isn't the only contender in the free OS arena.\footnote{Although I speak of Linux here as a complete operating system, the more correct term would be ``Linux-based system,'' or as the Free Software Foundation would prefer, ``Linux-based GNU system.'' FreeBSD is the whole shabang---that is, unlike Linux, FreeBSD encompasses a complete operating system, including a kernel and a set of software. There is only one FreeBSD distribution, coordinated by a well-defined team of volunteers.} FreeBSD is a very similar system with an active and knowledgeable user community. Although FreeBSD can theoretically run Linux binaries out of the box, a few differences sometimes prevent Linux applications (and games) from working. Aside from these minor glitches, FreeBSD is rather easy to support (and certainly worthwhile, given its userbase), so it's a good idea to keep a few things in mind as you develop:

\begin{itemize}
	\item Half of the work in supporting FreeBSD is getting your build environment set up. This should be easy: almost all Linux libraries are also available under FreeBSD, as well as all of the familiar GNU development utilities. Once you get your application to compile under FreeBSD, the rest is a piece of cake. This is a good reason to use Autoconf; with a bit of help from the \code{configure} script, there's a good chance that your project will require no modifications whatsoever for FreeBSD.

Note that the GNU Make utility is called gmake under FreeBSD. The Make utility distributed with FreeBSD is actually BSD Make, which is somewhat incompatible with GNU Make. If you plan to use Autoconf, you definitely want GNU Make.

	\item FreeBSD's filesystem is very similar to a typical Linux distribution's filesystem, and you should treat it accordingly. We'll discuss filesystem politeness later in this chapter.

	\item \index{proc filesystem@\filename{proc/} filesystem}As a descendent of the original BSD, FreeBSD has no \filename{proc/} filesystem (which the Linux kernel uses to publish live information about the system). You probably shouldn't mess with \filename{proc/} in most cases (since its exact layout depends on the current version of the kernel), but it's sometimes the only sane way to get statistics about the system. If your program depends on \filename{proc/}, you'll probably have to do some porting.

	\item FreeBSD has no \filename{/etc/mtab} file (which normally contains a list of currently mounted filesystems). This discrepancy broke Loki Software's CD-ROM detection code when we tried to port it from Linux to FreeBSD. I fixed it with a quick hack based on the output of the mount program, but another programmer later found out that FreeBSD has a convenient system call for retrieving the same information.

	\item FreeBSD has a completely different kernel than Linux. Slight internal differences might cause quirky behavior when you run your newly ported program. For instance, networking, memory mapping (\code{mmap}), and thread scheduling might behave differently, since these functions are closely tied into the kernel. These usually aren't show-stopping issues, but it's a good idea to test your application thoroughly if you intend to officially support FreeBSD.

	\item Unfortunately, FreeBSD currently has no framebuffer device interface. Of course this won't matter if your application uses an abstraction layer such as SDL, but programs that require the Linux framebuffer interface are out of luck. However, FreeBSD does support the Direct Rendering Infrastructure, a lightning-fast 3D driver system originally created for Linux.
\end{itemize}

Several other free UNIX-like operating systems (particularly NetBSD and OpenBSD) are available, and it is nice to support these as well. You'll have to decide how much development time and energy you want to spend on porting your work. If you're developing free software, other people will probably help you with this job. Everyone likes to see new software for his or her favorite operating system, and porting a substantial chunk of code to a new platform can be very satisfying.
\index{FreeBSD!supporting|)}

\section{Packaging Systems}
\index{tarball distribution}
A simple tarball of source code is probably the easiest way to distribute a Linux application or game, and this is perfectly acceptable in some cases (especially if the project takes advantage of Autoconf). However, source tarballs have several disadvantages:

\begin{itemize}
	\item Although they're developer-friendly, source tarballs aren't exactly newbie-friendly. New Linux users often aren't comfortable with building and installing software from source. (They'll probably want to learn how to do this eventually, of course; it really isn't too difficult.)

	\item Some systems aren't meant to be developer workstations and therefore don't have the necessary compilers and libraries to build a source tree.

	\item A lot of people just want to download and install software without having to compile anything. In addition to the time it takes to build a project from source, binary distributions are often smaller than source distributions.
\end{itemize}

\index{tarball distribution!versus packages}
For these and other reasons, many Linux developers make precompiled packages of their software available. Each Linux distribution has its own idea of what exactly constitutes a ``package,'' and so developers often choose just one or two major distributions to support. The two most commonly supported package types are Red Hat's RPM and Debian's DEB. Neither of these are specific to their ``parent'' Linux distributions; SuSE, Caldera, and TurboLinux are RPM-based, and Debian's packaging system has found its way into Corel Linux and Storm Linux (which are actually Debian offshoots).

Package systems provide a bit of extra functionality over source tarballs. Package managers can usually install a package with a single command (in the case of RPM, the command \cmdline{rpm -i package.rpm} does everything), they keep track of all files that were installed so that they can be removed later, and they can facilitate version upgrades. Most importantly, package managers can help enforce \firstterm{dependencies}. If your game needs version 1.1.6 or later of the SDL library, for instance, a package manager will make sure that the system has it before allowing the user to install the game.

\shortpage\shortpage\shortpage
If you want to learn how to make your own RPM packages, take a look at the book \othertitle{Maximum RPM} by Edward C. Bailey. (This book is also available in its entirety online at \ulink{http://www.rpmdp.org/rpmbook/}.) RPM is not a simple tool by any means, but, like Autoconf, it's worth learning if you intend to maintain complicated Linux software packages. Debian packages are even a bit trickier to roll than RPMs, but they are explained in detail on the \website{Debian project's developer Web site}{http://www.debian.org/devel}.

\begin{note}{Making Slackware Packages}
\index{Slackware!making packages}
Unlike RPM and Debian packages, packages for Slackware Linux are quite easy to create. To make a Slackware package, install your program into a \firstterm{fake root}. (For instance, copy files into \filename{tmp/foobar/usr/bin/} instead of \filename{usr/bin/}.) All of your program's installable files should be there, but nothing else; there's no need to duplicate anything not related to your program. Make sure that the permissions on each file are correct and that all symbolic links are in place. When the fake root tree is ready to go, run the \code{makepkg} script (included with Slackware) to create a \filename{.tgz} package that can be installed with Slackware's \code{installpkg} script. \filename{.tgz} packages are really just tarballs with a bit of extra information; you can even install them manually (but that's a bad idea).
\end{note}

Users really appreciate it when you take the time to create packages for their favorite distribution---it can save them a lot of work and help them keep their systems organized. However, maintaining packages does take a bit of work. If you have to choose just one package type to support, it should probably be RPM. If you'd like to maintain packages for a particular distribution, but don't have the time to do so, just ask around online. Chances are good that someone enjoys making packages for that distribution and wouldn't mind lending a hand.

As a closing thought, I'd like to point out that it is a very bad idea to release your software in \filename{.rpm} or \filename{.deb} packages without providing a simple \filename{.tar.gz} option as well; many users (myself included) prefer to avoid package managers entirely and install everything by hand.


\section{Graphical Installation Goodness: Loki's Setup Program}
\index{Loki Setup|(}
Packages and tarballs are the staples of open source and free software distribution, but they might not meet your needs. Off-the-shelf, boxed software generally includes a nice, graphical installation program that copies the software from its CD-ROM to the user's hard drive and performs various setup tasks. This would be easy to accomplish with a simple shell script, but it wouldn't be pretty (the Linux version of \gametitle{Maple}, an excellent computer-assisted mathematics system, uses a shell script for installation, and it is indeed ugly). A badly written installation script could leave a first-time player with a bad impression of the game as a whole, and the game industry is far too competitive for us to let that happen.

Loki Software, Inc.\ developed Loki Setup to satisfy its need for a simple, consistent, and portable installation system. Setup reads a product-specific installation script from an XML file and then presents the user with a GTK-based installation wizard. If X11 isn't available, Setup provides an equivalent terminal-based interface. Setup can check disk space, copy files, run scripts, and launch the newly installed application when everything is finished. Loki Setup is free software, released under the GNU GPL. (And since the Setup program is separate from the software it installs, you can still use Loki Setup for nonfree software without being affected by the GPL.)

To understand how to use Setup for a CD-ROM title, let's take a look at Loki's \gametitle{Heavy Gear II} CD. This is a major commercial title, originally written for Windows but later ported to Linux. We'll start with the top-level directory:

\begin{filelist}
\begin{verbatim}
./autorun.inf
./binaries.tar.gz
./data.tar.gz
./icon.bmp
./icon.xpm
./README
./setup.sh
\end{verbatim}
\end{filelist}

\filename{setup.sh} is a shell script that invokes the appropriate setup binary for the system's architecture. These binaries are located in subdirectories of \filename{setup.data}, which we'll examine in a moment. The script locates the correct subdirectory with the output of the \code{uname -m} command. \filename{autorun.inf} is a Windows autorun file to deal with users who mistakenly try to install this Linux game on a Windows machine. The various icons and tarballs are game-specific.

And now the \filename{bin/} directory:
\begin{filelist}
\begin{verbatim}
./bin
./bin/x86
./bin/x86/glibc-2.1
./bin/x86/glibc-2.1/hg2
./bin/x86/glibc-2.1/libMesaMatroxGL.so.3.2.000121
./bin/x86/glibc-2.1/libMesaVoodooGL.so.1.2.030300
./bin/x86/glibc-2.1/libMesaVoodooGL.so.1.2.030100
\end{verbatim}
\end{filelist}

This directory contains the x86 binary for \gametitle{Heavy Gear II}, as well as precompiled OpenGL drivers for Matrox and 3Dfx graphics cards. Since Linux OpenGL support is changing rapidly, it's a good idea to include a working copy of the appropriate drivers with any packaged game, in case the next release of the drivers doesn't work correctly. (3D graphics support under Linux is expected to stabilize a bit in the near future as the DRI becomes the new standard, but now is a rough time for 3D graphics in Linux.)

Next is the \filename{setup.data/} directory, where Setup gets most of its information:

\begin{filelist}
\begin{verbatim}
./setup.data
./setup.data/bin
./setup.data/bin/alpha
./setup.data/bin/alpha/glibc-2.1
./setup.data/bin/alpha/glibc-2.1/setup.gtk
./setup.data/bin/alpha/setup
./setup.data/bin/ppc
./setup.data/bin/ppc/glibc-2.1
./setup.data/bin/ppc/glibc-2.1/setup.gtk
./setup.data/bin/ppc/setup
./setup.data/bin/sparc64
./setup.data/bin/sparc64/glibc-2.1
./setup.data/bin/sparc64/glibc-2.1/setup.gtk
./setup.data/bin/sparc64/setup
./setup.data/bin/x86
./setup.data/bin/x86/glibc-2.1
./setup.data/bin/x86/glibc-2.1/setup.gtk
./setup.data/bin/x86/setup
./setup.data/linkGL.sh
./setup.data/setup.glade
./setup.data/setup.xml
./setup.data/splash.xpm
\end{verbatim}
\end{filelist}

This directory tree contains Setup binaries for four different architectures, with both GTK- and terminal-based interfaces. The GTK binary requires GNU libc 2.1 or later, and so it's placed in its own directory. The \filename{setup.sh} script will run this binary only if glibc 2.1 is available. The plain terminal-based version is statically linked, and \filename{setup.sh} will run it regardless of the system's C library version. \filename{setup.glade} is a Glade GUI template for the Setup wizard, \filename{splash.xpm} is a version of the Heavy Gear II logo for the setup screen, and \filename{setup.xml} is the XML installation script.

The rest of the CD consists of \gametitle{Heavy Gear II}'s datafiles and cinematics. Setup just copies these files to the selected installation directory (probably \filename{usr/local/games/hg2/}), according to the \filename{setup.xml} script.

\index{Loki Setup!XML format}\filename{setup.xml} is pretty simple. XML may be overhyped, but this script is actually a good use of the language.\footnote{Don't worry, you don't need to know much about XML to use Setup. You can just copy an existing script and tweak it for your particular application. If you've ever written Web pages or documentation in HTML or SGML, XML's syntax should look quite familiar.} Here's the \gametitle{Heavy Gear II} installation script:

\begin{codesegment}
\begin{verbatim}
<?xml version="1.0" standalone="yes"?>
<install product="hg2" desc="Heavy Gear II" version="1.0"
         readme="README" postinstall="sh setup.data/linkGL.sh $*">
    <option install="true" help="Required for play"
            arch="x86" libc="glibc-2.1">
        Base Install
        <binary arch="any" libc="any" symlink="hg2"
                icon="icon.xpm" name="Heavy Gear II">
            hg2
        </binary>
        <files>
            data.tar.gz
            binaries.tar.gz
            icon.bmp
            icon.xpm
            README
        </files>
    </option>
    <option install="true">
        GL Drivers (STRONGLY recommended)
        <option>
            3dfx Voodoo Mesa 3.2 GL library
            <binary arch="any" libc="any">
                libMesaVoodooGL.so.1.2.030100
            </binary>
        </option>
        <option>
            3dfx Voodoo Mesa 3.3 GL library
            <binary arch="any" libc="any">
                libMesaVoodooGL.so.1.2.030300
            </binary>
        </option>
        <option>
            Matrox G200/G400 Mesa 3.2 GL library
            <binary arch="any" libc="any">
                libMesaMatroxGL.so.3.2.000121
            </binary>
        </option>
    </option>
    <option>
        Movies
        <files>
            shell/movies/asteroid.mpg
            shell/movies/flight.mpg
            shell/movies/gate.mpg
            shell/movies/intro.mpg
  
            (more MPEG movies)

            shell/movies/sc37.mpg
            shell/movies/sc3j.mpg
            shell/movies/title.mpg
        </files>
    </option>
</install>
\end{verbatim}
\end{codesegment}

% $

The root element of this XML file is labeled \code{install}, and it contains the options needed for the complete installation process. Flags to the \code{install} section include the name of the product, its version number, a brief description, the name of an information file (in this case \filename{README}), and a shell script to run after the files have been copied to the user's hard drive. You can optionally include a \code{preinstall} script (to be executed before copying files), a default installation \code{path} other than \filename{/usr/local/games}, \code{preuninstall} and \code{postuninstall} scripts for uninstalling the product (by default, Setup will just remove the directory tree it installed), and several other flags (documented in the Setup source package).

\code{install} usually contains several \code{option} elements. These elements specify sets of files that may be installed. If an \code{option} node contains the \cmdline{install="true"} attribute, Setup will install it by default. You can nest \code{option} sections to specify logical groups of files. If the user unchecks an option, Setup will block out any nested options. You can also specify libc or architecture requirements for options, making it easy to release a CD with support for several different architectures. Setup also provides support for internationalization.

After the user selects the appropriate sets of files and clicks the \menucommand{Begin Install} button, Setup performs the following tasks:

\begin{enumerate}
	\item Runs the \code{preinstall} script, if any (none in this case).
	\item Creates the installation directory, in this case \filename{usr/local/games/hg2/}. Obviously, the user must have write access to this part of the filesystem; Setup will refuse to continue otherwise.
	\item Copies the selected file sets from the CD-ROM to the installation directory.
	\item Writes an \filename{uninstall} script in the installation directory. This script simply removes all of the files that were copied and provides a quick way to uninstall the software. The script also executes any requested \code{preuninstall} or \code{postuninstall} scripts that were specified in \filename{setup.xml}.
	\item Runs the \code{postinstall} script, if any.
	\item Offers the user a chance to view the \filename{README} file, if one was given in \filename{setup.xml}.
	\item Offers to run the program immediately.
\end{enumerate}

\extfigure{figures/lokisetup-screenshot}{fig:lokisetup}{Loki Setup in action}

Although Setup was designed primarily for CD-ROM titles, you could easily make it work in other situations, as long as it can find the files it needs. You can get your own copy of Loki Setup at \website{Loki's Web site}{http://www.lokigames.com}. The Setup package includes source code as well as full documentation for the XML script format.

\index{Loki Setup|)}

\section{Understanding the Linux Filesystem Standard}
\index{filesystem hierarchy|see{Filesystem Hierarchy Standard}}
\index{Linux filesystem|see{Filesystem Hierarchy Standard}}
\index{Filesystem Hierarchy Standard|(}
Linux evolved from Linus Torvald's pet project into a full-blown multiuser operating system, and its filesystem has gone through a long period of evolution. A while back people decided that it wouldn't do for each Linux distribution to use a different filesystem, and so an effort was made to settle on a standard. Originally dubbed the \othertitle{Linux Filesystem Standard}, this document has grown into the \othertitle{Filesystem Hierarchy Standard} (FHS), and it is meant to apply to all UNIX-like operating systems. Most Linux distributions do a fairly decent job of adhering to the FHS, which makes life easier for application (and game) programmers who would like to support as many systems as possible.

We won't duplicate the FHS here; it's pretty long, and you can browse the whole thing at \ulink{http://www.pathname.org/fhs}. We'll simply offer a brief overview of the filesystem and then give a few hints about where your game should put its files. Following these hints will keep your users happy and hopefully reduce the possibility of your game damaging someone's filesystem. We'll start with an overview of the top-level directories on a typical Linux box.\footnote{Much of this information is directly from the \othertitle{Filesystem Hierarchy Standard}, version 2.1.}

\begin{bodylist}
	\item [\filename{/}] The top-level directory. Don't put anything here.\footnote{The FHS forbids compliant distributions from adding new top-level directories, but some do anyway.}
	\item [\filename{bin/}] Important binaries that the system needs to boot. Don't touch this directory unless you have a really good reason (which is unlikely if your product is a game).
	\item [\filename{boot/}] The Linux kernel and various bootloader information.
	\item [\filename{dev/}] Device files, such as \filename{dsp}. You may need to access some of these, but it's unlikely that you'll need to modify them.
	\item [\filename{etc/}] Systemwide configuration files. Game configuration files almost certainly do not belong here.
	\item [\filename{home/}] Home directories for each user. For instance, my home directory is \filename{home/overcode/}. Programs and scripts can retrieve the current user's home directory with the \code{HOME} environment variable. \filename{home/} is sometimes actually stored in \filename{usr/home/} and linked to \filename{home/}.
	\item [\filename{lib/}] System libraries and kernel modules. Don't put anything here unless your application requires special kernel modules (which is very unlikely and potentially very dangerous).
	\item [\filename{mnt/}] A temporary filesystem mount point. For instance, floppies and CD-ROMs are frequently mounted here.
	\item [\filename{opt/}] A somewhat controversial (but standardized) place for applications to add their own directory trees. Very similar to \filename{/usr/local}, and roughly equivalent to the \filename{Program Files} folder in Windows.
	\item [\filename{proc/}] Dynamically generated system information. Look, but don't touch.
	\item [\filename{root/}] The root user's little cave. Unless this happens to be the current \code{HOME}, don't mess with it (it'll probably be read/write protected anyway).
	\item [\filename{sbin/}] System administration binaries. I don't see why a game would ever need to touch this directory, except perhaps to collect information about the system.
	\item [\filename{tmp/}] A scratch pad directory. You can put anything here, but it's polite to clean up after yourself. Don't count on anything remaining in \filename{tmp/} for too long. Some systems purge \filename{tmp/} weekly.
	\item [\filename{usr/}] Billed by the FHS as the ``secondary hierarchy,'' \filename{usr/} contains a second directory structure very similar to the root directory but with a different purpose. We'll look at some of \filename{usr/}'s subdirectories shortly.
	\item [\filename{var/}] Variable data, according to the FHS. \filename{var/} is home to logs, email, state information, and temporary files that are too important for \filename{tmp/}. (Files in \filename{var/tmp/} are guaranteed to be preserved between system reboots.)
\end{bodylist}

\filename{usr/} is typically the largest top-level directory on the system. It houses almost all of the system's datafiles, application binaries (those that aren't in \filename{opt/}, at least), and some local configuration files. Here's a typical \filename{usr/} structure:

\begin{bodylist}
	\item [\filename{usr/X11R6/}] The X Window System. It would more correctly be elsewhere, but this location is well established, and the FHS makes an exception for it.
	\item [\filename{usr/bin/}] User binaries. In some cases it's acceptable for your installation program to put binaries or symlinks here; see below.
	\item [\filename{usr/games/}] Games. If your game is small (one or two files), you might want to have it install itself here. If you're not using a package manager, though, \filename{usr/local/games/} is probably a better idea.
	\item [\filename{usr/include/}] Directory of \filename{.h} files for the C compiler. If your game needs to install a development library of some sort (perhaps as part of a source build), its header files should go here so the C compiler can find them. It's polite to put them in a subdirectory of \filename{usr/include/}, though. SDL puts its headers in \filename{usr/include/SDL} or \filename{usr/local/include/}.
	\item [\filename{usr/lib/}] Noncritical libraries. The system should be able to run without the libraries stored in \filename{usr/lib/}. Packages such as SDL and GTK usually put their shared libraries here (or in \filename{usr/local/lib/}). The distinction between critical (\filename{lib/}) and noncritical (\filename{usr/lib/}) libraries is very important for maintaining a Linux system.
	\item [\filename{usr/local/}] Similar in function to \filename{opt/}. This directory is not supposed to be under the control of any package manager. (RPM packages usually install to \filename{usr/} rather than \filename{usr/local/}.) If you intend to use Loki's Setup program for your installation, you'll probably want to install to \filename{usr/local/}. It's not uncommon for applications to create their own subdirectories under \filename{usr/local/} (whereas creating a subdirectory under \filename{usr/} is very bad style). \filename{usr/local/} contains \filename{include/} and \filename{lib/} subdirectories that are more or less equivalent to \filename{usr/include/} and \filename{usr/lib/}, respectively. The FHS specifies that \filename{usr/local/} should be left empty by the distribution's installer and should not be touched during system upgrades.
	\item [\filename{usr/sbin/}] Additional system administration binaries. Although this directory contains the same sort of programs as \filename{sbin/} (that is, programs primarily intended for use by root), it shouldn't contain anything that's absolutely critical to the system. For instance, network traffic monitors and improved versions of basic networking utilities might go in \filename{usr/sbin/}, while the basic system administration programs common to all Linux systems should go in \filename{sbin/}.
	\item [\filename{usr/share/}] Architecture-independent data, according to the FHS. This directory usually contains assorted program datafiles. For instance, Emacs' Lisp scripts reside in \filename{usr/share/emacs/}. It's not unreasonable to put your own datafiles here (in a separate subdirectory).
\end{bodylist}

Where should your game install itself? If you're installing with a package manager that has the ability to remove and verify the files it installs, it's acceptable to use \filename{usr/} directly (including \filename{usr/bin/}, \filename{usr/games/}, \filename{usr/lib/}, and \filename{usr/share/}). If your game were \gametitle{FooBall}, for instance, it might install its executable to \filename{usr/games/fooball} and its datafiles to \filename{usr/share/fooball/}. However, if your game uses its own installation system rather than a package manager, it's best to use \filename{usr/local/games/fooball} and \filename{usr/local/share/fooball/}. It would also be OK to install to \filename{opt/fooball/}. The basic rule is that you shouldn't touch \filename{usr/} without involvement from a package manager; instead, you should use \filename{usr/local/} and \filename{opt/}.

These places are fine for executables and datafiles, but what about configuration information? Most users don't have write permission to anything in \filename{usr/} (and certainly not to \filename{etc/}), and it's a very bad idea to require your program to be run under the root account (mainly for security reasons). Per-user configuration files (high scores, window/video mode info, saved games, and so on) can go in each user's home directory, which you can grab from the \code{HOME} environment variable (in C, \code{getenv("HOME")} should do the trick). All of Loki's games, for instance, use \filename{\$HOME/.loki/} for this purpose. Systemwide configuration files, if any, can go in \filename{usr/local/etc}. But you'll probably want to leave most options up to the individual user.
\index{Filesystem Hierarchy Standard|)}

This concludes our discussion of installing software under Linux. In the next chapter we'll talk about... Wait, there are no more chapters!

We've thoroughly scratched the surface of game programming with Linux. There's a lot we haven't covered, but hopefully you've now seen enough that you can pick up the rest on your own. Whether or not Linux will become a major gaming platform is anyone's guess, but if we want that to happen, it is our responsibility to lead the charge. Happy game hacking.
