speed-dreams-code/INSTALL.txt

Table of contents
-----------------

WARNING: Only intended for developers who'll build Speed Dreams from sources.

I - Pre-requisites

II - Linux Installation from sources

  1 - Introduction
  2 - Installation from the official tarballs
  3 - Installation from SVN (developers only)
  4 - Run Speed-Dreams
  5 - Getting Help

III - Windows Installation from sources

  1 - CMake and MinGW under Windows
  2 - CMake and MS VC++ 2005 (8) / 2008 (9) / 2010 (10) under Windows
  3 - MS VC++ 6 : no more supported

IV - FreeBSD Installation from sources (Work in progress)

V - MacOS X installation from sources (TODO)



I - Pre-requisites
------------------

- Working OpenGL Driver and header files / associated libraries
- SDL 1.2.12/13/15 (http://www.libsdl.org/)
- PLIB 1.8.3 / 4 / 5 (http://plib.sourceforge.net/). 
  Linux: Be carefull to compile plib with -fPIC on AMD64 if you run a 64 bit version.
- OpenAL soft 1.5 / 1.6 / 1.11 / 1.14 (http://connect.creativelabs.com/openal)
   (Torcs modified 0.0.8 from www.torcs.org also used to work in the past).
- ENet 1.3.2/4 (http://enet.bespin.org)
  Linux: Be careful to compile ENet with -fPIC on AMD64 if you run a 64 bit build.
- Expat 2 (can be skipped for the moment, but won't anymore soon)
- Free Solid 2 (optional for the moment, will soon get mandatory)
- libpng
- zlib
- jpeg 

WARNING: Under Windows, be carefull to compile anything for multi-threaded DLL integration (/MD[d])


II - Linux installation from sources
------------------------------------

1 - Introduction

There are 2 ways of building and installing Speed Dreams from sources :
- from the official source tarballs,
- from the subversion repository.

Pick only one of the above options. If you have trouble during the installation,
have a look in the FAQ on the above sites. In case you get stuck,
please learn how to report the problem in the FAQ before filing a bug or contact us.

Have fun,

The Speed Dreams Team.


2 - Installation from the official tarballs

  a - get these tarballs : please go to our SF.net download page at

        http://sourceforge.net/projects/speed-dreams/files/2.0.0,

      and you should find :

        speed-dreams-src-base-<version>.tar.xz
        speed-dreams-src-hq-cars-and-tracks-<version>.tar.xz
        speed-dreams-src-more-hq-cars-and-tracks-<version>.tar.xz
        speed-dreams-src-wip-cars-and-tracks-<version>.tar.xz
        speed-dreams-src-unmaintained-<version>.tar.xz

      where <version> is something like "2.0.0-rc1-r4420", "2.0.0-r4687", ...

      Warning: you must download them all, as our current build system
	           can't cope with missing files.

      Let's say that :
      * you downloaded them all in $HOME/sd,
      * and that <version> is x.y.z-rabcd.
      (you can do as you like, but we'll use this folder in the explanations below).

  b - uncompress the tarballs :

      $ cd $HOME/sd
      $ mkdir x.y.z-rabcd
      $ cd x.y.z-rabcd
      $ for file in ../*.xz; do tar xvfa $file; done

      You should now see "cmake", "data" and "src" folders (among others).

  c - configure :

    1. create the build dir for CMake

      $ mkdir build
      $ cd build

    2. run CMake :

      - for a Release build using default 3rd party libs

        $ cmake -D OPTION_OFFICIAL_ONLY:BOOL=ON ..

        Note: This "OFFICIAL_ONLY" stuff is mandatory, otherwise
              you'll get errors saying that some (unofficial contents) folders
              are missing, just because the official tarballs don't include them.

      - you may also want to override some default settings :

        for that, you can use the -D option of cmake :

          Example :

            $ cmake -D SD_LOCALDIR:STRING=~/dev/.sd-settings \
                    -D CMAKE_PREFIX_PATH:STRING=/usr/local
                    -D CMAKE_BUILD_TYPE:STRING=Debug

        or else you can use ccmake to change the variables interactively :

            $ ccmake ..

             * press (t) for advanced options if needed
             * in order to change a variable :
               * select the associated line using the up/down arrow keys
               * press (enter)
               * edit the value
               * press (enter)
             * press (c) for configure
             * press (g) for generate
             * press (e) to exit


        Usefull CMake variables for Speed Dreams (note that some might be "advanced" ones) :

        - CMAKE_BUILD_TYPE:STRING :
            Debug, Release, RelWithDebInfo, MinSizeRel (def: Release)

        - OPTION_OFFICIAL_ONLY:BOOL :
            Build/install only official contents (def: OFF)

        - SD_LOCALDIR:STRING :
            User settings dir for run-time (def: ~/.speed-dreams-2)

        - CMAKE_PREFIX_PATH:STRING :
            Path prefixes for additional 3rdParty libraries (def:empty)
            (use /usr/local if you compiled some 3rdParty libs yourself).
        - CMAKE_INSTALL_PREFIX:PATH :
            Install path for Speed Dreams (def: /usr/local)

        - OPTION_3RDPARTY_EXPAT:BOOL :
            Enable building against 3rd party Expat 2 library, rather than bundled txml (def: ON)
			Disable if "Expat 2 dev" is not available for your distro (which is very unlikely).

        - OPTION_3RDPARTY_SOLID:BOOL :
            Enable building against 3rd party Free Solid 2 library, rather than bundled one (def: OFF)
			Note: This is not set by default, because Free Solid 2 dev is not yet available
			      on most Linux distros (only Fedora is working on this right now, AFAIK, 2012, July)
				  Ask the dev team for any hint about building it ...

        - OPTION_TRACE:BOOL :
            Full run-time traces if ON (def: ON)

        - OPTION_TRACE_LEVEL:STRING :
            Run-time traces level integer threshold, only if OPTION_TRACE
            (traces with higher level are not logged ;
             0=Fatal, 1=Error, 2=Warning, 3=Info, 4=Trace, 5=Debug, ...) (def: 5)

        - OPTION_UNLOAD_SSGGRAPH:BOOL :
            The 'ssggraph' graphics engine module will never be unloaded if OFF (def: ON)
            Usefull under some Linux configurations where this unloading badly crashes XOrg
            (see http://sourceforge.net/apps/trac/speed-dreams/ticket/209),
            or simply makes SD crash because PLib is shipped as a set of shared libraries
            (see http://sourceforge.net/apps/trac/speed-dreams/ticket/459).
 
        - OPTION_FORCE_DEBUG:BOOL :
            Enable debug symbols even in Release builds (def: OFF)

        Tips reported about some issues :
        - sometimes, ENET_INCLUDE_DIR is not detected correctly, resulting in something like
          /usr/include/enet or so, and, consequently, in bad compilation errors because
          /usr/include/enet contains a special time.h header file that conflicts with the standard
          one in /usr/include. Removing the "enet" postfix from ENET_INCLUDE_DIR should fix this
          (in cmake command line or interactively through ccmake).

  d - build:

      $ make
  
  e - install:

      $ sudo make install
  
      Notes:
      * sudo is only useful if your install PREFIX is a read-only folder (like default /usr/local)
      * sudo configuration : you may ask your system administrator to enable you to run
        'sudo make install' ; if he doesn't know how, you can tell him/her
        to add a line like this in /etc/sudoers (or something less permissive ;-) :
           <your login name>    ALL=(ALL) NOPASSWD: ALL

3 - Installation from SVN

  Before you start, be aware that the SVN trunk / branches might crash or even not compile
  sometimes. If you want to get it anyway, follow the instructions at
    http://sourceforge.net/svn/?group_id=239111

  For the moment, 
  - the developments for the next release are located in the trunk ; 
    you can checkout the current _development_ state through :
     $ svn co https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/trunk sd-trunk
  - we make branches under the "branches" root dir ; as an exemple,
    you can get the "1.4.x" release maintenance branch current state through :
     $ svn co https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/branches/1.4.x sd-1.4.x
  - we make release tags under the "tags" root dir ; 
    as an exemple, you can get the "2.0.0 RC 1" pre-release through :
     $ svn co https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/tags/2.0.0-rc1 sd-2.0.0-rc1

  See configure, build and install method above (2)
  (note however that branches/1.4.x and tags/1.4.0 are not built through cmake :
   please refer to the dedicated INSTALL file for these).

4 - Run Speed-Dreams

  If the default CMake settings were kept, Speed Dreams is normally installed in /usr/local.

  So, if /usr/local/games is already in your PATH variable, simply try :

    $ speed-dreams-2
      
  If /usr/local/games not already in your PATH variable, you may want to add it ; to do so,
  simply add the line "export PATH=$PATH:/usr/local/games" to your  ~/.bashrc file ;
  you can use :

    $ echo "export PATH=$PATH:/usr/local/games" >> ~/.bashrc" for that

  Then, the above startup command should work now :

    $ speed-dreams-2

  If not or if the game crashes, see right below "5 - Known run-time issues".
      
  Runtime options : type this command to get them explained :

    $ speed-dreams-2 --help

5 - Known run-time issues :

  * Under some Linux configurations, the game crashes after restarting a race,
    of when exiting ; we have a build-time workaround for this :
    see above, in II-2-c-2, the OPTION_UNLOAD_SSGGRAPH CMake option.

  * If you get all white rectangles or ugly fonts in the menus,
    it's likely that some game data was not properly installed ;
    check again carefully the build and install instructions.

6 - Getting Help

  From inside the game, press F1 at any time, you'll get a help page explaining
  the available keyboard shorcuts.

  If you are stuck please report problems through speed-dreams-users mailing list
  or our bug tracker at http://sourceforge.net/apps/trac/speed-dreams/report.


II - Windows installation from sources
---------------------------------------

Note that these instructions work under Windows XP 32 SP2/SP3 ; some tweaks wight be needed for newer / wider versions.

0) Initial steps, common to all build methods

  a.  Install CMake v2.6+ http://www.cmake.org/cmake/resources/software.html
  b.  Download the official Speed Dreams tarballs from SF.net
        http://sourceforge.net/projects/speed-dreams/files/2.0.0
      (speed-dreams-src-<package>-<version>.tar.xz)
	  Note: See below if you want to do it from SVN, in order to get the latest changes ...
  c.  Extract their contents to your local disk (7Zip is an excellent tool for that),
      all in the same target folder.
      Warning: You need to extract all of the source packages in order to start building
               (see ablove 2-a chapter for more).

1) Cmake and MinGW :

  Work-in-progress ...

  Tested with success for :
    - CMake 2.8.3 + MinGW shipped with Nokia Qt Creator 2.4.1 (gcc 4.4.0)
    - CMake 2.8.8 + MinGW shipped with Nokia Qt Creator 2.4.1 (gcc 4.4.0)
    - CMake 2.8.2 + MinGW 2012 April (gcc 4.7.0)
    - CMake 2.8.8 + MinGW 2012 April (gcc 4.7.0)

  d.  Install MinGW and MSYS 

     Following the instructions of http://www.mingw.org/wiki/Getting_Started
     (example here for the official release of 2012, April, featuring gcc 4.7.0) :

     * Download and run the latest mingw-get-inst version from 
        https://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst/
        => mingw-get-inst-20120426.exe
     * Select the directory where to install MinGW, remembering the advice
       that the path to this directory should not contain any spaces.
       => C:\MinGW
     * Select the minimal set of components to install :
       * C++ compiler
       * MSYS.

     * Run MSYS, the MinGW Shell (bash) :
       Start Menu / Programs / MinGW / MinGW Shell

       Note: PATH is already configured for using all useful tools
             (try the command "echo $PATH")

     * Optional but usefull additional components :
       * rxvt (a Linux-like terminal) : mingw-get install msys-rxvt
         - customize rxvt terminal : in C:\MinGW\MSYS\1.0\msys.bat, line 98 : "start %WD%rxvt ...",
           . -geometry 120x40
           . -sl 9999
         - change MSYS Shell shortcut command : msys.bat --rxvt
       * vim (text editor for Linux geeks) : mingw-get install msys-vim
       * patch : mingw-get install msys-patch
       * xargs and co : mingw-get install msys-findutils
       * bzip2 : mingw-get install msys-bzip2
       * xz : mingw-get install msys-xz
       * diff and co : mingw-get install msys-diffutils

     * Optional tweaks to /etc/profile (C:\MinGW\msys\1.0\etc\profile)
       * add your usual aliases : alias xx='command'
       * a nicer prompt : export PS1='\w $ '

     * Direct X 7 SDK for MinGW : Optional for building SD, but mandatory if you want
       to build yourself the 3rd party libraries SDL, PLib, and OpenAL :
       * download it from http://alleg.sourceforge.net/files/dx70_min.zip
       * extract it somewhere on your hard disk (let's say C:\dx7_mingw)
       * add the following line to /etc/fstab (C:\MinGW\msys\1.0\etc\fstab)
         C:\dx7_mingw /dxsdk # DX7 SDK for compiling SDL, PLib, OpenAL

       Note: The other newer versions from http://alleg.sourceforge.net/files didn't work for me.

     Another solution (tested with success) :
      * MinGW itself : You can use the one shipped with Nokia Qt Creator
        (Release 2.4.1 worked for me)
      * MSYS :
  	  	- download and install the latest 1.0.x through the MinGW installer
            https://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst/
        - add a /mingw mount point to the fstab in order MSYS knows where MinGW is installed
          (inside Qt Creator folders) :
          ex: add a "c:/Qt/qtcreator-2.4.1/mingw /mingw" line to /etc/fstab
      * Qt creator is a full-fledged IDE, making you able to :
        - open your SD "project" (equivalent to a MSVC "solution")
          by simply opening the master CMakeLists.txt in Qt Creator,
        - run CMake after specifying the needed options (see below),
        - make and install SD,
        - and everything you expect from a modern IDE (MSVC 2005 is not one ;-)
        all of the above through the GUI.
      * But you'll have to build yourself your 3rd party package for this (older) GCC version

     Last minute news : It seems that Nokia no more ships MinGW with it's QtCreator IDE,
      but let you use the one you like ... see Nokia's HOWTO pages.

  e.  Download the "MinGW 4.7.0" release of the Speed Dreams "3rdParty" binary package from SF.net
        http://sourceforge.net/projects/speed-dreams/files/3rd%20party
      (it contains necessary 3rd party libs compiled with/for MinGW 4.7.0)

  f.  Extract it to the /usr/local folder :
      From the MinGW Shell :
      $ cd /usr
      $ tar xvfz .../3rdParty-2.1-win32-mingw470-g-O2.tar.gz

  g.  Run CMake to configure the build (here we assume CMake 2.8, but newer versions should work) :

      $ cd /path/to/sd/sources/trunk
      $ mkdir build
      $ cd build
      $ /c/Program\ Files/CMake\ 2.8/bin/cmake -G "MSYS Makefiles" -DOPTION_OFFICIAL_ONLY:BOOL=On -DCMAKE_PREFIX_PATH:STRING=/usr/local -DCMAKE_BUILD_TYPE:STRING=Release ..
      $ make # -j2 or even -j4 if you own a dual/quad-core CPU
      $ make install

      Note: This 'Release' build gives you -O3-optimised binaries.

2) Cmake and MS VC++ 2005 (8) / 2008 (9) / 2010 (10) on Windows XP 32

Note: If you use an "Express" version, don't forget to install also the Windows SDK.

  d.  Download the "MSVC 2005 / 2.0.0-or-earlier" release of the "3rdParty" binary package from SF.net
        http://sourceforge.net/projects/speed-dreams/files/3rd%20party
      (it contains necessary 3rd party libs compiled with/for MSVC 2005)
  e.  Extract from the zip file the "3rdParty" directory to where speed-dreams sources
      are installed.  
      Example: If sources are in c:\gamesources\speed-dreams\src-2.0.0
               (inside which you should find at least the "src" and "data" folders), 
               then extract 3rd party zip in c:\gamesources\speed-dreams\3rdParty
               (inside which you should find at least the "include" and "lib" folders), 
  f.  Startup CMake and set :
      * "Where is the source code" to c:\gamesources\speed-dreams\src-2.0.0
      * "Where to build the binaries" to c:\gamesources\speed-dreams\src-2.0.0\build
        (if you follow the folder specs above).
  g.  Press "Configure" button, answer "Yes, create the ...\build folder"
      and select the compiler.
      Press the "Configure" button again, until the "OK" button is no more greyed.
  h.  Press the "Generate" button.  CMake will generate the solution file "speed-dreams-2.sln"
      and associated project files (*.vcproj) in the ...\build folder
      (Note : .sln/.vcproj are OK for MSVC 2005, but you might get other files extensions
              the later MSVC versions).
  i.  Load speed-dreams-2.sln in MSVC IDE.
  j.  Select the build configuration (Debug, Release, ...).
  k.  Build the whole Solution (Build / Build Solution)
  l.  Build the 'INSTALL' project (right click on it and select Build).
  m.  Double-click on speed-dreams-2.exe in c:\Program Files\speed-dreams-2\bin

 Note: First-ever startups sometimes fail to correctly write the necessary stuff
       into <My documents>\speed-dreams-2.settings and this prevents the game from starting.
       If this happens, simply remove the <My documents>\speed-dreams-2.settings folder
       with Windows explorer, and restart the game : it should now work.

 Note: This should also work with MSVC 2008/2010.
       For MSVC 2003, you'll probably need to rebuild
       a dedicated 3rdParty package for this compiler

 Note : If you need to recompile the 3rdParty package from sources,
        (the "Sources/2.0.0-or-earlier" release of the "3rdParty" package on SF.net Download page)
        be carefull then to rebuild :
         - everything possible
         - for the same configuration (don't mix Release and Debug) 
         - everything for multithreaded DLL integration (/MD & /MDd),
        ... or be ready for headaches, and no support at all ;-)

 Note: Building from SVN repo at SF.net :
       From trunk@r4790, there's CMake support for a new MSVC 2005 3rd party binary package,
	   with updated releases of the dependencies, + 2 new ones : Expat 2 and FreeSOLID 2,
	   coming there in order to replace the bundled versions (txml and simuv2.1/SOLID-2.0),
	   in order SD becomes compatible with FOSS Linux distros (like Fedora, Debian, ...).
	   See http://sourceforge.net/projects/speed-dreams/files/3rd%20party/MSVC%202005/post-2.0.0
	   (and http://sourceforge.net/projects/speed-dreams/files/3rd%20party/Sources/post-2.0.0),
	   along with "II - Linux installation from sources" for some more tips about CMake options.
	   

3) MS VC++ 6 : No more supported.

III - FreeBSD installation from sources
---------------------------------------

Mostly the same as for "Linux installation from sources" ...

Some specific details though :

2 - Installation from official tarballs

  b - build and install:

    1.  cd $HOME/sd/2.0.0/build
    2.  ccmake ..
    3.  press (t) for advanced options
    4.  wanted rows CMake CPPFLAGS
    5.  press (enter)
    6.  add /usr/local/include
    7.  press (enter)
    8.  press (c) for configure
    9.  press (g) for generate and press (e)
   10.  make && sudo make install
  
     
    TO BE COMPLETED


IV - MacOS X installation from sources
--------------------------------------

To do ...