INSTALL.txt for "Tux, Of Math Command" (aka "Tuxmath")
Version 1.5.7

October 29, 2007


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:

      Linux
      Windows 32-bit
      MacOSX

    In principle, Tuxmath should build and run on any platform with SDL,
    including: 
      Solaris
      IRIX
      FreeBSD
      BeOS
    However, I do not know if anyone has done a current build on these systems.

  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.

    Gnu gettext is required to run "make install".

    As of version 1.5, TuxMath uses SDL_ttf to display true type fonts.
    The freely distributable Andika font is included under data/fonts.

    Note: libSDL, SDL_image, SDL_ttf 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," "SDL_ttf", 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/
        SDL_ttf:  http://www.libsdl.org/projects/SDL_ttf/

      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
    ---------------------
      You can build Tuxmath either with the latest subversion checkout or 
      using a convenient source tar.gz distribution package. The svn
      repository is located at:

        http://svn.debian.org/wsvn/tux4kids/tuxmath 

        or:

        svn://svn.debian.org/tux4kids/tuxmath

      If you are using a source tar.gz package (e.g. tuxmath-1.5.5-tar.gz),
      all you need to do is unpack the archive in a convient location and
      do a typical configure, make, and install.  In other words, the
      tarball contains a complete "GNU Build System".  Note, however, that
      you will need the "-dev" files for SDL, SDL_image, SDL_mixer, and
      SDL_ttf.  You also need Gnu gettext as "msgfmt" is called during the
      installation.
 
      For example:
 
        tar -xzf tuxmath-1.5.5-tar.gz
        cd tuxmath-1.5.5
        ./configure
        make
        make install.  (you might need "su" or "sudo" for this)
 
      If you use a subversion checkout, you will need to generate the configure script.
      Tuxmath uses the Gnu Autoconf/Automake tools for development. You will need
      to run Autoconf's "autoreconf" to generate the configure script, Makefile.in's,
      and friends, so the build process becomes:
      
        autoreconf --install; ./configure; make; make install

      Tuxmath supports "parallel" or "vpath" builds to avoid cluttering the source
      tree with object files, so a clean way would be (starting within trunk):

        mkdir build
        cd build
        autoreconf --install ../trunk
        ../trunk/configure
        make
        make install

      (which is what I do).

      By default, the build process will install tuxmath under /usr/local/share
      for the data and /usr/local/bin for the executable, which is simply
      called "tuxmath".

      If you are using a deb or rpm-based distribution, your distro may have
      tuxmath in a prepared package, in which case your job is as simple as
      "apt-get install tuxmath".

  Windows 
  -------
      Tuxmath can be cross-compiled for Windows under Linux.  I have done this on
      my Debian system. Once the crossbuild environment is set up, the process is
      simple and nearly automatic.
 
      To set up a crossbuild environment:
 
      1. Install mingw32 (apt-get install mingw32) and makensis (apt-get install nsis)

      2. Create directory structure:
        - mkdir /usr/local/cross-tools
        - mkdir /usr/local/cross-tools/i586-mingw32msvc
        - mkdir /usr/local/cross-tools/i586-mingw32msvc/lib
        - mkdir /usr/local/cross-tools/i586-mingw32msvc/include

      3. Install precompiled win32dev files (lib and includes) for SDL, SDL-image
         and SDL-mixer in the lib and include directories you just created.
         You can get all of these from www.libsdl.org. I had some trouble with
         this step as the SDL libs have varieties intended for both mingw32 and MSVC -
         I was able to build successfully using the mingw32 ones. I also had to put
         all the lib files directly under /usr/local/cross-tools/i586-mingw32msvc/lib
         to get it to work.  My /usr/local/cross-tools/i586-mingw32msvc/lib contains:

         dbruce@debian:/usr/local/cross-tools/i586-mingw32msvc/lib$ ls
         jpeg.dll      libSDL.la     SDL_image.dll  SDL_ttf.dll     zlib1.dll
         libgw32c.a    libSDLmain.a  SDL_image.lib  smpeg.dll
         libpng12.dll  libtiff.dll   SDL_mixer.dll  vorbis.dll
         libSDL.dll.a  ogg.dll       SDL_mixer.lib  vorbisfile.dll


         The header files can be in their own folders as long as they are under
         /usr/local/cross-tools/i586-mingw32msvc/include

      4. Install libgw32c (the dev file):
         http://gnuwin32.sourceforge.net/packages/libgw32c.htm in the same directory.
         This gives you the file "libgw32c.a" that you need to have in the lib directory.

      5. You need to have a directory containing all of the dlls that will need to be
         packaged into the installer.  The Makefile expects them to be in NSI_DLL_DIR,
         which I have set to  ~/tuxmath_dll. On my machine, this contains:

         dbruce@debian:~/tuxmath_dll$ ls
        jpeg.dll      ogg.dll        SDL_mixer.dll  vorbis.dll
        libpng12.dll  SDL.dll        SDL_ttf.dll    vorbisfile.dll
        libtiff.dll   SDL_image.dll  smpeg.dll      zlib1.dll


        (Note - this has mostly the same files as the cross-tools lib directory - it is most
        likely possible to eliminate this redundancy in some way.).

      6. If you have done a native (Linux) build in the same source tree, run "make clean"
         and "make distclean" to get rid of the autogenerated files.

      7. From the trunk dir, run:
         autoreconf --install
         ./cross-configure.sh --with-sdl-prefix
         ./cross-make.sh
         ./cross-make.sh nsis

      This should create the windows installer file ("tuxmath-1.5-win32-installer.exe")
      under trunk.

      Installation on Windows:
      ------------------------
      To install, simply execute the installer file on the Windows machine. Depending on
      the version of Windows and the computer's security settings, it may be necessary
      to install with administrator privileges in order to use the default installation
      location (C:\Program Files\Tuxmath). If you are not able to write to the default
      location, TuxMath can be installed in any writable location (i.e. "My Documents")
      and should function correctly.  It can be run with ordinary user privileges,
      even if installed by the administrator.


  Mac OSX: (contributed by Tim Holy)
  -------
      Building from source:
      --------------------
      You have to have the development tools and development libraries for SDL.  Here's the approach that worked for me:
	  1. Download and install XCode from the Apple web site.
	  2. Check out the code from the subversion repository at alioth.
	     You may have to download and install Fink
             (http://fink.sourceforge.net/). You may then have to do
	           fink install svn-client-ssl
             if the pre-built binary for the svn-client doesn't
             support SSL.
	  3. Download & install the SDL (www.libsdl.org) Frameworks for
             MacOSX. You'll need SDL, SDL_image, SDL_mixer, and SDL_ttf.
	  4. Open the Xcode project (in tuxmath's macosx/ directory)
             and hit "build." Cross your fingers. The most likely
             issue you'll encounter is that, as tuxmath progresses,
             new source code files get added to (or old ones deleted from)
             the src/ directory.  So, you might have to add or remove
             files from the project.
	  5. To build a disk image, open a terminal and navigate to
             the macosx/ directory. Type "make macapp". After a short
             while, the TuxMath.dmg disk image will appear in the
	     build/Release directory. You can surely also do this
	     using GUI tools.

     The main issues in getting the Mac build to work come from the
     fact that it is not using the automake system. So, certain macros
     have to be defined by Xcode (under Project->Edit Project
     Settings, then choose the Build tab, in the collection
     Preprocessing).
     Currently, the macro definitions are these:
     MACOSX=1 DATA_PREFIX=\"TuxMath.app/Contents/Resources/data\"
     VERSION=\"1.5\" $(inherited)

     In particular, VERSION could be updated with each release (you
     also should edit InfoPlist.strings if you want the Finder's
     notion of the version # to be updated).

     Currently, internationalization is disabled on MacOSX.
     Anyone who knows how to get the Linux internationalization
     framework working on MacOSX is invited to contribute.
