INSTALL

Contents:
  1. Prerequisites
  2. Common instructions
  3. Scons build
  4. CMake build
  5. Autotools build


1. Prerequisites:

You'll need to have these libraries (with equivalent devel versions) to build Wesnoth:

 boost_iostreams >= 1.33.0
 boost_regex >= 1.33.0
 libfontconfig >= 2.4.2
 libpango (with cairo backend) >= 1.14.8
 libsdl >= 1.2.7
 libsdl-image >= 1.2 (with png support)
 libsdl-mixer >= 1.2 (with Vorbis support)
 libsdl-net
 libsdl-ttf >= 2.0.8
 libz

There are currently three ways to build wesnoth:
 * The old autotools system
 * scons
 * cmake (still incomplete, but most stuff works)

2. Common steps:

In the future, autotools will probably be replaced with either scons or cmake.
Once scons and cmake are complete all build systems will be evaluated and
one build system will be chosen as the official build system.

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 (see https://gna.org/bugs/index.php?10326)
that under gcc 3.3.6 you need to turn off optimizations or you will
get a build that doesn't work for multiplayer.  We recommend building
with gcc 4.

If you see lots of messages like "Type 'svnversion --help' for usage.",
you have a Subversion client installed but it is not implementing the 
-n option of svnversion. Time to update it.

Source-code:

You can get it here:

 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

You will need the following tools:

 python >=2.4
 scons

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

Simply type 'scons' in the top-level directory to build the game and
editor. It is possible to select individual targets by naming them as
scons 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 want to set prefix=/usr.

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

So, for example, this builds game, editor, and campaign server,
enabling debugging on all:

    scons build=debug wesnoth wesnoth_editor 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 want 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 want 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-wesnoth_editor',
'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 editor, 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.  It runs
in one step, checking your configuration amnd building, rather than (as
autotools does) generating makefiles to be run later.  So not all autotools
options have exact scons equivalents.  

But here is a translation key, autotools configure options on the left
and scons command-line options 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 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
  --disable-python          python=no
  --enable-python-install   N/A
  --enable-lite             N/A
  --enable-tinygui          gui=tiny
  --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-editor           (See --help documentation on choice of targets)
  --enable-tools            (See --help documentation on choice of targets)
  --enable-dummy-locales    dummy_locales=yes
  --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.4-patch 8 . You can get cmake at 
http://www.cmake.org .

There are two ways to build wesnoth with cmake: Inside the source tree or outside.
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
 $ make install

To build wesnoth in the source directory:

 $ cmake .
 $ make
 $ make install

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

 $ cmake .. -DOPTION=value

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

 $ ccmake ..

Build options:

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

Debug builds:
Set CMAKE_BUILD_TYPE to "debug"


5. Autotools build

The .tar.bz2 file is distributed with a working set of configure files. They
are not in the SVN repository. Consequently, if you are building from
SVN, you will need autoconf (>= 2.60) and automake (>= 1.9). Run './autogen.sh'
then to generate the configure files.

 $ ./configure
 $ make
 $ make install

as usual.  See './configure --help' for all available options.
You should clean your existing wesnoth release build first with:

 $ make distclean

If you want to clean your wesnoth SVN build do:

 $ make maintainer-clean