====== Setup ======

//This page is intended for developers.//

Assumption: You checked out the trunk into ''holdingnuts/trunk'' and created a build-directory ''holdingnuts/build''. If not, see page [[:hacking]].

===== Client =====

==== data directory ====

The client needs to find its ''data''-directory. Without it, the client displays an error-message and exits.

On UN*X, create a **symbolic link** from ''holdingnuts/trunk/data'' to ''holdingnuts/build/data''.

On Windows, create a **windows-shortcut** to ''holdingnuts/build/src/client/holdingnuts.exe'' and set ''holdingnuts/trunk'' as the **working directory**.
==== translations ====

=== update translations for editing with linguist ===
There's a CMake option for updating the translations (rescan the sources).

The following commands update the translation files, e.g. ''holdingnuts/trunk/src/client/translations/hn_de.ts''.

<code>
cd build
cmake -DUPDATE_TRANSLATIONS=On ../trunk
make translations
cmake -DUPDATE_TRANSLATIONS=Off ../trunk
linguist ../trunk/src/client/translations/hn_de.ts
</code>

**Warning:** Don't forget to turn the option off again (''cmake -DUPDATE_TRANSLATIONS=Off ../trunk''). A ''make clean'' would delete the translation-source files!

=== building the translations ===

There's a special make-target called ''translations'' which builds all available translations (''*.ts -> *.qm'').

The following commands build the translation files, e.g. ''holdingnuts/build/src/client/hn_de.qm''.

<code>
cd build
make translations
</code>

**Note:**: The CMake option UPDATE_TRANSLATIONS must **not** be ''On''.

=== use the translations ===

After building the translations, copy the files into ''holdingnuts/trunk/data/i18n''.

<code>
cd build
mkdir ../trunk/data/i18n
cp -v src/client/hn_*.qm ../trunk/data/i18n/
</code>

**Important:** DO NOT check-in those files into SVN, because these are generated files. In a release package the files will -of course- already be present in ''data/i18n''.

**Note:** If there's no Qt installation on your system, you'll need to copy the Qt's own translations (''$QT_DIR/translations/qt_*.qm'') into ''/trunk/data/i18n/'' as well. In a release package these files are present, too.

===== Builds =====

==== Build types (release/debug) ====

There's an internal CMake variable called ''CMAKE_BUILD_TYPE'' which specifies whether to build a **release or debug version**.

In order to build a release version, run following:
<code>
cd build
cmake -DCMAKE_BUILD_TYPE=Release ../trunk
make
</code>

==== Verbose builds ====
Sometimes it's useful to see which commands are executed and which compiler-/linker-flags are used during a build. Use following to get verbose output of the build process:
<code>
cd build
make VERBOSE=1
</code>
==== Partial build ====
There are some options for including/excluding features:
  * ENABLE_SERVER (default: On)
  * ENABLE_CLIENT (default: On)
  * ENABLE_AUDIO  (default: On; client only)
  * ENABLE_SQLITE (default: On; server only)
  * ENABLE_TEST (default: Off; test programs)
  * ENABLE_DEBUG (default: Off; debug version)

Example: Configure for not building the client.
<code>
cmake -DENABLE_CLIENT=Off ../trunk
</code>

==== Additional compiled-in search-path for data-dir ====
The definition ''CMAKE_DATA_PATH'' (Default: unset) adds an own search-path for the data-dir.

<code>
cmake -DCMAKE_DATA_PATH=/usr/local/share ../trunk
</code>

In this example the data-dir will be located at ''/usr/local/share/holdingnuts/data''.

**Note:** There are already several search-paths compiled in. Usually this option isn't needed. If the ''CMAKE_DATA_PATH'' is specified then this is the only path the data-dir is searched.

==== SVN revision included in build ====
The option ''USE_SVNREV'' (Default: Off) activates inclusion of a SVN revision string in the build.

<code>
cmake -DUSE_SVNREV=On ../trunk
</code>

**Note:** Each time the revision increases, the whole sources are re-built. This is because the SVN revision-string is provided as a definition (CPP macro; #define). Only enable this option if you plan to give away a specific revision for testing purpose.
==== Source documentation ====

Doxygen generated source documentation can be built with:
<code>
cd build
cmake -DBUILD_DOCUMENTATION=On ../trunk
make documentation
</code>

The doxygen output can be found in ''build/doxygen/doc''.


==== Installation ====

<code>
cmake -DCMAKE_INSTALL_PREFIX=/usr ../trunk
make install
</code>

<code>
cmake -DCMAKE_INSTALL_PREFIX=/usr/games -CMAKE_DATA_PATH=/usr/share/games ../trunk
make install
</code>

===== Config- and Log-files =====
The client as well as the server creates an application-settings directory.

On UN*X it's ''~/.holdingnuts/'', on Windows it's ''%APPDATA%\HoldingNuts\''.

  * client.cfg - Client configuration file
  * client.log - Client log file (includes all messages from ''log_msg()'')
  * client.debug - //Windows only//, includes all messages to stderr (''dbg_msg()'')
  * server.cfg - Server configuration file
  * server.log - Server log file (includes all messages from ''log_msg()'')

===== Pitfalls =====
  * older CMake's FindQt4 versions do not provide moc-qt4 with preprocessor definitions