This document describes steps needed to compile Widelands for different
systems using different compilers. If you have problems, please also have a
look at our website http://www.widelands.org, especially the FAQ.



================
= Dependencies =
================
These are the libraries you need. You also need the headers and link libraries
(on some distributions these come in separate packages, e.g. 'libpng-dev'),
for Widelands makes direct use of them:
   - SDL >= 1.2.8
   - SDL_mixer >= 1.2.6
   - SDL_image
   - SDL_net
   - SDL_ttf >= 2.0.0
   - SDL_gfx
   - boost >= 1.35
   - gettext (look at FAQ if you have problems with -lintl)
   - libpng
   - zlib
   - libjpeg
   - libiconv (only needed under win32)
   - libintl (only needed under win32)

Make sure you have them all. If you encounter library versions that do not work,
please tell us.

Optional you will need the following libraries for Widelands' metaserver usage:
   - ggz-base-libs >= 0.99.5
or
   - ggz-client-libs == 0.14.1
   - libggz == 0.14.1

For compiling, you will also need
   - Python >= 2.3
   - CMake 2.6 (strictly recommended)
   - scons >= 1.0.0 (optional, if you don't want to use CMake yet, see below)
If you have a desparate need to use older Python versions then tell us. It'd be
possible, but the inconvenience seems not to be worthwile so far.

If you are a developer, you might (optionally!) make use of the following software:
   - ctags
   - astyle
     astyle does not layout correctly when structs are used like public classes (C++)
     and not in the traditional C sense. If you decide to use this, please
     double-check the results before committing
   - pngrewrite and optipng
     Used to make PNG images more compact. You most certainly don't need this;
     compactification is a once-a-year, one-person-only job. If you don't know
     already that you will be doing it, forget about it.
   - Krazy
     A sourcecode checker from the KDE project, subversion repository available at
     svn://anonsvn.kde.org/home/kde/trunk/quality/krazy2
   - Doxygen
     Used to generate source code documentation.

CMake is the new way of building widelands. To make it easier, we provide a script.
Below is an excerpt of the http://wl.widelands.org/wiki/BuildingWidelands/ page, see there
for more detailed information.

============
=Unix/Linux=
============

CMake
------------------
The currently most recommended way to build Widelands is using CMake.
The other ways (SCons, Make standalone) will probably be removed before release of Build16.

The easiest way to start with CMake is the script build_and_run.sh, which is primarily
used as entry point for beginners. It creates the out of source build directory
(see below for details), initializes the cmake commands, compiles the sources and then starts the game:

   $ ./build_and_run.sh

If you like to run Widelands again later on:

   $ ./widelands

If you want to compile manually, follow this path:

- Create a build directory.
  CMake is a so called out of source build tool. That means, the build runs in a different
  directory than where the sources are located, avoiding polluting the sources 
  directory (and the ignore entries for the VCS systems). If you know SCons, this is different.
  The build directory can either be a path within your sources directory, or a directory
  at a completely independent location. In this example, we are using the subdirectory way:
  Go to your widelands directory, and issue:  

  $ mkdir -p build/compile

  Then go to that build directory

  $ cd build/compile

- Prepare compiling using CMake
  CMake is in fact only a tool to prepare compilation (and more). It creates lots of
  Makefiles depending on your input and things it learns from the environment and of course
  the scripts the widelands developers provided. The most important parameter for the CMake
  command is the path where your sources are located. This path can be relative or absolute.

  $ cmake ../..

  This command should look for a couple of libraries and initialize the Makefiles.

- Compile and link a widelands executable.
  As you already know, CMake only prepares the compilation, the Makefiles. Now run make.

  $ make

- Install the game.
  Unfortunately, you cannot play a game from out of source builds. You have to prepare the
  directory layout to follow the rules of Linux/Unix in a way Widelands finds it. In the
  means of CMake/make this means "installing".
  Since you did not specify any different settings, CMake prepared everything to install
  widelands to /usr/local - this is the default for Linux. Writing files there will require
  root privileges, as this is outside of your home directory.

  $ sudo make install

  Now everything is installed in /usr/local, and you can run widelands:

  $ widelands

- Tweak the setup: different install directory.
  Say, you don't want to install in /usr/local, but in /usr. This can be done by issuing
  this as a parameter to CMake. Parameters are stated by -Dparameter=value.

  $ cmake -DCMAKE_INSTALL_PREFIX=/usr ../..

  That's it. Widelands will now be installed to /usr if you issue:

  $ sudo make install

- Tweak the setup even more: portable directory layout.
  Say, you don't want to install to /usr, but only in your home directory. You don't need
  or want the twin directory layout of /usr/local/share/games/widelands and /usr/local/games.
  You want everything in one directory, and run from this directory. This can be done:

  $ cmake -DWL_PORTABLE=true -DCMAKE_INSTALL_PREFIX=~/widelands-compiled ../..

  The -DWL_PORTABLE=true parameter changes directory layout in a way so that everything runs
  from one directory, and that directory is, after installing, even movable - yes, portable.

  $ make install
  $ cd ~/widelands-compiled
  $ ./widelands

- Additional parameters CMake understands.
  This topic is already "enhanced CMaking", everything necessary is already taught.

  - Versioning.
    Without any settings, CMake refers to BZR revision for versioning. If you want to change that,
    you can use the different ways:

    $ cmake -DWL_VERSION_STANDARD=true ../..

    This uses a fixed set of versioning settings from the CMake script, provided by developers.

    $ cmake -DWL_VERSION_MAJOR=0 -DWL_VERSION_MINOR=15 -DWL_VERSION_ADDITION="DEV"

    This defines the versions manually.

  - Build type (Release or Debug build)
    When omitting the Build type, CMake decides upon finding of WL_RELEASE file if it should do
    a Release or Debug build.
    
    $ cmake -DCMAKE_BUILD_TYPE=Release ../..
    $ cmake -DCMAKE_BUILD_TYPE=Debug ../..

    This setting overrides the automatic decision.

  - Install directories
    Instead of using the predefined directory layout, you can also modify the details.

    $ cmake -DWL_INSTALL_DATADIR=share/widelands ../..

    This setting defines a path for the data directory relative to CMAKE_INSTALL_PREFIX.

    $ cmake -DWL_INSTALL_BINDIR=gplgames ../..

    This setting defines a path for the executable relative to CMAKE_INSTALL_PREFIX.

    $ cmake -DWL_INSTALL_LOCALEDIR=/usr/locales/widelands ../..

    This setting defines a path for the locales of widelands.
    This path is either absolute (as in this example) or relative to WL_INSTALL_DATADIR
    (for portable setups).

- Additional commands you can use with make:

  - make lang
    In Debug build types, this creates the locale dir and the localizations in it.

  - make codecheck
    This runs codechecking. Obviously a developer command.

  - make optimizepics
    This runs the optimization task for PNG files. Takes very long to run.
    Normally you don't need to do this. This is a developer command.

  - make doc
    This runs source code documentation. Takes very long and lots of disk space.
    Obviously a developer command.

scons
------------------
Using scons for building is the old way starting with Widelands-build10, ending with build15.

We also still support make, but the motivation to do so is dwindling rapidly.

Change to the Widelands directory and execute "scons". That's it.

This will use the default build type, which is "release" for published releases
(who'd have guessed? *g*) and "debug" anytime else. If you want to change the
build type, execute e.g. "scons build=debug". To see all available types, do
"scons -h"

Several other build targets are available :-) but mostly not documented yet :-(

some available scons flags are:

cc=<COMPILER>
cxx=<COMPILER>

ccache=True/False
distcc=True/False

build=debug|release|profile
build_id=<IDNAME>
efence=1 (default false)
enable_ggz=false (default true)

install_prefix=<PREFIX> (default '/usr/local')
bindir=<BINDIR> (default 'games')
datadir=<DATADIR> (default ('share/games/widelands')
localedir=<LOCALEDIR> (default ('share/games/widelands/locale')

stylecheck ('scons stylecheck' will just do the style checking without compiling)

make
------------------
Edit src/config.h.default to your liking and check the Makefile for more
user definable variables. If everything is good, simply run GNU make in the
widelands directory. Unlike scons, the make infrastructure does not support
installation or creation of distribution tarballs.

Once again: there's a strong possibility that make support is on it's way out.

localization
------------
If you choose to install widelands, you'll probably want to take care of proper
l10n setup. Widelands will normally look for it's locale definitions in
<install_prefix>/<localedir> (see "scons -h"). To change this setting, use a
commandline like "scons localedir=foo/bar/baz" (relative to install_prefix)
or "scons localedir=/foo/bar/baz" (absolute path). If you aren't using scons,
set INSTALL_LOCALEDIR in src/config.h before starting the compile.

Unless you are doing a release build, you will have to manually call
"scons locale" to create the message catalogs. Release builds do this by default.

Be aware that our installer does not yet put the files in the correct location.
You will have to move/copy them yourself!



=============
=  Windows  =
=============
If you're searching for a good SVN tool for windows, we recommend Tortoise
SVN.
Check http://tortoisesvn.sourceforge.net.

mingw and msys
------------------
This describes the steps needed to set up a free development enviroment
under Windows and compiling Widelands.
 - get the latest MSYS snapshot from http://sourceforge.net/projects/mingw
 - install it
 - get the latest complete mingw tarball from
   http://sourceforge.net/projects/mingw
 - unpack it under the MSYS sh-shell in the dir /mingw
 - get all library source tarballs which are mentioned in DEPENDENCIES and STDPort from http://www.stlport.com
 - compile and install all stuff
 - check out a widelands SVN version or get a build source release
 - unpack it, edit the makefile user variables and run make
 - if there were no problems, you're done. start developing and commit your
   changes

InnoSetup
------------------
Since Build10 we support an Innosetup file, which can be used for compiling a Setup
(like the official Widelands-Setup available on sourceforge.net-mirrors).
Innosetup can be downloaded from http://www.jrsoftware.org

If you've installed InnoSetup, you just need to open [Widelands]/build/win32/Widelands.iss.
You might change few settings or directly start packing/compiling the setup.

ATTENTION!
Please check if all needed *.dll-files are in [Widelands]-directory during Setup packing/compile.
Else your setup might be useless :-?