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

November 09, 2010

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

Slower machines will, however, haved a noticeable delay at program startup
related to scaling of all the SVG images introduced in version 1.8.0.


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 scripts 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/
	SDL_gfx:    http://www.ferzkopp.net/Software/SDL_gfx-2.0/


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-1.8.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: -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:
 
tar -xzf tuxmath_w_fonts-1.8.0-tar.gz
cd tuxmath_w_fonts-1.8.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.

On Mac OS X, this builds a static "intl" library (for internationalization
support) and creates a .dmg file. Building requires the full gettext
infrastructure; see below under "Mac OS X" for more details.

(NOTE: the CMake build has not been tested for 1.8.0 and likely will have some
problems related to new library dependencies).

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 is not officially part of
mingw-cross-env, so you need to add t4k_common's *.mk file into mingw-cross-env's
source directory.  Then, you can just do "make t4k_common" from the main mingw-cross-env
directory to build it like any other mingw-cross-env lib. 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:
----------------------------------

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)

