From 2739a6f97e843240890e38d68505f5595bba4470 Mon Sep 17 00:00:00 2001 From: Stephen Kelly Date: Sun, 2 Feb 2014 11:09:49 +0100 Subject: Help: Move Qt tool invocation information to a generic cmake-qt manual. Add an introduction about the use of different package types, and the ability to use Qt 4 and 5 versions together in a single buildsystem. Add a section about automatic linking of the qtmain.lib library and how to disable it. --- Help/index.rst | 1 + Help/manual/cmake-qt.7.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++ Modules/FindQt4.cmake | 73 +---------------------- 3 files changed, 142 insertions(+), 72 deletions(-) create mode 100644 Help/manual/cmake-qt.7.rst diff --git a/Help/index.rst b/Help/index.rst index 551db75..7fce223 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -35,6 +35,7 @@ Reference Manuals /manual/cmake-packages.7 /manual/cmake-policies.7 /manual/cmake-properties.7 + /manual/cmake-qt.7 /manual/cmake-toolchains.7 /manual/cmake-variables.7 diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst new file mode 100644 index 0000000..a318afb --- /dev/null +++ b/Help/manual/cmake-qt.7.rst @@ -0,0 +1,140 @@ +.. cmake-manual-description: CMake Qt Features Reference + +cmake-qt(7) +*********** + +.. only:: html or latex + + .. contents:: + +Introduction +============ + +CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found +by the :module:`FindQt4` find-module shipped with CMake, whereas the +Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See +:manual:`cmake-packages(7)` for more information about CMake packages, and +see `the Qt cmake manual `_ +for your Qt version. + +Qt 4 and Qt 5 may be used together in the same +:manual:`CMake buildsystem `: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR) + + project(Qt4And5) + + set(CMAKE_AUTOMOC ON) + set(CMAKE_INCLUDE_CURRENT_DIR ON) + + find_package(Qt5Widgets REQUIRED) + add_executable(publisher publisher.cpp) + target_link_libraries(publisher Qt5::Widgets Qt5::DBus) + + find_package(Qt4 REQUIRED) + add_executable(subscriber subscriber.cpp) + target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus) + +A CMake target may not link to both Qt 4 and Qt 5. A diagnostic is issued if +this is attempted or results from transitive target dependency evaluation. + +Qt Build Tools +============== + +Qt relies on some bundled tools for code generation, such as ``moc`` for +meta-object code generation, ``uic`` for widget layout and population, +and ``rcc`` for virtual filesystem content generation. These tools may be +automatically invoked by :manual:`cmake(1)` if the appropriate conditions +are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. + +The tools are executed as part of a synthesized custom target generated by +CMake. Target dependencies may be added to that custom target by adding them +to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. + +AUTOMOC +''''''' + +The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)` +inspects the C++ files in the target to determine if they require ``moc`` to +be run, and to create rules to execute ``moc`` at the appropriate time. + +If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` +will be run on the file. The result will be put into a file named according +to ``moc_.cpp``. If the macro is found in a C++ implementation +file, the moc output will be put into a file named according to +``.moc``, following the Qt conventions. The ``moc file`` may be +included by the user in the C++ implementation file with a preprocessor +``#include``. If it is not so included, it will be added to a separate file +which is compiled into the target. + +Generated ``moc_*.cpp`` and ``*.moc`` files are placed in the build directory +so it is convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` +variable. The :prop_tgt:`AUTOMOC` target property may be pre-set for all +following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The +:prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set +options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` +variable may be populated to pre-set the options for all following targets. + +AUTOUIC +''''''' + +The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)` +inspects the C++ files in the target to determine if they require ``uic`` to +be run, and to create rules to execute ``uic`` at the appropriate time. + +If a preprocessor ``#include`` directive is found which matches +``ui_.h``, and a ``.ui`` file exists, then ``uic`` will +be executed to generate the appropriate file. + +Generated ``ui_*.h`` files are placed in the build directory so it is +convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable. The +:prop_tgt:`AUTOUIC` target property may be pre-set for all following targets +by setting the :variable:`CMAKE_AUTOUIC` variable. The +:prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options +to pass to ``uic``. The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be +populated to pre-set the options for all following targets. The +:prop_sf:`AUTOUIC_OPTIONS` source file property may be set on the +``.ui`` file to set particular options for the file. This +overrides options from the :prop_tgt:`AUTOUIC_OPTIONS` target property. + +AUTORCC +''''''' + +The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)` +creates rules to execute ``rcc`` at the appropriate time on source files +which have the suffix ``.qrc``. + +.. code-block:: cmake + + add_executable(myexe main.cpp resource_file.qrc) + +The :prop_tgt:`AUTORCC` target property may be pre-set for all following targets +by setting the :variable:`CMAKE_AUTORCC` variable. The +:prop_tgt:`AUTORCC_OPTIONS` target property may be populated to set options +to pass to ``rcc``. The :variable:`CMAKE_AUTORCC_OPTIONS` variable may be +populated to pre-set the options for all following targets. The +:prop_sf:`AUTORCC_OPTIONS` source file property may be set on the +``.qrc`` file to set particular options for the file. This +overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. + +qtmain.lib on Windows +===================== + +The Qt 4 and 5 :prop_tgt:`IMPORTED` targets for the QtGui libraries specify +that the qtmain.lib static library shipped with Qt will be linked by all +dependent executables which have the :prop_tgt:`WIN32_EXECUTABLE` enabled. + +Do disable this behavior, enable the ``Qt5_NO_LINK_QTMAIN`` target property for +Qt 5 based targets or ``QT4_NO_LINK_QTMAIN`` target property for Qt 4 based +targets. + +.. code-block:: cmake + + add_executable(myexe WIN32 main.cpp) + target_link_libraries(myexe Qt4::QtGui) + + add_executable(myexe_no_qtmain WIN32 main_no_qtmain.cpp) + set_property(TARGET main_no_qtmain PROPERTY QT4_NO_LINK_QTMAIN ON) + target_link_libraries(main_no_qtmain Qt4::QtGui) diff --git a/Modules/FindQt4.cmake b/Modules/FindQt4.cmake index 2d2feae..21a853d 100644 --- a/Modules/FindQt4.cmake +++ b/Modules/FindQt4.cmake @@ -35,78 +35,7 @@ # meta-object code generation,``uic`` for widget layout and population, # and ``rcc`` for virtual filesystem content generation. These tools may be # automatically invoked by :manual:`cmake(1)` if the appropriate conditions -# are met. -# -# The tools are executed as part of a synthesized custom target generated by -# CMake. Target dependencies may be added to that custom target by adding them -# to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. -# -# AUTOMOC -# ''''''' -# -# The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)` -# inspects the C++ files in the target to determine if they require ``moc`` to -# be run, and to create rules to execute ``moc`` at the appropriate time. -# -# If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` -# will be run on the file. The result will be put into a file named according -# to ``moc_.cpp``. If the macro is found in a C++ implementation -# file, the moc output will be put into a file named according to -# ``.moc``, following the Qt conventions. The ``moc file`` may be -# included by the user in the C++ implementation file with a preprocessor -# ``#include``. If it is not so included, it will be added to a separate file -# which is compiled into the target. -# -# Generated ``moc_*.cpp`` and ``*.moc`` files are placed in the build directory -# so it is convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` -# variable. The :prop_tgt:`AUTOMOC` target property may be pre-set for all -# following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The -# :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set -# options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` -# variable may be populated to pre-set the options for all following targets. -# -# AUTOUIC -# ''''''' -# -# The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)` -# inspects the C++ files in the target to determine if they require ``uic`` to -# be run, and to create rules to execute ``uic`` at the appropriate time. -# -# If a preprocessor ``#include`` directive is found which matches -# ``ui_.h``, and a ``.ui`` file exists, then ``uic`` will -# be executed to generate the appropriate file. -# -# Generated ``ui_*.h`` files are placed in the build directory so it is -# convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable. The -# :prop_tgt:`AUTOUIC` target property may be pre-set for all following targets -# by setting the :variable:`CMAKE_AUTOUIC` variable. The -# :prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options -# to pass to ``uic``. The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be -# populated to pre-set the options for all following targets. The -# :prop_sf:`AUTOUIC_OPTIONS` source file property may be set on the -# ``.ui`` file to set particular options for the file. This -# overrides options from the :prop_tgt:`AUTOUIC_OPTIONS` target property. -# -# AUTORCC -# ''''''' -# -# The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)` -# creates rules to execute ``rcc`` at the appropriate time on source files -# which have the suffix ``.qrc``. -# -# .. code-block:: cmake -# -# add_executable(myexe main.cpp resource_file.qrc) -# -# The :prop_tgt:`AUTORCC` target property may be pre-set for all following targets -# by setting the :variable:`CMAKE_AUTORCC` variable. The -# :prop_tgt:`AUTORCC_OPTIONS` target property may be populated to set options -# to pass to ``rcc``. The :variable:`CMAKE_AUTORCC_OPTIONS` variable may be -# populated to pre-set the options for all following targets. The -# :prop_sf:`AUTORCC_OPTIONS` source file property may be set on the -# ``.qrc`` file to set particular options for the file. This -# overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. -# +# are met. See :manual:`cmake-qt(7)` for more. # # Qt Macros # ========= -- cgit v0.12