Commit 282fa97a authored by Brad King's avatar Brad King Committed by Kitware Robot

Merge topic 'autogen_documentation'

b55e5d66 Help: Autogen: Overhaul AUTOMOC target property documentation
fdab21f3 Help: Autogen: Overhaul AUTOUIC target property documentation
d08548c6 Help: Autogen: Overhaul AUTORCC target property documentation
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !3461
parents 3e1dac73 b55e5d66
Pipeline #139602 passed with stage
in 0 seconds
This diff is collapsed.
AUTORCC
-------
Should the target be processed with autorcc (for Qt projects).
Should the target be processed with auto-rcc (for Qt projects).
:prop_tgt:`AUTORCC` is a boolean specifying whether CMake will handle
the Qt ``rcc`` code generator automatically, i.e. without having to use
......@@ -13,34 +13,49 @@ as target sources at build time and invoke ``rcc`` accordingly.
This property is initialized by the value of the :variable:`CMAKE_AUTORCC`
variable if it is set when a target is created.
By default :prop_tgt:`AUTORCC` is processed inside a
By default :prop_tgt:`AUTORCC` is processed by a
:command:`custom command <add_custom_command>`.
If the ``.qrc`` file is :prop_sf:`GENERATED` though, a
If the ``.qrc`` file is :prop_sf:`GENERATED`, a
:command:`custom target <add_custom_target>` is used instead.
Additional command line options for rcc can be set via the
:prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file.
When there are multiple ``.qrc`` files with the same name, CMake will
generate unspecified unique output file names for ``rcc``. Therefore, if
``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used, the
``.qrc`` file name must be unique.
Modifiers
^^^^^^^^^
:prop_tgt:`AUTORCC_EXECUTABLE`:
The ``rcc`` executable will be detected automatically, but can be forced to
a certain binary using the :prop_tgt:`AUTORCC_EXECUTABLE` property.
a certain binary by setting this target property.
The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group
the autorcc targets together in an IDE, e.g. in MSVS.
:prop_sf:`AUTORCC_OPTIONS`:
Additional command line options for ``rcc`` can be set via this ``.qrc``
source file property.
The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group
files generated by :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS.
:prop_sf:`SKIP_AUTORCC`:
``.qrc`` files can be excluded from :prop_tgt:`AUTORCC` processing by
setting this source file property.
When there are multiple ``.qrc`` files with the same name, CMake will
generate unspecified unique names for ``rcc``. Therefore if
``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the
``.qrc`` file name must be unique.
: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.
:prop_gbl:`AUTOGEN_SOURCE_GROUP`:
This global property can be used to group files generated by
:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS.
Source files can be excluded from :prop_tgt:`AUTORCC` processing by
enabling :prop_sf:`SKIP_AUTORCC` 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.
:variable:`CMAKE_GLOBAL_AUTORCC_TARGET`:
A global ``autorcc`` target that depends on all :prop_tgt:`AUTORCC` targets
in the project can be generated by enabling
:variable:`CMAKE_GLOBAL_AUTORCC_TARGET`.
in the project will be generated when this variable is ``ON``.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.
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() <FindQt4>` 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
``<AUTOGEN_BUILD_DIR>/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 <GENERATOR_IS_MULTI_CONFIG>`,
the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``.
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_<ui_base>.h"
Once such an include statement is found in a file, CMake searches for the
``uic`` input file ``<ui_base>.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_base>.ui`` file was found, ``uic`` is called on it to generate
``ui_<ui_base>.h`` in the directory
- ``<AUTOGEN_BUILD_DIR>/include`` for single configuration generators or in
- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` for
:prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators.
Where ``<AUTOGEN_BUILD_DIR>`` 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 ``<base_name>.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 ``<ORIGIN>_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
``<ORIGIN>_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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment