[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Article] Linux Games Install and Directory Guide (update)

I have updated my  Installation and Directory Guide (anyone know a
better name?). The sgml source along with *.dvi, *.tex, *.html files
is available at: 

I have not checked the spelling yet, so be warned ;-)
Critic and corrections are *very* welcom! I have *no* real experience
with some parts of this article (like CDRom installation, install
scripts, etc.), so if someone ever tried something like that, please
comment. I need also some infos on what infos I should add.

I have attached the txt version below:
-------------------------------- snip ---------------------------------
  Linux Games Install And Directory Guide
  Ingo Ruhnke, grumbel@gmx.de

  v0.2, Begin: Tue Aug 17 23:11:43 1999, LastUpdate: Sun Aug
  22 15:23:43 1999

  This document gives an overview how to install games under Linux and
  how to put the files in the correct directories according to the FHS.


  Table of Contents

  1. What is different between DOS/Windows and Linux?

  2. The directories and how to handle them

     2.1 The different between
     2.2 Which files are needed by a game?
     2.3 Where to put the files?
        2.3.1 Binaries
        2.3.2 Static Datafiles
        2.3.3 Shared libarys
        2.3.4 Save games
        2.3.5 Hiscores
        2.3.6 Config files
     2.4 How to find the files and how to make the game relocatable?
     2.5 How to allow extra levels or similar stuff?
     2.6 How to handle data from a cd-rom?

  3. How to install the game?

     3.1 How to install the source?
     3.2 How create packages?
     3.3 How to handle CD-Rom installation?
     3.4 How to create update or patch distribution?
        3.4.1 Using diff/patch
        3.4.2 Using hand build update scripts
        3.4.3 Patchig a RPM

  4. Some tips about of to make that with automake/autoconf?

     4.1 Tweaking the path
     4.2 How to find out where the package is installed?



  What is different between DOS/Windows and Linux?

  DOS and Windows use a very simple way of handling the directories. If
  you install a programm all data goes to a single directory. The
  programm don't has to worry about were to place the files, it can
  handle that as it likes to do.

  Under Linux the thing looks a bit different, the complete file system
  is only one big tree, there is no seperation into different drives and
  the data of a programm is mostly spread over this filesystem tree.
  There is a standard document, the Filesystem Hierarchy Standard, which
  descripes where the files belong, most games which I know do not
  follow this standard or following only some of its rules. For standard
  software documentation goes to /usr/doc/, binaries go to /usr/bin/,
  data files goes to /usr/share and so on. So the installation is a bit
  difficult, since the data should go to it correct directory. This as
  different reasons, one of them is for example that you should be able
  to mount the share/ directory remout over a network, since it should
  only contain system indepented files, while bin/ for example contains
  system depended binaries which can be shared over different machine
  types. For games there are some special directories reserved, they
  differ a bit from the standard directories, but not much. A lot of
  games at the moment don't use that directories, this document should
  give a introduction on how to handle all that directories and how to
  avoid throuble.


  The directories and how to handle them

  2.1.  /usr/local .

  The different between /usr/  and

  Before I start with some more detailed description, there is one thing
  you should know. There is a directory /usr and there is a directory
  /usr/local, they contain both the same subdirectories, but the
  different is that all stuff under /usr is handled by the distributions
  pakage system, while all stuff under /usr/local is maintained by the
  system administrator. So if you are providing a game as source or as a
  precompiled tarball it has to go to /usr/local, if you provide instead
  or in addition RPM or debian packages they should install themself
  into /usr. In the following text I will refer only to /usr, because
  things under /usr/local are the same just in another start diretory.


  Which files are needed by a game?

  So before we a going to install a game we first have to thing which
  files we have in a game and what types of files are they. Most games
  will have some or most of the following file types:

    binarys (or executables)




    packed datafiles


    shared libaries

    script files

    save games

    hiscore files

    config files



  Where to put the files?



  This is the easiest thing to do correct. Normal programms are placed
  under /usr/bin, while games get their own directory under /usr/games/.
  So all your user visible binaries should go into that directory, this
  will be mostly just a single executable binary.


  Static Datafiles

  A lot of games at the moment put there data files in a place like
  /usr/lib/$GAME, but games will now get there own directory so placing
  them into /usr/lib/ wouldn't be the correct way. The new place for
  static game data is /usr/share/games/$GAME. All static and
  architecture independent goes to that directory, like images, music
  files or packed datafiles. It is not required to seperate the diretory
  any further, but I recommon it, since it will ensure that you will not
  end up in chaos, if the project groves.


  Shared libarys

  Some games use shared libarys which are linked at run time, this
  allows the game much more flexibility, because levels and enemys can
  be created in C or whatever language they might choose, so there is no
  need for scripting languages or other stuff to make the game more
  flexible. You might guess that libaries should also placed under
  /usr/share/, but that is not correct. Since /usr/share/ is only for
  architecture independent files and shared librarys are not
  architecture independent, they depend on a specific type of machine
  architecture. So they should be placed under /usr/lib/games/$GAME/.


  Save games

  A lot of games offer the posibility to save the game status and
  restore the state where you left the game. This data is variable and
  should therefore not saved under /usr/*. So were to put the savegames?
  Because savegames are personal data, there are best placed into the
  users home directory. The savegames should be placed in an extra
  directory for each game, like $HOME/.$GAME/.  This will ensure that
  the directory is normaly hidden and won't annoy the user. If there is
  more variable user specific data (like demo files, etc.) it should
  also be placed in that directory. Then the directory should be
  seperated into some subdirs like save/ and demo/.



  Hiscores are similar to save games, but they are not eqal. The
  different is that save games or mostly interesting for personal use,
  while hiscores are interessting for other. On a multiuser system it
  would be interesting to fight against other peoples hiscores. So
  hiscore files and other dynamic data which is not meant for personal
  use only shoud be placed under /var/games/. If the game needs more
  then one file to hold the data it should get its own subdirectory,
  like /var/games/$GAME


  Config files

  As for all other programms, there are two places for config files, one
  is /etc/ and the other is the users home directory. I'd recomment to
  use an extra directory for games under /etc/, but the FHS does not
  require this, but it will prevent chaos in the future. So /etc/games/
  should be the places where the global config files where placed. Local
  user config files should be placed under $HOME/.$GAME/, just like save


  How to find the files and how to make the game relocatable?

  Now you know where to put all files, but how to find them after
  installaton? If the game is compiled from source it is easy, the
  install prefix, which should be /usr/local by default, should be
  compiled into the binary. How to do this using autoconf/automake is
  discribed below, if you are using a non standard way, you have to do
  that yourself or switch to autoconf/automake, which is really
  recommend. Then the game will allways know where it was installed. The
  problems come when you are trying to install a binary. If the game is
  packed in a debian or RPM package, then the package maintainer should
  have set the prefix right so that the game will run fine after
  installaton. But what if the user wants to install the game somewhere
  else, for example under /opt? Then the game should be relocatable. But
  what does relocatable mean? Its means that you can install a programm
  where ever you want it to be, you are not forced to use the standard
  directories.  In a binary the path is hard coded into the binary, so
  what to do? There should be allways a way to override the default path
  in a game. A good possibility to do that is to set the prefix
  directory throu a configuration file, an enviroment variable
  (GAME_DATADIR or GAME_PREFIX) or an command line option.


  How to allow extra levels or similar stuff?

  The problem that arrived with extra levels and similar stuff is that
  not all users have root access to there macines, so it is not possible
  to place the files under /usr or it would be more comfortable to have
  them in the home directory, when you are developing a level. Therefore
  the game should offer the possibility to read the files from
  $HOME/.$GAME/. The subdirectory structure in that directory should be
  equal to that in /usr/share/games/$GAME, so it will be possible to
  extract the extra level in /usr or in $HOME, without tweaking the

  At the moment I am not having much experience with shared libaries, so
  I can not say if it will cause throuble to placing them under
  $HOME/.$GAME/. I think the LD_LIBRARY_PATH has to be adjusted, but I
  am not sure.


  How to handle data from a cd-rom?

  This section is only theoretical, I never tested anything from below,
  so be warned!

  Under DOS and Windows handling the cdrom wasn't very difficult the
  game only needs to now the drive letter. Under Linux the situation is
  not much different, but instead of a drive letter we have a device
  name where the cd-rom is and a directory name where the cd-rom is
  mounted. The standard places are on the most machines /dev/cdrom,
  which is a link to the correct device (you normaly will newer want to
  touch this directly) and the directory /cdrom. But the correct
  location should be always be detected at installation time.
  Overwriding the defaults should allways be possible using a command-
  line option or a config file.

  Some games allow it to install only some files to the harddrive and
  let all other data resist on the cd or to install all data to the
  harddisk which could improve the speed a bit. This shouldn't be to
  hard to include into a game, it only has to keep track of were it
  installed it files and then load them were there were installed. I
  recomment it to have a similar directory structure on the cdrom as on
  the harddisk, since that makes thing easier, so the programm can acces
  its data with:

              f = fopen(make_full_path("levels/level1.dat"), "rb");

  Where make_full_path() is a function translating the relative path
  (here: levels/level1.dat) into a full path, which could be
  /cdrom/levels/level1.dat or /usr/share/games/GAME/levels/level1.dat,
  depending on which data was installed. Another possiblity would be to
  use symlink. The install scripts would create symlinks for all files
  which aren't installed and let this symlinks point to the cdrom
  directory, that would be possible, but cause some throuble when the
  cdrom is mounted to another directory or the computer as multible
  cdrom drives.


  How to install the game?

  Now as we made clear where all the files should go. The question is
  how to install the game? The game can come into source or binary form,
  can use just a few MB's or thousand of them. If the game is small it
  is the best to just use the standard ways of installing software under
  linux, which are tar.gz files containing the source, or for binary
  distributions use packages files like RPM or debian packages, you can
  also use tar.gz binary distribution, but then they would not check if
  the correct libs are installed, that causes lots of throuble for
  example with mixed libc5, glibc2.0 and glibc2.1 installation. So if
  you are not having much time its better to not start creating tar.gz
  binaries and instead make the source as easy compileable as possible.


  How to install the source?

  The source package should allway be a tar.gz file which installes in a
  single directory tree and is after unpacking installable with a:

              $ ./configure
              $ make
              $ make install

  This way of installation is the standard way for most software and is
  very common for the most users, so it will cause the lessest throuble.
  This way can be easily obtained with autoconf and automake. If you are
  using a non standard way of doing installations, you should change it
  to the lock and feel of the above or even better switch over to
  automake and autoconf, since it will give you all that and also stuff
  like automatic distribution packaging and libary checking, etc.


  How create packages?

  The task of package creation is more or less complex. You can probably
  get some simple packages to work for your distribution, but
  maintaining different packages for different distribution, which you
  don't have, is probably a bit hard, since you can't test them easily,
  so it is a very good idea to find somebody who will packaging the
  stuff for you and test it, this will save you a lot of work and ensure
  that the package will work.


  How to handle CD-Rom installation?

  If your game is very big, so that it is distributed on CD, there could
  be some throuble. Packages of your program will be impossible, since
  you would have to distribute three or more different packages (.rpm,
  .deb, tar.gz), that will probably blowup the CD space. So the easiest
  solution is to just distribute a tar.gz file with a installation
  script and documentation on how to do the installation manually. The
  install script should ask what the user wants to install and where to
  install it, it should also create a config file, so that the game find
  its datafiles after installation without user interactions. The script
  should probably perform the following task:

    Ask what to install (videos, level data, etc.)

    Ask where to install (/opt, /usr, /usr/local, etc.)

    Install the data

    Make sure that the game will find its data (create a config script
     or tell the user which enviroment varibales he has to set)


  How to create update or patch distribution?

  If you release a new version of your package it is a good idea to also
  make a patch or update available, so that the user is not forced to
  download the complete game again.


  Using diff/patch

  If you changed only the source, you can create a patch file, with
  diff. The patch file can be applied using patch. For more informations
  see info patch and info diff. The problem is that diff/patch can't
  handle binary files, so it is impossible to use them with datafiles.


  Using hand build update scripts

  If you changed the directory layout or added some new files you will
  have to use a hand build update script. I have never done that, so I
  can't give you an advice.


  Patchig a RPM

  If you distributed your game as RPM you might ask, but how to patch
  that? A way to do that was mentioned by Pierre Phaneuf
  <pp@ludusdesign.com>. You can create an update scipt and a which a
  Source RPM, the script will than catch all the installed datafiles
  from theire directories, build a new RPM from the SourceRPM using the
  datafiles, then install the new RPM.


  Some tips about of to make that with automake/autoconf?


  Tweaking the path

  The problem with automake, which I really recomment to use, is that it
  installed the files at default in the normal places, thats perfectly
  ok, but since games are a bit different there is the need to tweak the
  pathnames a bit. That can be done by placing the following in the

              # Tweaking the `datadir' to install the files in the correct location
              pkgdatadir = $(datadir)/games/@PACKAGE@


  How to find out where the package is installed?

  If you are using automake/autoconf the user has the choice to override
  the default prefix, which is /usr/local. So the question is how to I
  get the install directory? Therefore we have to hardcode the path into
  the binary, but how to accompilsh that? The problem is that we need to
  expand the variable $prefix to the full pathname, else we would end up
  with a useless string like "$prefix/". Place the following in the file

              AC_DEFUN(MY_EXPAND_DIR, [
                     test "x$prefix" = xNONE && prefix="$ac_default_prefix"
                     test "x$exec_prefix" = xNONE && exec_prefix="${prefix}"
                     eval echo \""[$]$1"\"

  And the following into configure.in:

              MY_EXPAND_DIR(game_datadir, "$datadir/games/$PACKAGE")
              AC_DEFINE_UNQUOTED( GAME_DATADIR, "$game_datadir")

  This will create a macro called GAME_DATADIR, which will expand into
  the path where your game data resist (i.e. /usr/share/games/pingus).
  For example if the game is installed into /usr/local GAME_DATADIR will
  expand to /usr/local/share/GAME/, when you need other data then the
  one that resist in share/$GAME you can also use "${prefix}" in the

-------------------------------- snip ---------------------------------

                                  http://dark.x.dtu.dk/~grumbel/pingus/ | 
Ingo Ruhnke <grumbel@gmx.de>             http://home.pages.de/~grumbel/ |