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

Nov 18, 2006


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.

    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
    ---------------------
      Tuxmath now uses the Gnu Autoconf/Automake tools, meaning that the
      complete build and installation process just involves typing the
      following at a shell prompt within the /trunk directory of the source
      code tree:
      
      ./autogen.sh && ./configure && make && make install

      By default, the build process will install tuxmath under /usr/local/share
      for the data and /usr/local/bin for the executable.  To build tuxmath, you
      will need the SDL dev files as noted above, as well as the GNU developer
      tools, including automake-1.9 and autotools-dev.

      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 win32 dev 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
         SDL_image.dll  jpeg.dll      libgw32c.a    smpeg.dll
         SDL_image.lib  libSDL.dll.a  libpng12.dll  vorbis.dll
         SDL_mixer.dll  libSDL.la     libtiff.dll   vorbisfile.dll
         SDL_mixer.lib  libSDLmain.a  ogg.dll       zlib1.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 is set to  ~/tuxmath_dll. On my machine, this contains:

         dbruce@debian:~/tuxmath_dll$ ls
         SDL.dll        jpeg.dll      
         SDL_image.dll  libpng12.dll  smpeg.dll   zlib1.dll
         SDL_mixer.dll  libtiff.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:
         ./autogen.sh
         ./cross-configure.sh --with-sdl-prefix
         ./cross-make.sh
         ./cross-make.sh nsis

      This should create the windows installer file ("tuxmath-1.0.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). The program can be installed in any writable
      location and should function correctly.  It can be run with ordinary user privileges,
      even if installed by the administrator.


  Mac OSX:
  -------
      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. Download and install Fink (http://fink.sourceforge.net/).
	  3. fink install sdl sdl-image sdl-mixer.
	And if you haven't gotten the source code for tuxmath yet,
	  4. fink install svn-client-ssl (the pre-built binary for the svn-client doesn't support SSL!)
	  5. svn co https://svn.tux4kids.net/tuxmath/

	Then you can follow the instructions above for Linux/Unix.

      Building a disk image:
      ---------------------
      A disk image is a file that can be copied to another Mac, allowing the application to be run.  Assuming you have set up your build environment as above, you can build a disk image by running (from the "trunk" directory)
	./autogen.sh
	./configure
	make macapp
      The disk image will reside in a subdirectory macbuild, and has the name TuxMath.dmg.

      Possible issues:
      ---------------
      The Mac build system has not yet been configured to make a "universal binary," i.e. one that runs on either PPC or Intel macs.
