Doc: Extend qt_add_resource documentation

Pick-to: 6.1
Change-Id: Ia76b1e681eb15cc8ad9de04bb80654e35442c82b
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

3 files changed, 83 insertions, 4 deletions

diff --git a/src/corelib/doc/snippets/cmake-macros/examples.cmake b/src/corelib/doc/snippets/cmake-macros/examples.cmake
index 7515d7fdb2..c02f5c783d 100644
--- a/src/corelib/doc/snippets/cmake-macros/examples.cmake
+++ b/src/corelib/doc/snippets/cmake-macros/examples.cmake
@@ -22,6 +22,13 @@ qt_add_resources(SOURCES example.qrc)
 add_executable(myapp ${SOURCES})
 #! [qt_add_resources]
 
+#! [qt_add_resources_target]
+add_executable(myapp main.cpp)
+qt_add_resources(myapp "images"
+    PREFIX "/images"
+    FILES image1.png image2.png)
+#! [qt_add_resources_target]
+
 #! [qt5_add_big_resources]
 set(SOURCES main.cpp)
 qt5_add_big_resources(SOURCES big_resource.qrc)
diff --git a/src/corelib/doc/src/cmake-macros.qdoc b/src/corelib/doc/src/cmake-macros.qdoc
index 29c1785b67..833aeaff86 100644
--- a/src/corelib/doc/src/cmake-macros.qdoc
+++ b/src/corelib/doc/src/cmake-macros.qdoc
@@ -95,22 +95,77 @@ qt6_add_resources(<VAR> file1.qrc [file2.qrc ...]
                   [OPTIONS ...])
 \endcode
 
+Since 6.0:
+
+\badcode
+qt_add_resources(<TARGET> <RESOURCE_NAME>
+                  [PREFIX <PATH>]
+                  [LANG <LANGUAGE>]
+                  [BASE <PATH>]
+                  [FILES ...] [OPTIONS ...])
+
+qt6_add_resources(<TARGET> <RESOURCE_NAME>
+                  [PREFIX <PATH>]
+                  [LANG <LANGUAGE>]
+                  [BASE <PATH>]
+                  [FILES ...] [OPTIONS ...])
+\endcode
+
 \section1 Description
 
-Creates source code from Qt resource files using the
-\l{Resource Compiler (rcc)}. Paths to the generated source files are added to
-\c{<VAR>}.
+To add resources, you can pass either a variable name or a target as the first
+argument of the command.
+
+When passing a variable name as first argument, \c qt_add_resources creates
+source code from Qt resource files using the \l{Resource Compiler (rcc)}. Paths
+to the generated source files are added to \c{<VAR>}.
+
+When passing a target as first argument, the function creates a resource with
+the name \c{RESOURCE_NAME}, containing the specified \c{FILES}. The resource is
+automatically linked into \c{TARGET}.
 
 For embedding bigger resources, see \l qt_add_big_resources.
 
-\section1 Arguments
+See \l{The Qt Resource System} for a general description of Qt resources.
+
+\section1 Arguments of the target-based variant
+
+\c PREFIX specifies a path prefix under which all files of this resource are
+accessible from C++ code. This corresponds to the XML attribute \c prefix of the
+\c .qrc file format. If \c PREFIX is not given, the target property
+\l{cmake-target-property-QT_RESOURCE_PREFIX}{QT_RESOURCE_PREFIX} is used.
+
+\c LANG specifies the locale of this resource. This corresponds to the XML
+attribute \c lang of the \c .qrc file format.
+
+\c BASE is a path prefix that denotes the root point of the file's alias. For
+example, if \c BASE is \c{"assets"} and \c FILES is
+\c{"assets/images/logo.png"}, then the alias of that file is
+\c{"images/logo.png"}.
+
+Alias settings for files need to be set via the \c QT_RESOURCE_ALIAS source file
+property.
+
+\section1 Arguments of both variants
 
 You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls.
 You can find possible options in the \l{rcc}{rcc documentation}.
 
 \section1 Examples
 
+Variable variant, using a .qrc file:
 \snippet cmake-macros/examples.cmake qt_add_resources
+
+Target variant, using immediate resources:
+\snippet cmake-macros/examples.cmake qt_add_resources_target
+
+\section1 Caveats
+
+When adding multiple resources, \c{RESOURCE_NAME} must be unique across all
+resources linked into the final target.
+
+This especially affects static builds. There, the same resource name in
+different static libraries conflict in the consuming target.
 */
 
 /*!
diff --git a/src/corelib/doc/src/cmake-properties.qdoc b/src/corelib/doc/src/cmake-properties.qdoc
index ced2798f62..9627187bec 100644
--- a/src/corelib/doc/src/cmake-properties.qdoc
+++ b/src/corelib/doc/src/cmake-properties.qdoc
@@ -298,3 +298,20 @@ That library provides implementations of main (or WinMain).
 
 On targets that must provide their own entry point, set the property \c qt_no_entrypoint to inhibit linking against Qt's entrypoint library.
 */
+
+/*!
+\page cmake-target-property-qt_resource_prefix.html
+\ingroup cmake-properties-qtcore
+\ingroup cmake-target-properties-qtcore
+
+\title QT_RESOURCE_PREFIX
+\target cmake-target-property-QT_RESOURCE_PREFIX
+
+\brief Specifies the default Qt resource prefix.
+
+\preliminarycmakeproperty
+
+When using \l{qt6_add_resources}{qt_add_resources} without a \c PREFIX
+argument, then the value of this target property will be used as
+resource prefix.
+*/