INSTALL.txt for "tuxmath"

September 6, 2001


[ NOTE: When (and if) TuxMath changes from a simple Makefile system to
  an autoconf/automake system, parts of this document will need to change! ]


Requirements
------------
  Operating System
  ----------------
    "Tux, of Math Command" ("TuxMath" for short) requires a computer and
    operating system supported by libSDL.  At the time this document was
    written, this included:

      Windows 32-bit
      MacOS
      Linux
      Solaris
      IRIX
      FreeBSD
      BeOS


  CPU
  ---
    [ Minimum requirements should be P90, but not sure yet... ]
    [ Architectures including i386, Alpha, PPC, Sparc64, 68000<?> ]


  Video Display
  -------------
    TuxMath displays the game screen in a 640x480 window.

    If supported by your system, the game can also display in full-screen
    mode (see "README.txt" or the program's "--usage" display).

    When attempting to run in fullscreen mode on systems where true 640x480
    resolution isn't available for some reason, the next-lowest resolution
    available will be used, and the game area will be centered within a
    black screen.

    TuxMath prefers 16bpp (bits per pixel) color depth, but can run in
    8bpp (256 colors) if that's all that is available.


  Sound Card
  ----------
    TuxMath attempts to play stereo 16-bit sound and music at
    44.1Khz, if possible.

    Sound, however, is optional, and can be disabled at compile-time
    (see below) or run-time (see "README.txt" or the program's "--usage"
    display).


  Input Methods
  -------------
    The game is typically played using a keyboard.  The numeric keypad
    portion of standard PC keyboards is supported (so if there are any
    stand-alone numeric keyboards with no other keys, they SHOULD work, too).

    Menus and options can be controlled with either the pointer or the
    keyboard's arrow keys.

    The game can also be played with a large, on-screen numeric keypad
    which can be accessed using the pointer (ie, a mouse, trackball,
    touch-screen monitor, touchpad, etc.).  (See "README.txt" or the
    game's "--usage" display).


  Required Libraries
  ------------------
    "Tux, of Math Command" uses the Simple DirectMedia Layer library (libSDL)
    to display graphics, receive keyboard and mouse input, and play sounds.
    (It was designed around libSDL version 1.2, but later versions should
    work.)

    It uses the SDL helper library "SDL_image" to load the game's graphics
    data, as they are in PNG (Portable Network Graphic) format.

    Also, by default, it uses "SDL_mixer" to load and play the game's
    sound and music.  This library is optional, but without it, the program
    will be completely silent.

    Note: libSDL, SDL_image and SDL_mixer are all free, Open Source libraries,
    released under the GNU Library General Public License (LGPL).

    Getting SDL
    -----------
      You can download "libSDL," "SDL_image," and "SDL_mixer" from the
      SDL website:

      http://www.libsdl.org/


      Specifically, the download pages for each are here:

        libSDL:     http://www.libsdl.org/download-1.2.html
        SDL_image:  http://www.libsdl.org/projects/SDL_image/
        SDL_mixer:  http://www.libsdl.org/projects/SDL_mixer/

      Using SDL Packages
      ------------------
        When building "TuxMath" from source, if you decide to install the
        SDL libraries using packages (RedHat RPMs or DEBs), you'll
        need to install not only each library's 'binary' package, but ALSO
        each library's 'development' package.

        These contain the text "-devel" in the package name.

        Also note: Make sure you download the packages for the appropriate
        operating system and architecture (eg, an RPM for Linux/i386 for
        RedHat Linux on Intel-compatible computers).



Compiling and Installing TuxMath
--------------------------------
  Linux/Unix
  ----------
    Compiling the Program
    ---------------------
      To compile the "tuxmath" binary, simply issue the following command:

        make

      This will compile the source files and, unless any errors occur,
      create a "tuxmath" executable program in the TuxMath directory.


      If you wish to build the program without sound support (in this
      case, the "SDL_mixer" does NOT need to be installed), run this
      command instead:

        make nosound


      NOTE: See below to change the installation directory for TuxMath.


    Installing
    ----------
      Once compiled, you can have the program and graphics/sound data
      files copied to a shared location on your system.

      First, change to the superuser (root), by running the "su"
      command and entering root's password.  Then, run this command:

        make install

      By default, the program will be copied into "/usr/local/bin/"
      and the data will be copied into a new directory,
      "/usr/share/tuxmath/".


    Changing Installation Directory
    -------------------------------
      If you wish to override the default installation directories
      for TuxMath, you can specify them when you run "make"
      (or "make nosound").  Do this BEFORE running "make install".

        make DATA_PREFIX=/path/to/put/data/ BIN_PREFIX=/path/for/executable/


      For example, if you do not have superuser access on the computer
      you're installing in, and wish to simply run TuxMath from within
      your home directory, you can run:

        make DATA_PREFIX=/home/usernmame/tuxmath-data/   \
             BIN_PREFIX=/home/username/bin/

      And when you go to install, run "make install" with the same:

        make install DATA_PREFIX=/home/usernmame/tuxmath-data/   \
                     BIN_PREFIX=/home/username/bin/

      The data files will be copied into "tuxmath-data" in your home
      directory, and the program will be copied into the "bin" directory.


    Cleaning Up
    -----------
      If you need to re-make from scratch for some reason (for example,
      you wish to change the "DATA_PREFIX" value when you run "make"),
      you can have all of the compiled files (the program, and all of the
      object files in the "obj/" directory) deleted by running:

        make clean


[ UNDER CONSTRUCTION ]
