From fdab21f30b48021a6ecad2307b092b4d55561ae9 Mon Sep 17 00:00:00 2001 From: Sebastian Holtermann Date: Mon, 17 Jun 2019 13:44:28 +0200 Subject: Help: Autogen: Overhaul AUTOUIC target property documentation --- Help/prop_tgt/AUTOUIC.rst | 87 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 26 deletions(-) diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 85226c15f0..5cf87552ce 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -1,47 +1,82 @@ AUTOUIC ------- -Should the target be processed with autouic (for Qt projects). +Should the target be processed with auto-uic (for Qt projects). :prop_tgt:`AUTOUIC` is a boolean specifying whether CMake will handle the Qt ``uic`` code generator automatically, i.e. without having to use the :module:`QT4_WRAP_UI() ` or ``QT5_WRAP_UI()`` macro. Currently Qt4 and Qt5 are supported. -When this property is ``ON``, CMake will scan the source files at build time -and invoke ``uic`` accordingly. If an ``#include`` statement like -``#include "ui_foo.h"`` is found in ``source.cpp``, a ``foo.ui`` file is -searched for first in the vicinity of ``source.cpp`` and afterwards in the -optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. -``uic`` is run on the ``foo.ui`` file to generate ``ui_foo.h`` in the directory -``/include``, -which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` +variable if it is set when a target is created. -* For :prop_gbl:`multi configuration generators `, - the include directory is ``/include_``. +When this property is ``ON``, CMake will scan the header and source files at +build time and invoke ``uic`` accordingly. -* See :prop_tgt:`AUTOGEN_BUILD_DIR`. -This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` -variable if it is set when a target is created. +Header and source file processing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +At build time, CMake scans each header and source file from the +target's sources for include statements of the form + +.. code-block:: c++ + + #include "ui_.h" + +Once such an include statement is found in a file, CMake searches for the +``uic`` input file ``.ui`` + +- in the vicinity of the file and +- in the :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. -Additional command line options for ``uic`` can be set via the -:prop_sf:`AUTOUIC_OPTIONS` source file property on the ``foo.ui`` file. -The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the -autouic targets together in an IDE, e.g. in MSVS. +If the ``.ui`` file was found, ``uic`` is called on it to generate +``ui_.h`` in the directory +- ``/include`` for single configuration generators or in +- ``/include_`` for + :prop_gbl:`multi configuration ` generators. + +Where ```` is the value of the target property +:prop_tgt:`AUTOGEN_BUILD_DIR`. + +The include directory is automatically added to the target's +:prop_tgt:`INCLUDE_DIRECTORIES`. + + +Modifiers +^^^^^^^^^ + +:prop_tgt:`AUTOUIC_EXECUTABLE`: The ``uic`` executable will be detected automatically, but can be forced to -a certain binary using the :prop_tgt:`AUTOUIC_EXECUTABLE` property. +a certain binary using this target property. + +:prop_sf:`AUTOUIC_OPTIONS`: Additional command line options for ``uic`` can +be set via this source file property on a ``.ui`` file. + +:prop_sf:`SKIP_AUTOUIC`: +Source files can be excluded from :prop_tgt:`AUTOUIC` processing by setting +this source file property. + +:prop_sf:`SKIP_AUTOGEN`: +Source files can be excluded from :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by +setting this source file property. -Source files can be excluded from :prop_tgt:`AUTOUIC` processing by -enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. +:prop_gbl:`AUTOGEN_TARGETS_FOLDER`: +This global property can be used to group :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, +e.g. in MSVS. -The number of parallel ``uic`` processes to start can be modified by -setting :prop_tgt:`AUTOGEN_PARALLEL`. +:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: +A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or +:prop_tgt:`AUTOUIC` generated ``_autogen`` targets in the project, +will be generated when this variable is ``ON``. -A global ``autogen`` target that depends on all :prop_tgt:`AUTOUIC` generated -``_autogen`` targets in the project can be generated by enabling -:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`. +:prop_tgt:`AUTOGEN_PARALLEL`: +This target property controls the number of ``moc`` or ``uic`` processes to +start in parallel during builds. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. -- cgit v1.2.1