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
   - GLEW, when compiling with OpenGL support
   - boost >= 1.35
   - lua >= 5.1
   - gettext (look at FAQ if you have problems with -lintl)
   - libpng
   - zlib
   - 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.

For compiling, you will also need
   - Python >= 2.3 but < 3
   - CMake >= 2.6

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.


=======================
= Unix/Mac OS X/Linux =
=======================

CMake
------------------
The easiest way to start with CMake is the script compile.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.

If you want to do it 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).
  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

- Find your libraries: Adapt your library search path.
  Specifies a path which will be used by the cmake commands.  It contains the "base" directories,
  cmake adds  /bin, /lib, /include appropriate to each of the directories.

  $ cmake -DCMAKE_PREFIX_PATH="/tmp/widelands/libraries"

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

  - Controlling which languages are installed
    Instead of having all languages installed, you may want to control which languages are available.

    $ cmake -DWL_LINGUAS="de;en_GB;eo" ../..

    This setting only makes the languages German, English (Great Britain) and Esperanto available.
    You can also select only one language; and you have to use the semicolon character if you want
    to create a list of languages.

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



=============
=  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 :-?

