config_notes.txt

Project Configuration Notes (win-ia32)
--------------------------------------

Following notes documents non-obvious tricks used in the project configuration.

1) Preprocessor Definitions
BOOS_ALL_NO_LIB
    Disable Boost auto-linking feature. That means all required Boost libraries
    must be passed to the linker manually.
BOOST_THREAD_USE_LIB
    By default, Boost assumes the thread library will be linked dynamically.
    That is, even if the linker is given static library, the symbols cannot be
    resolved. This definition orders Boost to expect static linking of thread
    library.
RCF_*
    All RCF definitions must correspond to those which the RCF library was
    actually compiled with. Otherwise, wrong parts of RCF headers would be
    included to the project code.
TBB_USE_DEBUG=0
    Should be defined automatically by tbb/tbb_config.h. However, because
    TBB uses internally _DEBUG macro which is in conflict with some other
    project dependency, TBB_USE_DEBUG is incorrectly defined as empty and
    causes compilation errors.
WIN32_LEAN_AND_MEAN
    Some RCF headers includes Win32 API headers. Therefore, if RCF library was
    compiled with the minimalistic "lean and mean" version of Win32 API, it
    must be defined also in the project.
WINVER=0x0501
_WIN32_WINNT=0x0501
    Both definitions belong to Win32 API. WINVER is required by RCF headers,
    _WIN32_WINNT is required by Boost headers. The defined value correspond to
    Windows XP, which is the best tradeoff between backwards-compatibility of
    resulting binaries and enabled Win32 API features.
NOT_NETBEANS
    This definition is part of NetBeans hack (see sources for further
    explanation). It is only important to note here, that the definition must
    be invisible to NetBeans code parser, but visible to g++ compiler. Such
    behaviour can be achieved by not adding it directly to Preprocessor
    Definitions in project configuration, but rather into Additional Options in
    backend and Qt - Custom Definitions in frontend.

2) Compiler Warning Flags
-Wno-deprecated
-Wno-write-strings
-Wno-attributes
-Wno-strict-aliasing
    Removes various compilation warnings caused by headers of dependencies. It
    is usually caused by the fact that the dependency was tested on some older
    version of compiler. All hidden warnings were investigated and considered
    non-critical. However, it may change if some dependency or toolchain would
    be upgraded (e.g. deprecated features would be really removed from newer
    version of g++).

3) Frontend Debugging Console
In order to allow developer to use console debug printouts even when developing
widget application, it is sufficient to add "CONFIG += console" to Custom
Definitions. This can be removed for the release version of the project.

4) Frontend Debug Binary
Technically, it is not necessary to have debug versions of libraries to actually
build debug version of project binaries. The problem is, that NetBeans
configuration dialog for Qt applications does not expect such situation - the
Build Mode option is common for both libraries and resulting binary. If it is
set to Release, the linker is automatically ordered to strip debugging symbols
from the resulting binary - there is no workaround for this. On the other hand,
if it is set to Debug, linker is automatically ordered to link against Qt debug
libraries. Fortunately, there is a workaround for that - it is necessary to:
    a) deselect all Qt Modules
        This causes that NetBeans will not pass any Qt libraries automatically
        to the linker.
    b) add "QT -= core gui" to Custom Definitions
        This causes that qmake will not pass any Qt libraries automatically
        to the linker. Only core and gui are enabled by default, other libraries
        are disabled by default so they don't have to be considered.
    c) add "QMAKE_CXXFLAGS += -DQT_NO_DEBUG" to Custom Definitions
        This causes Qt headers to expect to be linked against release versions
        of Qt libraries. Notice it is done at compiler level (after hiding this
        information from both NetBeans and qmake).
    d) add "QMAKE_CXXFLAGS += -DQT_GUI_LIB -DQT_CORE_LIB" to Custom Definitions
        This simulates addition of required Qt libraries at compiler level
        (instead of checking Qt Modules in NetBeans, or passing
        "QT += core gui" to the qmake). More Qt libraries might need to be
        added (e.g. -DQT_NETWORK_LIB).

4) Library Linking
Because GNU linker is one-pass linker, all libraries must be passed on command
line in the correct order - i.e. all external symbols used by any particular
library or object file must be resolvable later (more on the right) on the
command line. To determine this order, it is necessary to build all dependencies
as dynamically linked libraries and inspect the dependency hierarchy by programs
like Dependency Walker (http://www.dependencywalker.com/).

5) Runtime Environment
In order to run or debug project binaries, environment variable "Path" must
contain paths to all dynamically linked dependencies that are not inside
C:\Windows\system32. Since most of the project dependencies are linked
statically, this applies only for TBB libraries, compiler runtime (libgcc) and
standard C++ library (libstdc++).

6) Console Type
During testing, NetBeans internal console caused some problems (invisible
output, incorrectly formatted output, incorrect program termination). Therefore,
External Terminal is explicitly selected in the project configuration to avoid
these problems.

7) Build and Run
If Run - Build First is checked in the configuration, NetBeans always run make
before executing the binary. Even if there are no changes to the source code,
make takes about 5-10 seconds to check all targets for changes. Because the
developer usually either build several times while correcting bugs and then run
only once, or run several times without making any changes (e.g. repeatedly
running backend while doing changes to the frontend), such behaviour is
redundant and annoying in most of the scenarios. Therefore, it is disabled.