INSTALL.txt for "Tux, Of Math Command" (aka "Tuxmath") Version 1.7.2 March 12, 2009 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 now has extremely 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. For Windows/Macs: visit http://www.tux4kids.com, 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. 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 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. 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. 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 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). SDL_Pango is not yet supported in the Windows build or 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". 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 (and, optionally, SDL_Pango) 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 Library General Public License (LGPL). Getting SDL ----------- On Linux, the easy way to get the required SDL packages is from your distributor. 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 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 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.7.2-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/SDL_Pango. (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.7.2-tar.gz cd tuxmath_w_fonts-1.7.2 ./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 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 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 trunk): mkdir build cd build autoreconf --install ../trunk ../trunk/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 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 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. 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. The only deficiency as of this writing is that SDL_Pango is not supported. 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.7.2-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: ---------------------------------- 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.