INSTALL.txt for "Tux, Of Math Command" (aka "Tuxmath") Version 1.5.7 October 29, 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 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. Gnu gettext is required to run "make install". As of version 1.5, TuxMath uses SDL_ttf to display true type fonts. The freely distributable Andika font is included under data/fonts. Note: libSDL, SDL_image, SDL_ttf 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," "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/ 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 --------------------- You can build Tuxmath either with the latest subversion checkout or using a convenient source tar.gz distribution package. The svn repository is located at:         http://svn.debian.org/wsvn/tux4kids/tuxmath or:         svn://svn.debian.org/tux4kids/tuxmath If you are using a source tar.gz package (e.g. tuxmath-1.5.5-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. You also need Gnu gettext as "msgfmt" is called during the installation. For example: tar -xzf tuxmath-1.5.5-tar.gz cd tuxmath-1.5.5 ./configure make make install. (you might need "su" or "sudo" for this) 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 need to run Autoconf's "autoreconf" to generate the configure script, 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". 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 win32dev 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 jpeg.dll libSDL.la SDL_image.dll SDL_ttf.dll zlib1.dll libgw32c.a libSDLmain.a SDL_image.lib smpeg.dll libpng12.dll libtiff.dll SDL_mixer.dll vorbis.dll libSDL.dll.a ogg.dll SDL_mixer.lib vorbisfile.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 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 (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: autoreconf --install ./cross-configure.sh --with-sdl-prefix ./cross-make.sh ./cross-make.sh nsis This should create the windows installer file ("tuxmath-1.5-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 OSX: (contributed by Tim Holy) ------- 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. Check out the code from the subversion repository at alioth. You may have to download and install Fink (http://fink.sourceforge.net/). You may then have to do fink install svn-client-ssl if the pre-built binary for the svn-client doesn't support SSL. 3. Download & install the SDL (www.libsdl.org) Frameworks for MacOSX. You'll need SDL, SDL_image, SDL_mixer, and SDL_ttf. 4. Open the Xcode project (in tuxmath's macosx/ directory) and hit "build." Cross your fingers. The most likely issue you'll encounter is that, as tuxmath progresses, new source code files get added to (or old ones deleted from) the src/ directory. So, you might have to add or remove files from the project. 5. To build a disk image, open a terminal and navigate to the macosx/ directory. Type "make macapp". After a short while, the TuxMath.dmg disk image will appear in the build/Release directory. You can surely also do this using GUI tools. The main issues in getting the Mac build to work come from the fact that it is not using the automake system. So, certain macros have to be defined by Xcode (under Project->Edit Project Settings, then choose the Build tab, in the collection Preprocessing). Currently, the macro definitions are these: MACOSX=1 DATA_PREFIX=\"TuxMath.app/Contents/Resources/data\" VERSION=\"1.5\" $(inherited) In particular, VERSION could be updated with each release (you also should edit InfoPlist.strings if you want the Finder's notion of the version # to be updated). Currently, internationalization is disabled on MacOSX. Anyone who knows how to get the Linux internationalization framework working on MacOSX is invited to contribute.