1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: improve SUBDIRS documentation for dependency handling

Browse Source 
The use of the 'ordered' CONFIG option is known to not be efficient for
multi-core builds. This patch updates the documentation with an example
using the .depends modifier as well a discourage the use of 'ordered'.

Change-Id: I3575243a7c4138f0671d171441c932c3ad89a411
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>
This commit is contained in:
Samuel Gaist 2020-01-09 08:36:20 +01:00
parent 99b3966319
commit 44fd33e05c
2 changed files with 26 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
qmake/doc/snippets/code/doc_src_qmake-manual.pro
View File

@ -303,7 +303,9 @@ SUBDIRS = kernel \
#! [51] #! [51]
CONFIG += ordered SUBDIRS += my_executable my_library tests doc
my_executable.depends = my_library
tests.depends = my_executable
#! [51] #! [51]

30
qmake/doc/src/qmake-manual.qdoc
View File

@ -936,7 +936,9 @@
file. file.
\row \li ordered \li When using the \c subdirs template, this option \row \li ordered \li When using the \c subdirs template, this option
specifies that the directories listed should be processed in the specifies that the directories listed should be processed in the
order in which they are given. order in which they are given. \note The use of this option is discouraged.
Specify dependencies as described in the \l{#SUBDIRS}{SUBDIRS}
variable documentation.
\row \li precompile_header \li Enables support for the use of \row \li precompile_header \li Enables support for the use of
\l{Using Precompiled Headers}{precompiled headers} in projects. \l{Using Precompiled Headers}{precompiled headers} in projects.
\row \li precompile_header_c (MSVC only) \li Enables support for the use of \row \li precompile_header_c (MSVC only) \li Enables support for the use of
@ -2730,21 +2732,35 @@
\snippet code/doc_src_qmake-manual.pro 50 \snippet code/doc_src_qmake-manual.pro 50
If you need to ensure that the subdirectories are built in the order in If you need to ensure that the subdirectories are built in a particular
which they are specified, update the \l{#CONFIG}{CONFIG} variable to order, use the \c .depends modifier on the relevant \c SUBDIRS elements.
include the \c ordered option:
For example:
\snippet code/doc_src_qmake-manual.pro 51 \snippet code/doc_src_qmake-manual.pro 51
It is possible to modify this default behavior of \c SUBDIRS by giving The configuration above ensures that \c{my_library} is built before
additional modifiers to \c SUBDIRS elements. Supported modifiers are: \c{my_executable} and that \c{my_executable} is built before \c{tests}.
However, \c{doc} can be built in parallel with the other subdirectories,
thus speeding up the build process.
\note Multiple dependencies can be listed and they will all be built before
the target that depends on them.
\note Using \l{#CONFIG}{CONFIG += ordered} is discouraged as it can slow down
multi-core builds. Unlike the example shown above, all builds will happen
sequentially even if they don't have dependencies.
Beside defining the build order, it is possible to modify the default behavior
of \c SUBDIRS by giving additional modifiers to \c SUBDIRS elements.
Supported modifiers are:
\table \table
\header \li Modifier \li Effect \header \li Modifier \li Effect
\row \li .subdir \li Use the specified subdirectory instead of \c SUBDIRS value. \row \li .subdir \li Use the specified subdirectory instead of \c SUBDIRS value.
\row \li .file \li Specify the subproject \c pro file explicitly. Cannot be \row \li .file \li Specify the subproject \c pro file explicitly. Cannot be
used in conjunction with \c .subdir modifier. used in conjunction with \c .subdir modifier.
\row \li .depends \li This subproject depends on specified subproject. \row \li .depends \li This subproject depends on specified subproject(s).
\row \li .makefile \li The makefile of subproject. \row \li .makefile \li The makefile of subproject.
Available only on platforms that use makefiles. Available only on platforms that use makefiles.
\row \li .target \li Base string used for makefile targets related to this \row \li .target \li Base string used for makefile targets related to this