INSTALL for "Tux, Of Math Command" (aka "Tuxmath")
Version 2.0.3

May 04, 2011

For users
---------

This document is mostly about building TuxMath on your own
computer. If you just want to download a working copy of the program,
then you might want to consider pre-built versions.

For Linux: your distribution probably already has packages available.
Your distributor probably has a graphical way to install tuxmath.
Alternatively, you can use the command line to install it.  For
example, with Debian systems you can say "apt-get install tuxmath" and
you're done.

The openSUSE Build Service has had up-to-date builds of TuxMath
for most rpm-based distributions (all recent openSUSE versions, Mandriva 2008
and 2009, Fedora 9 and 10) that can be found via http://software.opensuse.org/search
by searching for "tuxmath" (btw, TuxType is available there, too). Preliminary
developer builds will have "tuxmath_preview" in the package name instead of just
"tuxmath", but all are available to everyone.  However, we have not yet added
TuxMath 2.0.0 to the build service until we work out the added complexity created by
splitting some of the code out to form the t4k_common library.

For Windows/Macs: visit http://tux4kids.alioth.debian.org (note that
http://www.tux4kids.com should also work), click on "Released
Files," and find the most recent package for your platform.  You will
not need the source code packages.  Save the package on your
harddrive and double-click on the icon.

