View source for Qt In Namespace

[[Category:Developing_Qt::Guidelines]]

The Qt-in-Namespace feature serves as a tool to handle certain scenarios involving multiple configurations of Qt more gracefully. E.g. before Qt-in-Namespace a Qt 3 based application in Linux would immediately segfault as soon as it tries to dlopen() a shared object that is linked to Qt 4. With the Qt in namespace feature not only can the crash be prevented, but under certain circumstances this combination might actually "work".

The core of the feature's implementation consists of wrapping "all of Qt code" into a pair of macros <tt>QT_BEGIN_NAMESPACE</tt> and <tt>QT_END_NAMESPACE</tt>. Both macros usually expand to nothing, but they expand to <tt>namespace xxx {</tt> and <tt>}</tt>, respectively, when Qt is configured with the option <tt>-qtnamespace xxx</tt>. The macros are defined in <tt><qglobal.h></tt>

The feature is part of Qt since Qt 4.4. Keeping the feature in a working state is, unfortunately, a bit tedious and influences code that gets integrated into Qt.

To help with this, all contributors to the Qt source code are kindly asked to follow the set of rules given below.

=== Rules for ''namespaced'' code: ===

This concerns code in <tt>main/src/{corelib,gui,…}</tt> and in <tt>main/tools/designer</tt> but not in <tt>main/src/3rdparty</tt>. As a rule of thumb: If it contributes to one of "the Qt" libraries that end up in <tt>lib/*</tt> ''and'' if it is "Qt" code, it is "namespaced code".

# All occurrences of <tt>QT_BEGIN_NAMESPACE</tt> and <tt>QT_END_NAMESPACE</tt> must be balanced with respect to <tt>#if/#ifdef</tt> etc. preprocessor directives. Most notably this applies to all <tt>QT_NO_<FEATURE></tt> branches.
# All code that is not a preprocessor directive or a comment must be wrapped in <tt>QT_BEGIN_NAMESPACE</tt> and <tt>QT_END_NAMESPACE</tt>. As a rule of thumb this applies do all definitions and declarations concerning types, objects etc with identifiers starting with 'q' or 'Q'.
# All <tt>#include</tt> lines go outside the <tt>QT_BEGIN_NAMESPACE … QT_END_NAMESPACE</tt>. 
# Forward declarations of items in non-namespaced code go outside.
# As a special exception <tt>QT_DECLARE_METATYPE</tt> lines go ''outside''.
# <tt>Q_INIT_RESOURCE</tt> inside. However, the Makefile dependencies are inadequate, so make sure to remove all qrc_*.cpp files manually if you have troubles when "namespacing" old code.
# Since not all compilers we support adhere to The Standard we cannot declare external functions locally within other functions. As a workaround, declare the external function on namespace scope.

=== Rules for ''namespace aware'' code: ===

This concerns everything in <tt>main/*</tt> that is not "namespaced code" and any end user code that wishes to use the Qt-in-Namespace feature:

<ol>
<li>All forward declarations of types, functions and objects that are in "namespaced code" must be namespaced and their use must be "namespace qualified", i.e. written as

<code>
QT_BEGIN_NAMESPACE
class QCheckBox;
class QComboBox;
QT_END_NAMESPACE
</code>

This is admittedly ugly but needed. A simple <tt>using namespace QT_NAMESPACE</tt> unfortunately does not help as

<code>
namespace QT_NAMESPACE { … }
using namespace QT_NAMESPACE;
class QString;
</code>

will declare QString at global namespace which will be distinct from our <tt>QT_NAMESPACE::QString</tt> and cause compiler or linker errors later.
</li>

<li>A <tt>QT_BEGIN_NAMESPACE</tt> and <tt>QT_END_NAMESPACE</tt> wrapper is also needed when extending a namespace that itself lives in namespaced code. This situation typically appears when extending the QtTest namespace in auto tests.
</li>
</ol>

Making code ''namespace aware'' can be given a headstart by running

<code>
find . -name '*.cpp' -o -name '*.h' -exec perl -pie 's:^class Q (.*);:QT_ADD_NAMESPACE_PREFIX($1);: {} 
</code>

but it looks a bit cleaner if only <tt>QT_BEGIN_NAMESPACE</tt> and <tt>QT_END_NAMESPACE</tt> are used.

=== Rules for other code: ===

Everything else including end user code that does not need the feature and end user code that is not even aware of Qt at all does not need to be changed.

=== Related: ===

The [[Qt Creator]] Debugger can handle namespaced code as if it were "native" Qt.