path: root/doc/reference/modules/qt-modules.qdoc

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \contentspage index.html
    \page qt-modules.html
    \ingroup list-of-modules

    \title Qt Modules
    \brief Provide Qt support.

    The \c{Qt.*} modules contain properties and rules for Qt.

    \section1 Creating Dependencies to Qt Modules

    The Qt modules are special in that they are submodules within the \c Qt "namespace", which
    has ramifications on the syntax when expressing dependencies. Assume your product depends
    on the \c core and \c network modules. Then you could write:
    \code
    Depends { name: "Qt.core" }
    Depends { name: "Qt.network" }
    \endcode
    Or, alternatively:
    \code
    Depends { name: "Qt"; submodules: ["core", "network" } }
    \endcode

    \section1 List of Submodules

    \table
    \header
        \li Submodule Name
        \li Qt Module Name
        \li Notes
    \row
        \li axcontainer
        \li QAxContainer
        \li This module is only available on Windows.
    \row
        \li axserver
        \li QAxServer
        \li This module is only available on Windows.
    \row
        \li concurrent
        \li Qt Concurrent
        \li
    \row
        \li core
        \li Qt Core
        \li All other \c Qt modules have a dependency to this one, so you do not
            need to list it in your dependencies if you depend on at least one
            other \c Qt module.

            For more information on the properties you can specify, see
            \l{core Properties}.

            For more information on the relevant file tags, see
            \l {core File Tags}.
    \row
        \li dbus
        \li Qt D-Bus
        \li For more information on the properties you can specify, see
            \l{dbus Properties}.

            For more information on the relevant file tags, see
            \l {dbus File Tags}.
    \row
        \li declarative
        \li Qt Quick 1
        \li Provides the \c{Qt Quick 1} module. For more information, see
            \l{declarative Properties}.
    \row
        \li designer
        \li Qt Designer
        \li
    \row
        \li enginio
        \li Qt Enginio
        \li
    \row
        \li gui
        \li Qt GUI
        \li For more information on the properties you can specify,
            see \l {gui Properties}.

            For more information on the relevant file tags, see
            \l {gui File Tags}.
    \row
        \li help
        \li Qt Help
        \li You do not need this module for building \c qdoc documentation,
            because that functionality is part of the \c core module. This
            module is for using Qt classes such as \c QHelpEngine.
    \row
        \li multimedia
        \li Qt Multimedia
        \li
    \row
        \li multimediawidgets
        \li Qt Multimedia Widgets
        \li
    \row
        \li network
        \li Qt Network
        \li
    \row
        \li opengl
        \li Qt OpenGL
        \li
    \row
        \li phonon
        \li Phonon (Qt 4 only)
        \li
    \row
        \li printsupport
        \li Qt Print Support
        \li
    \row
        \li quick
        \li Qt Quick (2)
        \li Provides the \c{Qt Quick} module (Qt Quick 2). For more information,
            see \l {quick Properties}.
    \row
        \li qml
        \li Qt QML
        \li
    \row
        \li script
        \li Qt Script
        \li
    \row
        \li scxml
        \li Qt Scxml
        \li For more information on the properties you can specify, see
            \l{scxml Properties}.

            For more information on the relevant file tags, see
            \l {scxml File Tags}.
    \row
        \li sql
        \li Qt SQL
        \li
    \row
        \li svg
        \li Qt SVG
        \li
    \row
        \li testlib
        \li Qt Test
        \li
    \row
        \li webkit
        \li Qt WebKit
        \li
    \row
        \li webkitwidgets
        \li Qt WebKit Widgets
        \li
    \row
        \li widgets
        \li Qt Widgets
        \li
    \row
        \li xml
        \li Qt XML
        \li You do not need this module for the \c QXmlStreamReader and
            \c QXmlStreamWriter classes, because those classes are a part of the
            \c core module. This module provides the deprecated DOM and SAX
            classes.
    \row
        \li xmlpatterns
        \li Qt XML Patterns
        \li
        \li
    \endtable

    \section1 Module Properties

    The following sections describe the properties of Qt modules that can be
    interesting to users.

    \section2 core Properties

    Some of the following properties only need to be defined if the respective installation
    of Qt was built in some unusual way, for instance by setting non-default \c configure flags.

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li availableBuildVariants
        \li \c{stringList}
        \li set by \c{qbs-setup-qt}
        \li The build variants that this Qt installation offers.
    \row
        \li binPath
        \li \c{path}
        \li \c{undefined}
        \li The path in which Qt tools such as \c qmake, \c moc and so on are located.
    \row
        \li config
        \li \c{stringList}
        \li \c{empty}
        \li Corresponds to the default value of qmake's \c CONFIG variable.
    \row
        \li docPath
        \li \c{path}
        \li \c{undefined}
        \li The path in which the Qt documentation is located.
    \row
        \li frameworkBuild
        \li \c{bool}
        \li \c{undefined}
        \li Specifies whether Qt was built as a framework. This is only relevant for Darwin systems.
    \row
        \li incPath
        \li \c{path}
        \li \c{undefined}
        \li The base path of the Qt headers.
    \row
        \li libInfix
        \li \c{string}
        \li \c{empty}
        \li The library infix can be set at Qt build time to change the name of Qt's libraries.
            For instance, if the infix is "Test", then on Unix systems, the \c{Qt Core} library will
            be in a file called \c{libQt5CoreTest.so} instead of the default \c{libQt5Core.so}.
    \row
        \li libPath
        \li \c{path}
        \li \c{undefined}
        \li The path in which the Qt libraries are located.
    \row
        \li lreleaseMultiplexMode
        \li \c{bool}
        \li \c{false}
        \li If this property is \c true, \c lrelease will merge all ts files into one qm file.
            Otherwise, one qm file will be created for every ts file.
    \row
        \li lreleaseName
        \li \c{string}
        \li \c{"lrelease"}
        \li The base name of the \c lrelease tool. Set this if your system uses a name such as "lrelease-qt4".
    \row
        \li mkspecPath
        \li \c{path}
        \li \c{undefined}
        \li The path in which the Qt mkspecs are located.
    \row
        \li mocFlags
        \li \c{stringList}
        \li empty
        \li Additional flags to \c moc. You will rarely need to set this property.
    \row
        \li mocName
        \li \c{string}
        \li \c{"moc"}
        \li The base name of the \c moc tool. Set this if your system uses a name such as "moc-qt4".
    \row
        \li namespace
        \li \c{string}
        \li \c{undefined}
        \li The Qt namespace that can be set at build time via the \c configure script. By default,
            Qt is not built in a namespace.
    \row
        \li pluginMetaData
        \li \c{stringList}
        \li empty
        \li Additional plugin meta data. The elements of the list are key-value pairs separated
            by the \c = character. A possible use case is to set the plugin URI when building
            a static QML plugin:
            \code
            Qt.core.pluginMetaData: ["uri=thePlugin"]
            \endcode
    \row
        \li pluginPath
        \li \c{path}
        \li \c{undefined}
        \li The path in which the Qt plugins are located.
    \row
        \li qdocEnvironment
        \li \c{stringlist}
        \li \c{undefined}
        \li The environment for calls to \c qdoc. Typically, you will need to set some variables
            here when running \c qdoc to build your project documentation.
    \row
        \li qdocName
        \li \c{string}
        \li \c{"qdoc3"} for Qt 4, \c{"qdoc"} otherwise
        \li The base name of the \c qdoc tool.
    \row
        \li qmBaseName
        \li \c{string}
        \li \c{product.targetName}
        \li The base name of the qm file to be built from the ts files in the product.
            This property is ignored if \c lreleaseMultiplexMode is \c false.
    \row
        \li qtBuildVariant
        \li \c{string}
        \li See below.
        \li Specifies the type of Qt libraries to build against: "debug" or "release".
            The default value is the build variant of the code linking against Qt. If Qt does not
            offer that build variant, the build variant offered by Qt is chosen instead.
            \note On some systems, it is not possible to link code built in debug mode against
            libraries built in release mode and vice versa.
    \row
        \li qtConfig
        \li \c{stringList}
        \li \c{empty}
        \li Corresponds to the default value of qmake's \c QT_CONFIG variable.
    \row
        \li resourceSourceBase
        \li \c{path}
        \li \c{product.sourceDirectory}
        \li For files tagged as \c{qt.core.resource_data}, this property determines which part of
            their path will end up in the generated \c qrc file.
    \row
        \li resourcePrefix
        \li \c{string}
        \li \c{"/"}
        \li For files tagged as \c{qt.core.resource_data}, this property determines the prefix
            under which they will be available in the generated \c qrc file. The value of this
            property needs to be the same for all such files in a product.
    \row
        \li staticBuild
        \li \c{bool}
        \li \c{undefined}
        \li Specifies whether Qt was built statically.
    \row
        \li version
        \li \c{string}
        \li \c{undefined}
        \li The Qt version. Consists of three numbers separated by dots, for instance "5.1.1".
    \row
        \li versionMajor
        \li \c{int}
        \li \c{versionParts[0]}
        \li The Qt major version.
    \row
        \li versionMinor
        \li \c{int}
        \li \c{versionParts[1]}
        \li The Qt minor version.
    \row
        \li versionParts
        \li \c{list}
        \li \c{empty}
        \li The Qt version as a list. For instance, Qt version 5.1.1 would correspond to a value of
            \c[5, 1, 1].
    \row
        \li versionPatch
        \li \c{int}
        \li \c{versionParts[2]}
        \li The Qt patch level.
    \endtable

    \section2 dbus Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li xml2cppName
        \li \c{string}
        \li \c{"qdbusxml2cpp"}
        \li The base name of the \c qdbusxml2cpp tool. Set this if your system uses a different name.
    \row
        \li xml2CppHeaderFlags
        \li \c{stringList}
        \li empty list
        \li Additional flags when running the \c qdbusxml2cpp tool to create header files.
    \row
        \li xml2CppSourceFlags
        \li \c{stringList}
        \li empty list
        \li Additional flags when running the \c qdbusxml2cpp tool to create source files.
    \endtable

    \section2 declarative Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li qmlDebugging
        \li \c{bool}
        \li \c{false}
        \li Specifies whether QML debugging support should be compiled into your binaries.
    \row
        \li qmlImportsPath
        \li \c{string}
        \li set by \c{qbs-setup-qt}
        \li The absolute path to the directory where Qt's QML imports are installed.
    \row
        \li qmlPath
        \li \c{string}
        \li set by \c{qbs-setup-qt}
        \li The absolute path to the directory where Qt's QML files are installed.
            This property is undefined for Qt4.
    \endtable

    \section2 gui Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li uicName
        \li \c{string}
        \li \c{"uic"}
        \li The base name of the \c uic tool. Set this if your system uses a name such as "uic-qt4".
    \endtable

    \section2 quick Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li qmlDebugging
        \li \c{bool}
        \li \c{false}
        \li Specifies whether QML debugging support should be compiled into your binaries.
    \row
        \li qmlImportsPath
        \li \c{string}
        \li set by \c{qbs-setup-qt}
        \li The absolute path to the directory where Qt's QML imports are installed.
    \row
        \li qmlPath
        \li \c{string}
        \li set by \c{qbs-setup-qt}
        \li The absolute path to the directory where Qt's QML files are installed.
            This property is undefined for Qt4.

    \endtable

    \section2 scxml Properties

    \table
    \header
        \li Property
        \li Type
        \li Default
        \li Description
    \row
        \li className
        \li \c{string}
        \li \c undefined
        \li The class name of the generated state machine. By default, the compiler will use the
            \c name attribute of the input file's \c{<scxml>} tag.
    \row
        \li namespace
        \li \c{string}
        \li \c undefined
        \li The C++ namespace in which to put the generated class. By default, the compiler will
            place the class in the global namespace.
    \row
        \li qscxmlcName
        \li \c{string}
        \li \c{"qscxmlc"}
        \li The base name of the Qt SCXML compiler. Set this if your system uses a different name.
    \endtable

    \section1 Relevant File Tags

    The following sections describe the file tags that are relevant for the Qt
    modules.

    \section2 core File Tags

    \table
    \header
        \li Tag
        \li Auto-tagged File Names
        \li Since
        \li Description
    \row
        \li \c{"qch"}
        \li n/a
        \li 1.1
        \li This tag is attached to the output artifacts of the rule that runs the
            \c qhelpgenerator tool.
    \row
        \li \c{"qdoc"}
        \li \c{*.qdoc}
        \li 1.1
        \li Source files with this tag trigger a re-execution of the rule running the \c qdoc
            tool when their timestamp changes.
    \row
        \li \c{"qdocconf"}
        \li \c{*.qdocconf}
        \li 1.1
        \li Source files with this tag trigger a re-execution of the rule running the \c qdoc
            tool when their timestamp changes.
    \row
        \li \c{"qdocconf-main"}
        \li -
        \li 1.1
        \li Source files with this tag serve as inputs to the rule running the \c qdoc tool.
    \row
        \li \c{"qdoc-output"}
        \li n/a
        \li 1.5
        \li Use this tag to match all \c qdoc outputs, for instance in a \l{Group Item}{Group}
            using the \c fileTagsFilter property.
    \row
        \li \c{"qhp"}
        \li \c{*.qhp}
        \li 1.1
        \li Files with this tag serve as inputs to the rule running the \c qhelpgenerator tool.
            Such files are created by \c qdoc, but can also appear as source files.
    \row
        \li \c{"qm"}
        \li n/a
        \li 1.1
        \li This tag is attached to the output artifacts of the rule that runs the \c lrelease tool.
    \row
        \li \c{"qrc"}
        \li \c{*.qrc}
        \li 1.0
        \li Files with this tag serve as inputs to the rule running the \c rcc tool.
    \row
        \li \c{"qt_plugin_metadata"}
        \li -
        \li 1.0
        \li Source files with this tag trigger a re-execution of the rule running the \c moc
            tool when their timestamp changes.
    \row
        \li \c{"qt.core.resource_data"}
        \li -
        \li 1.7
        \li Source files with this tag serve as inputs to the rule creating \c qrc files.
    \row
        \li \c{"ts"}
        \li \c{*.ts}
        \li 1.0
        \li Files with this tag serve as inputs to the rule running the \c lrelease tool.
    \endtable

    \section2 dbus File Tags

    \table
    \header
        \li Tag
        \li Auto-tagged File Names
        \li Since
        \li Description
    \row
        \li \c{"qt.dbus.adaptor"}
        \li -
        \li 1.5
        \li Source files with this tag serve as inputs to the rule running the \c qdbusxml2cpp tool,
            which will create an adaptor class.
    \row
        \li \c{"qt.dbus.interface"}
        \li -
        \li 1.5
        \li Source files with this tag serve as inputs to the rule running the \c qdbusxml2cpp tool,
            which will create an interface class.
    \endtable

    \section2 gui File Tags

    \table
    \header
        \li Tag
        \li Auto-tagged File Names
        \li Since
        \li Description
    \row
        \li \c{"ui"}
        \li \c{*.ui}
        \li 1.0
        \li Source files with this tag serve as inputs to the rule running the \c uic tool.
    \endtable

    \section2 scxml File Tags

    \table
    \header
        \li Tag
        \li Auto-tagged File Names
        \li Since
        \li Description
    \row
        \li \c{"qt.scxml.compilable"}
        \li -
        \li 1.7
        \li Source files with this tag serve as inputs to the rule running the Qt SCXML compiler,
            which will create a C++ class representing a state machine.
    \endtable

*/