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

December 19, 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
      FreeBSD
      BeOS

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

  CPU
  ---
    Any machine from the last decade should easily handle TuxMath - when first
    written, the minimum suggested CPU was a 90 MHz Pentium.


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

    If a 640x480 resolution is 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 32bpp (bits per pixel) color depth.  Current
    builds have not been tested on systems that cannot provide this
    (AFAIK), but I believe SDL will make do with lower color depth if
    necessary.


  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.

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

    As of v1.5.8 (Linux), v1.6.0 (Windows), and v1.6.1(MacOSX),
    internationalization is supported using Gnu gettext and libiconv.

    As of v1.6.3 (Linux), TuxMath can support translations into
    languages requiring bidirectional text by using
    SDL_Pango. SDL_Pango is optional in the build process.

    The executable Windows installer contains all needed libraries
    (DLLs) and the Andika font - nothing else should be needed that is
    not part of Windows.  The *tar.gz source packages require the
    "*-dev" versions of SDL, SDL_image, SDL_mixer, SDL_ttf for
    building and installation (easily obtained in most any Gnu/Linux
    distribution).  The Andika font is also included.

    Note: libSDL, SDL_image, SDL_ttf, SDL_mixer, SDL_Pango, and
    libiconv 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/
	SDL_Pango: http://sourceforge.net/projects/sdlpango/


      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
--------------------------------

Note: there are now two ways to build tuxmath from source.  The first
(and main method) is using autotools ("./configure && make && make
install").  The second is to use CMake.  CMake is being explored as a
possible way to better-support MacOSX.  However, the CMake build is
currently having some troubles with the internationalization code, and
requires a cheat (running configure, copying a file, and then running
CMake).  Further details are below.


  Linux/Unix
  ----------
    Getting Tuxmath
    ---------------
      You can build Tuxmath either with the latest subversion checkout or 
      using a convenient source tar.gz distribution package. The current
      website is:

        http://www.tux4kids.com

      where you generally can find the latest tuxmath*tar.gz package.

      The svn repository is located at:

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

      or:

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

    Compiling the Program: Automake (Linux)
    --------------------------------------
      If you are using a source tar.gz package (e.g.,
      tuxmath_w_fonts-1.6.1-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. Your
      system is virtually certain to already contain the other
      standard libs used at compile or run time.
 
      For example:
 
        tar -xzf tuxmath_w_fonts-1.6.1-tar.gz
        cd tuxmath_w_fonts-1.6.1
        ./configure --enable-sdlpango
        make
        make install.  (you might need "su" or "sudo" for this)
 
      (The "enable-sdlpango" switch is needed if you want to compile
      Tuxmath with support for Pango for right-to-left languages.)

      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 Autoconf 2.61 or later, Automake 1.10
      or later, and Gnu Gettext 0.16 or later, in addition to the libs
      needed for the build itself. Run Autoconf's "autoreconf" to
      generate the configurescript, 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".

  Compiling the Program: CMake (Linux & Mac OSX)
  ----------------------------------------------
    The recommended procedure is to build out-of-source (equivalent to
    the "parallel" or "vpath" build for automake described above).

    From a directory above "trunk," do the following:
       mkdir build-cmake
       cd build-cmake
       cmake ../trunk
       make
       make install

    By default, the CMake build includes support for SDL_Pango, if the
    library & its header can be found.

    On Mac OSX, this builds a static "intl" library (for
    internationalization support) and creates a .dmg file.


  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.

      In order to get a successful crossbuild using gettext, it was
      necessary to set up a "pure" mingw environment, in particular
      avoiding the use of libgw32c.  I also stopped using the
      Debian-packaged mingw32 cross-tools and used the script directly
      from the mingw project:

      http://downloads.sourceforge.net/mingw/x86-mingw32-build.sh-0.0-20061107-1.tar.bz2

      I used the above to create a crossbuild environment under
      /usr/local/mingw.

      After that, I built *everything* from source needed for the
      crossbuild, including all the SDL* libs, gettext, libiconv,
      libjpeg, freetype, and so forth.  There were a number of
      pitfalls along the way, and hopefully I will get this documented
      at some point.  Suffice to say that tuxmath itself builds fine
      in this way, once the environment is set up.

      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
        libiconv-2.dll

      The svn repository has a directory with copies of all of these files:

        tuxmath/people/dbruce/tuxmath_dll


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

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

      This should create the windows installer file
      ("tuxmath-1.6.1-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 OS X: (contributed by Tim Holy)
  ----------------------------------

  There are several options for compiling on OS X.  If you just want
  to do a local build, using macports is perhaps the easiest approach:
  "port install tuxmath" and then wait.

  To build a .dmg, currently-supported approach is to use CMake
  (described above under Linux/Unix).  You will need to have both
  gettext and cmake installed on the build machine; using macports is
  the easiest way, "port install cmake gettext".  "make install" will
  create the .dmg in the build directory.

  Finally, it is also possible to do the conventional "./configure;
  make; make install" if you have the required libraries.

  There is still an old XCode project file in the macosx/ directory,
  but this is not up-to-date.  If you want to develop with XCode, you
  probably want to use CMake to create a new XCode project.  See the
  CMake documentation for details.
