INSTALL

Contents:
  1. Prerequisites
  2. Common Instructions
  3. SCons Build
  4. CMake Build


1. Prerequisites:

You'll need to have these libraries and their development headers to build Wesnoth:

 boost_iostreams >= 1.36.0
 boost_regex >= 1.36.0
 boost_serialization >= 1.36.0
 boost_asio >= 1.36.0
 boost_program_options >= 1.36.0
 boost_system >= 1.36.0
 boost_thread >= 1.36.0
 libfontconfig >= 2.4.1
 libpango (with cairo backend) >= 1.21.3
 libsdl >= 1.2.7
 libsdl-image >= 1.2 (with png support)
 libsdl-mixer >= 1.2 (with Vorbis support)
 vorbisfile
 libsdl-net
 libsdl-ttf >= 2.0.8
 libz

Note that problems with SDL 1.2.14 have been reported, thus we advise you to use SDL
1.2.13 for now.

These libraries are optional dependencies that enable additional features:

 libdbus-1 (used for desktop notifications)

There are currently two ways to build wesnoth:
 * scons >= 0.98.3
 * cmake >= 2.6.0

2. Common Steps:

The old autotools build system has been removed, thus you now have to use
either SCons or CMake. Both systems should work nicely and get all
common tasks, that are required for building Wesnoth, done nicely.

SDL libraries can be found at: http://www.libsdl.org
libfreetype can be found at: http://www.freetype.org
Python can be found at: http://www.python.org
Pango can be found at: http://www.pango.org/
The Boost libraries can be found at: http://www.boost.org

You will also need to have a working installation of GNU gettext to build the
translations.

Note: It has been reported that using gcc 3.3.6 and under with optimizations
will result in a build that is incapable of using multiplayer.
See https://gna.org/bugs/index.php?10326 for further details. We recommend using
gcc 4 to build Wesnoth.

Source Code:

You can get the source code from: http://www.wesnoth.org/downloads


Compiling:

First, untar the package:

 $ tar xfjv wesnoth-x.y.z.tar.bz2

then

 $ cd wesnoth-x.y.z


3. SCons Build

SCons can be found at: http://www.scons.org/ .

Simply type 'scons' in the top-level directory to build the game with the
server. It is possible to select individual targets by naming
them as arguments, including wesnothd (the Wesnoth multiplayer server)
and campaignd (the campaign server).

SCons takes a prefix= argument that says where to install the game
and its data. The prefix defaults to /usr/local; for production builds,
you may wish to set prefix=/usr.

The target 'all' is equivalent to 'wesnoth cutter exploder wesnothd campaignd'.

So, for example, this builds the game and the server:

    scons

This installs binaries that were built before (use su or sudo if required
to write files into the installation prefix):

    scons install

This builds the game and the campaign server while enabling debugging:

    scons build=debug wesnoth campaignd 

To build wesnothd:

   scons server_uid=<user> server_group=<group> wesnothd

where <user> and <group> are valid on your system. A wesnothd
subdirectory will be created under /var/run owned by
<user>:<group>. This is relevant if you wish to be able to communicate
with wesnothd through a FIFO or named socket. You have to run
wesnothd with the user specified while configuring in order for it to
work. You can also specify the FIFO directory directly by using
fifodir=<directory>.

If you wish to install several versions of wesnoth, you should use the
prefsdir= parameter to get distinct preferences directories. The
default is '.wesnoth'.

Installation productions 'install',
'install-wesnothd', and 'install-campaignd' are available.

A plain 'install' installs all binary executables that exist -- so
'scons install' after a plain 'scons' installs game and server, but
after 'scons all', it will install all binaries.

Notes on SCons for autotools users:

The scons build process works in a different way than configure. The scons
build process runs in one step, checking your configuration and building,
rather than generating makefiles to be run later. Not all autotools
options have exact SCons equivalents.  

Here is a translation key. Autotools configure options are on the left, and
scons commandline options are on the right. Defaults are given in square
brackets and are the same as those for corresponding configure options.  
Configure options with no scons equivalents are marked with 'N/A'.

Configuration:
  -h, --help              --help
      --help=short        N/A
      --help=recursive    N/A
  -V, --version           -v, --version
  -q, --quiet, --silent   -Q
      --cache-file=FILE   N/A
  -C, --config-cache      N/A
  -n, --no-create         -n, --no-create, --just-print, --dry-run, --recon
      --srcdir=DIR        N/A

Installation directories:
  --prefix=PREFIX         prefix=PREFIX  [/usr/local]
  --exec-prefix=EPREFIX   N/A

Fine tuning of the installation directories:
  --bindir=DIR           bindir=DIR [bin]
  --sbindir=DIR          N/A
  --libexecdir=DIR       N/A
  --sysconfdir=DIR       N/A
  --sharedstatedir=DIR   N/A
  --localstatedir=DIR    N/A
  --libdir=DIR           libdir=DIR [lib]
  --includedir=DIR       N/A
  --oldincludedir=DIR    N/A
  --datarootdir=DIR      datarootdir=DIR [share]
  --datadir=DIR          datadir=DIR [$datarootdir/$datadirname]
  --infodir=DIR          N/A
  --localedir=DIR        localedir=DIR [$datarootdir/locale]
  --mandir=DIR           mandir=DIR [$datarootdir/man]
  --docdir=DIR           docdir=DIR [$datarootdir/doc/wesnoth]
  --htmldir=DIR          N/A
  --dvidir=DIR           N/A
  --pdfdir=DIR           N/A
  --psdir=DIR            N/A

