Build instructions for KeeperFX
------------------------------
TOC
1. Downloading the code repository
2. Compiling under Windows
3. Cross-compiling on Linux host
4. Building additional files
5. Building a package
6. Make command targets summary

1. Downloading the code repository

You may use any SVN client application to download KeeperFX code.
Just connect to the repository and "checkout" the "trunk/keeperfx"
folder, or the whole "trunk" if you're also interested in tools
which are being developed with KeeperFX.

Note that the ".SVN" folders created by SVN client will not affect
the build, so you don't need to delete them.

2. To compile the game on Windows host, you need the following programs:

- MinGW32, Minimalist GNU for Windows with MSys
  http://sourceforge.net/projects/mingw/files/

- Coreutils, GNU Utilities pack for Windows
  http://sourceforge.net/projects/gnuwin32/files/coreutils/

- 7Zip, file archiver with a high compression ratio
  http://www.7-zip.org/download.html
  This one is only needed for making release package

The SDL library build is uploaded on KeeperFX repository, so you don't
need to compile SDL library on your own.

After all the tools are installed in locations referenced by "PATH"
environment variable, you have to run "sh". The "sh", which is part of
MSys package shipped with MinGW32, is one of UNIX shells - BASH.
The shell is something like "cmd.exe" on Windows - but standardized to
UNIX specification, so even tho there are more than 10 shells written
by different people, they all share the universal set of basic commands.
Use the shell to go to the folder where keeperfx repository is (with
"cd" command). You can check if you're in a correct directory with "pwd"
command. The directory should contain "Makefile" file - you can list
files with "ls" command.

Now you should run the correct "make" commands.
Use "mingw32-make standard" to compile the standard version of KeeperFX
executable. This is the version you usually play.
Use "mingw32-make heavylog" to compile the verbose logging version of
KeeperFX executable. This version creates huge LOG files which are useful
for finding bugs.
Use "mingw32-make package" to compress the previously compiled executables
and configuration files for KeeperFX into a compressed patch package, ready
to be released. Note that using the "package" build target without compiling
"standard" or "heavylog" version will result in a package without executable
files, which isn't very useful.

Remember to run the "make" command from within "sh", not from Windows "cmd",
as the "Makefile" will use shell-specific clauses incompatible with Windows,
ie. "if" statement or "echo" command. If you tried to use "cmd", then before
you start building with "sh", execute "make clean" to get rid of files which
were incorrectly generated by Windows shell. 

3. Cross-compiling on Linux host

It is possible to cross-compile KeeperFX for Windows using Linux as host.
Make copy of the "keeperfx_build.sh" file (from github.com/dkfans/nightlybld)
somewhere outside of the KeeperFX project folder. Edit the file and change variables
at its beginning to match your system. Then you can checkout GIT and recompile the
game by just running that script.

Of course, you can also trigger the cross-compile by yourself. You do this like:
 make standard CROSS_COMPILE=i586-mingw32msvc-
where the value of "CROSS_COMPILE" should be a prefix (may also include path)
of the cross-compiler toolchain you wish to use. 

Note that you need mingw32 cross-compiler for Linux to do the compilation.
Some Linux distributions allow to easily install the mingw32 cross compiler from
their repositories, other may require to manually compile mingw32. Recompiling
mingw32 isn't trivial, but you may learn a thing or two in the process. Please be
sure to use 32-bit version of MinGW.

If you'll make the script working, you can easily create your own "nightly builds"
site, which will automatically build KeeperFX releases. Just use CRON to start the
script every day, and it will automatically build and publish the package.

4. Building additional files

Besides the executable file, build system in KeeperFX can also generate other files
used by the game. The following make commands can be used for this:
"mingw32-make pkg-languages" - generate text strings DAT files from PO/POT translation sources
"mingw32-make pkg-gfx" - generate graphics DAT/TAB/RAW/PAL files from PNG bitmaps

Note that "mingw32-make pkg-gfx" requires access to libPNG library. Also, the source PNG files
used to generate DAT/TAB/RAW/PAL files are not kept on SVN repo - you must download
them separately and place in "gfx" folder. Download link is on the site:
http://keeper.lubie.org/html/dk_keeperfx_devel.php

5. Building a package

There is one more very handy function of the build system. It places all the files
which were built into correct folders (as in the release) and them compresses them into
a single archive file, which can be easily published as a KeeperFX patch.

The command is "mingw32-make package". It will compress binaries and other files (scripts,
config files, DAT files) into archive which can be released as a patch. This requires 7-zip
to be installed on the host system.

Making package will trigger automatic build of language files, but it won't trigger building
any executables or graphics files.

6. Make command targets summary

The following targets can be used for make:
standard - build binaries for 'standard release' of KeeperFX
heavylog - build binaries for 'heavylog release' of KeeperFX
pkg-languages - generate text strings DAT files from PO/POT translation sources
pkg-gfx - generate graphics DAT/TAB/RAW/PAL files from PNG bitmaps
package - compress binaries and other files into 7z archive
all - just an alias for 'standard'
clean - removes files created during previous builds

Additionally, you can add "DEBUG=1" to the command to build debug version of
standard or heavylog executable, ie:
 make heavylog DEBUG=1
This will build the game with debug symbols, which can be use for tracing
the program execution with a debugger, ie. GDB.

To prepare a KeeperFX release, run the commands in the following order:
 make clean
 make standard
 make heavylog
 make package
