CMake: Allow contents of resources to be replaced by empty files

This makes it possible to process QML files using qmlcachegen, and
retain the file nodes in the resource file system, but remove their
actual content from the binary. To do so, you need to mark your files
with the QT_DISCARD_FILE_CONTENTS source file property.

Fixes: QTBUG-87676
Fixes: QTBUG-103481
Fixes: QTBUG-102024
Fixes: QTBUG-102785
Change-Id: I93d5a2bfca1739ff1e0f74c8082eb8aa451b9815
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Reviewed-by: hjk <hjk@qt.io>

3 files changed, 50 insertions, 0 deletions

diff --git a/src/corelib/doc/snippets/code/doc_src_resources.qdoc b/src/corelib/doc/snippets/code/doc_src_resources.qdoc
index a2e515ce03..f5a12ee86a 100644
--- a/src/corelib/doc/snippets/code/doc_src_resources.qdoc
+++ b/src/corelib/doc/snippets/code/doc_src_resources.qdoc
@@ -26,3 +26,7 @@
 //! [3]
 rcc -binary myresource.qrc -o myresource.rcc
 //! [3]
+
+//! [4]
+<file empty="true">Button.qml</file>
+//! [4]
diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc
index 89e7045bc7..42dfeeabe2 100644
--- a/src/corelib/doc/src/cmake/cmake-properties.qdoc
+++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc
@@ -422,6 +422,33 @@ the property value overrides the runtime path where the resource file is found.
 */
 
 /*!
+\page cmake-source-file-property-qt-discard-file-contents.html
+\ingroup cmake-source-file-properties-qtcore
+
+\title QT_DISCARD_FILE_CONTENTS
+\target cmake-source-file-property-QT_DISCARD_FILE_CONTENTS
+
+\summary {Specifies that the given files should be empty in the resource file system}
+
+\cmakepropertysince 6.5
+\preliminarycmakeproperty
+
+When using the target-based variant of \l{qt6_add_resources}{qt_add_resources}
+or \l{qt_add_qml_module}, setting this property to \c TRUE causes the file
+contents to be omitted when creating the resource file system. The file name is
+retained.
+
+This is useful if you want to strip QML source code from the binary.
+
+\note If you omit the QML source code from the binary, the QML engine has to
+rely on the the compilation units created by \l{qmlcachegen} or \l{qmlsc}.
+Those are tied to the specific version of Qt they were built with. If you change
+the version of Qt your application uses, they can't be loaded anymore.
+
+\sa{The Qt Resource System}
+*/
+
+/*!
 \page cmake-target-property-qt-wasm-pthread-pool-size.html
 \ingroup cmake-properties-qtcore
 \ingroup cmake-target-properties-qtcore
diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc
index 8cee601c67..66d0c214b0 100644
--- a/src/corelib/doc/src/resource-system.qdoc
+++ b/src/corelib/doc/src/resource-system.qdoc
@@ -166,6 +166,25 @@
     The file is from the application then only accessible as \c :/cut-img.png
     or \c{qrc:/cut-img.png}.
 
+    \section2 Discarding the file contents
+
+    Sometimes you want to add a file node to the resource file system but
+    don't actually want to add the file contents. \c .qrc files allow this
+    by setting the \c empty attribute to \c{true}.
+
+    \snippet code/doc_src_resources.qdoc 4
+
+    The resulting file is then still accessible from the application, but
+    its contents are empty.
+
+    This is useful to strip QML source code from an application binary.
+
+    \note If you omit the QML source code from the binary, the QML engine has to
+    rely on the the compilation units created by \l{qmlcachegen} or \l{qmlsc}.
+    Those are tied to the specific version of Qt they were built with. If you
+    change the version of Qt your application uses, they can't be loaded
+    anymore.
+
     \section2 Language Selectors
 
     Some resources need to change based on the user's locale, such as