Program names:
  --program-prefix=PREFIX            N/A
  --program-suffix=SUFFIX            program_suffix=SUFFIX
  --program-transform-name=PROGRAM   N/A

X features:
  --x-includes=DIR    N/A
  --x-libraries=DIR   N/A

System types:
  --build=BUILD     N/A
  --host=HOST       N/A
  --target=TARGET   N/A

Optional Features:
  --disable-FEATURE         N/A (but see instances below)
  --enable-FEATURE[=ARG]    N/A (but see instances below)
  --disable-nls             nls=no
  --disable-dependency-tracking  N/A
  --enable-dependency-tracking   N/A
  --disable-rpath           N/A
  --enable-debug            build=debug
  --enable-profile          build=profile
  --enable-tests            (See --help documentation on choice of targets)
  --enable-static           static=yes
  --enable-python-install   N/A
  --enable-lite             N/A
  --enable-optipng          N/A
  --enable-lowmem           lowmem=yes
  --disable-game            (See --help documentation on choice of targets)
  --enable-server           (See --help documentation on choice of targets)
  --enable-campaign-server  (See --help documentation on choice of targets)
  --enable-tools            (See --help documentation on choice of targets)
  --enable-internal-data    internal_data=yes
  --enable-raw-sockets      raw_sockets=yes
  --disable-desktop-entry   desktop_entry=no
  --disable-sdltest         N/A

Optional Packages:
  --with-PACKAGE[=ARG]            N/A
  --without-PACKAGE               N/A
  --with-gnu-ld                   N/A
  --with-libiconv-prefix[=DIR]    N/A
  --without-libiconv-prefix       N/A
  --with-libintl-prefix[=DIR]     N/A
  --without-libintl-prefix        N/A
  --with-datadir-name[=DIR]       datadirname=DIR
  --with-localedir[=DIR]          localedir=DIR
  --with-fifodir                  fifodir=DIR
  --with-server-uid               server_uid=ID
  --with-server-gid               server_gid=ID
  --without-fribidi               fribidi=no
  --with-preferences-dir          prefsdir=DIR
  --with-icondir[=DIR]            icondir=DIR
  --with-desktopdir[=DIR]         desktopdir=DIR
  --with-x                        N/A
  --with-freetype-prefix=PFX      N/A
  --with-freetype-exec-prefix=PFX N/A
  --with-boost=DIR                boostdir=DIR boostlibdir=DIR boost_suffix=suffix(e.g. -gcc41-mt-1_35)


4. CMake Build

To build with CMake, you need cmake >= 2.6 . You can get cmake at http://www.cmake.org .

There are two ways to build wesnoth with CMake: inside the source tree or
outside of it. Out-of-source builds have the advantage that you can have builds with
different options from one source directory.

To build wesnoth out of source:

 $ mkdir build && cd build
 $ cmake ..
 $ make

To build wesnoth in the source directory:

 $ cmake .
 $ make

To install wesnoth after building (as root using su or sudo if necessary):

 # make install

To change build options, you can either pass the options on the commandline:

 $ cmake .. -DOPTION=value

or use the ccmake frontend which displays all options with their cached values.

 $ ccmake ..

Another possibility is to use a question-based interface, which can be
more convenient for some cases:

 $ cmake -i ..

Build options:

!TODO!
Use "ccmake .." to view a list of all build options with help texts.

Debug builds:
Set CMAKE_BUILD_TYPE to "debug"

Compiler flags:
CMake determines the compiler flags by combining CMAKE_CXX_FLAGS and
CMAKE_CXX_FLAGS_<CMAKE_BUILD_TYPE>. If no CMAKE_BUILD_TYPE is specified only the
CMAKE_CXX_FLAGS are used.

The CMAKE_CXX_FLAGS are controlled by CMake and should not be set by the user.
They are generated by the following parts:
- CXX_FLAGS_MSVC These flags are determined by CMake when using MSVC. They are
  stored so the can be preserved.
- CXX_FLAGS_PROJECT The default flags for all programs in the Wesnoth. These
  flags are determined by the Wesnoth developers.
- CXX_FLAGS_STRICT_COMPILATION The flags used for strict compilation. Whether
  these flags are used depends on the configuration option
  ENABLE_STRICT_COMPILATION.  When this option is changed the CMAKE_CXX_FLAGS
  will be changed to reflect the change. (Starting from Wesnoth 1.11.0 the flag
  can be changed after the initial generation.) What flags are set when choosing
  this option is determined by the Wesnoth developers.
- CXX_FLAGS_PEDANTIC_COMPILATION The flags used for pedantic compilation.
  Whether these flags are used depends on the configuration option
  ENABLE_PEDANTIC_COMPILATION.
- CXX_FLAGS_USER These flags set when configuring Wesnoth. The initial value of
  this variable depends on the CXXFLAGS in the environment or defined by
  -DCXX_FLAGS_USER. These flags are stored and can be changed later by running
  ccmake and changing the value of CXX_FLAGS_USER.