Also, Mac users interested in free/open source software should strongly consider
the MacPorts project (http://www.macports.org).  MacPorts is a package manager
for over 5000 free software programs for the Mac. Both TuxMath and TuxType are
included in MacPorts. Once MacPorts is installed (a simple
dmg file), it is extremely easy to automatically get the latest version of TuxMath.
Be aware, however, that MacPorts does require installation of Apple's XCode
developer tools, which are free but a very big download.

The remainder of this document is for people who want to compile TuxMath
themselves on their own computers.


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

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.
(as of Jan 2009, OpenSolaris does not have all the needed SDL libs -DSB)

CPU
---

Any machine from the last decade should easily handle TuxMath - when first
written, the minimum suggested CPU was a 90 MHz Pentium.  Now that higher
screen resolutions are supported, the increased drawing is likely a bit more
demanding, but nothing compared to a modern 3D game.  As a test, I have started
10 instances of TuxMath on a mid-range 2009 desktop machine with no visible
slowing.

When TuxMath is started for the first time after installation, there will be
a delay of a few to many seconds (depending on machine speed) while the images
are scaled to the correct size for the OS's fullscreen resolution.  This only
occurs the first time through, as the scaled images are cached to disk for 
rapid access on subsequent runs.


Video Display
-------------

By default, TuxMath displays fullscreen, as long as a 640x480 or greater
resolution is supported by your system. Beginning with the 1.7.0 release,
fullscreen mode runs at the native resolution of the operating system, rather
than only 640x480.  TuxMath can also display the game screen in a 640x480
window.  F10 toggles between these two modes.

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. This should not be an issue on any computer from the last 15 years.

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

(NEW) - For some time, Tux Math and Tux Typing have informally shared a lot of
code.  As of Tux Math 1.9.0, the common code has been factored out into a real
library, t4k_common.  To build Tux Math, t4k_common must first be built and
installed.  It can built very easily either with CMake ("cmake; make; sudo make
install") or Autotools ("./configure; make; sudo make install") - see the
documentation for tk4_common for further information. In the near future,
t4k_common should be provided by your distribution's package manager.

Tux Math 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.5, but later 1.2.x versions should work.  libSDL 1.3
will require source code adaptations in future versions of TuxMath when it is
finally released).

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 v1.5.8 (Linux), v1.6.0 (Windows), and v1.6.1(MacOSX),
internationalization is supported using Gnu gettext and libiconv.

TuxMath can use either SDL_Pango or SDL_ttf to display text. SDL_Pango is more
capable and is required for right-to-left display (e.g. Arabic, Hebrew) and
proper rendering of Indic and many other non-Western languages.  Also,
SDL_Pango takes care of font selection, so it eliminates the need for any
bundled fonts. For these reasons, SDL_Pango is the default when available
(Linux and the MacPorts build for MacOSX). If SDL_Pango is available, SDL_ttf
is not needed (as of v1.7.2).

As of v1.8.0, the Windows build finally provides SDL_Pango functionality.

SDL_Pango is not yet in the CMake MacOSX build (the ones available for download
from www.tux4kids.com), so the program still supports SDL_ttf.  For testing
purposes, TuxMath can be built without SDL_Pango by "./configure
--without-sdlpango".

Also, starting with v1.8.0, TuxMath uses librsvg2 to support Scalable Vector
Graphics (SVG) images, mostly used so far in the menus. This require the
librsvg2-dev package on Debian/Ubuntu.

TuxMath v1.8.0 also requires SDL_net if the new LAN multiplayer mode is
desired.  As with SDL_Pango, there are configure-time options to build without
SVG (--without-rsvg) or network (--without-sdlnet) support if these features
are not desired or if the required libraries are unavailable.

The executable Windows installer contains all needed libraries 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 (and, optionally, SDL_Pango, SDL_net, and librsvg2) for building and
installation.  These are easily installed in most any GNU-Linux distribution.
For Debian and its derivatives (including Ubuntu) type "aptitude search SDL" to
find the exact package names, and install them with "sudo aptitude install".
For Fedora and Red Hat derivatives, the "yum" tool works very similarly.

The Andika font is also included in the "tuxmath_w_fonts-*" packages.  You will
definitely want this if building for a platform without SDL_Pango. If you have
SDL_Pango, both the packages with and without fonts should work fine - the
fonts will just take up a bit of space on your hard drive.
    
Note: libSDL, SDL_image, SDL_ttf, SDL_mixer, SDL_Pango, and libiconv are all
Free, Open Source libraries, released under the GNU Lesser General Public
License (LGPL).

Getting SDL
-----------

On Linux, the easy way to get the required SDL packages is from your
distribution's package manager (e.g. apt-get, yum, yast). See below, "Using SDL
Packages".

Alternatively (and by necessity on other platforms), you can download "libSDL,"
"SDL_image," "SDL_ttf", and "SDL_mixer" from the SDL website and build these
libs from source:

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" or "-dev" 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).

For example, on (K)Ubuntu Hardy, you could say:

sudo apt-get install libsdl1.2debian-all libsdl1.2-dev libsdl-ttf2.0-0
libsdl-ttf2.0-dev libsdl-pango1 libsdl-pango-dev libsdl-mixer1.2
libsdl-mixer1.2-dev libsdl-image1.2 libsdl-image1.2-dev libsdl-net1.2-dev
librsvg2-dev

This should work for nearly any Debian variant.



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, which was developed to
better-support Mac OS X.


Linux/Unix
----------

Getting Tuxmath
---------------

You can build Tuxmath either with the latest Git checkout or using a
convenient source tar.gz distribution package. The current website is:

	http://tux4kids.alioth.debian.org
	(http://www.tux4kids.com should point to the same site, although we are
	certainly not "commercial")

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

The Git repository is located at:

	http://git.debian.org/git/tux4kids/tuxmath.git 

	or:

	git://git.debian.org/git/tux4kids/tuxmath.git

Compiling the Program: Automake (Linux)
--------------------------------------

If you are using a source tar.gz package (e.g., tuxmath_w_fonts-2.0.0-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, SDL_ttf/SDL_Pango, and SDL_net & librsvg2,
if desired.

Note that you must install t4k_common before trying to build tuxmath.  t4k_common
has the same library dependencies as tuxmath proper.

(NOTE: -If you have built other packages from source, your system is virtually
certain to already contain the other standard libs used at compile or run time.
If you haven't built anything before, you might need to install some other
packages.  Notably, on Ubuntu the needed tools are included in a package called
"build-essential").

For example (assuming you have already built and installed t4k_common):
 
tar -xzf tuxmath_w_fonts-2.0.0-tar.gz
cd tuxmath_w_fonts-2.0.0
./configure
make
make install.  (you might need "su" or "sudo" for this)
 
Note: the build now uses SDL_Pango by default - the "enable-sdlpango" switch is
no longer needed.  We now have a "--without-sdlpango" option for testing
purposes.  If your build environment lacks SDL_Pango, TuxMath will be built
using SDL_ttf instead.

If you use a Git clone, 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 configure script, Makefile.in's, and friends, so the build
process becomes:
      
autoreconf --install;
./configure;
make;
sudo 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 the top
level):

mkdir build
cd build
autoreconf --install ..
..configure
make
sudo 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", "yum install tuxmath", or using a GUI package manager.



Compiling the Program: CMake (Linux & Mac OS X)
----------------------------------------------

The recommended procedure is to build out-of-source (equivalent to the
"parallel" or "vpath" build for automake described above).

From the top-level tuxmath directory, do the following:

	mkdir build-cmake
	cd build-cmake
	cmake ..
	make
	make install

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

(NOTE: as of this writing, the CMake build is not quite as "smart" as the
automake build.  It doesn't directly test for pthreads, and may drag in some
dependencies that aren't really needed.  If it works for you, fine, but
remember that the autotools build is the officially recommended approach.
Fixing the minor issues with the CMake build is left as an exercise to the
reader, who is then encouraged to submit said patch ;-)

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 package TuxMath into the executable installer, you will need the nsis
package, which is free software available in major distributions (e.g.  "sudo
aptitude install nsis" for Debian).

Starting with v1.8.0, the Windows cross-build uses the mingw-cross-env project
(http://www.nongnu.org/mingw-cross-env). One very great advantage is that the
entire build setup can be installed automatically instead of the very laborious
process of downloading and building 15-20 libs by hand.

Basically, go to the mingw-cross-env site listed above and follow the
well-written directions to get the basic setup in place. Now, you need to
cross-build t4k_common using mingw-cross-env.  As of this writing, t4k_common
has been added to the mingw-cross-env project, but is only in the development
version in the Mercurial repository, not in any stable release.  So, try
running "make t4k_common" from your mingw-cross-env directory.  If it works,
great, otherwise you need to copy the t4k_common.mk file from tuxmath's source
tree into mingw-cross-env's src/, e.g.:

cp t4k_common.mk /opt/mingw-cross-env/src
cd /opt/mingw-cross-env
make t4k_common

This should download and build everything needed for the crossbuild, including
t4k_common itself.  It will take some time (perhaps an hour).  There is a
script in the tuxmath source tree under buildw32/ called
"setup_mingw-cross-env.sh" that will do all of this automatically (tested on
Debian and Ubuntu systems). Be aware that if you have an existing installation
at /opt/mingw-cross-env, it will be clobbered.
 
A copy of t4k_common.mk is provided in the tuxmath source tree until we get it
added to mingw-cross-env itself.

Now you should be all set to do the actual cross-build.  If you put the
cross-build setup in /usr/local/mingw-cross-env, and you are building from a
git clone, you can simply cd to tuxmath's buildw32 directory and use the simple
scripts there:

$ ./tmwin.sh

That's all - it should build a complete NSIS executable installer in the
buildw32 directory, which will be around 17 MB in size. The new crossbuild is
statically linked, so you wind up with quite a large executable (around 25M 
after decompression), but no dll's need to be included.  Also, since SDL_Pango
is supported, no fonts need to be bundled in. 


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

(NOTE - The CMake build has NOT been tested on OS-X recently.  It almost
certainly will require some modifications.  Hopefully I will get time to work
on this sometime soon - DSB).

There are several options for compiling on OS X.  If you just want to do a
local build, using macports (http://www.macports.org/) is perhaps the easiest
approach: "port install tuxmath" and then wait.  MacPorts can also build .dmg
files with "port mdmg tuxmath".  The MacPorts dmg files are very big because
they include all the library dependencies, even things like the X server. 

To build a .dmg, another 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, your best bet might be to
use CMake to create a new XCode project.  See the CMake documentation for
details.

BeOS/Haiku:
-----------

(to be developed)