C++ docs: add cmake reference

api/cpp/docs/cmake.md

@@ -15,10 +15,10 @@
 
 ## Install Slint
 
-To install Slint, either download the [binary packages](#install-binary-packages) or [build from sources](#build-from-sources).  
+To install Slint, either download the [binary packages](#install-binary-packages) or [build from sources](#build-from-sources).
 
 *Note*: Binary packages are available for only Linux and Windows on x86-64 architecture. The recommended and most flexible way to use the C++ API is to build Slint from sources.
-  
+
 ### Install Binary Packages
 
 The Slint binary packages work without any Rust development environment.
@@ -72,17 +72,6 @@ FetchContent_MakeAvailable(Slint)
 
 * To include Slint as an external CMake package, build Slint from source like a regular CMake project, install it into a prefix directory of your choice and use `find_package(Slint)` in your `CMakeLists.txt`.
 
-### Resource Embedding
-
-By default, images or fonts that your Slint files reference are loaded from disk at run-time. This minimises build times, but requires that the directory structure with the files remains stable. If you want to build a program that runs anywhere, then you can configure the Slint compiler to embed such sources into the binary.
-
-Set the `SLINT_EMBED_RESOURCES` target property on your CMake target to one of the following values:
-
-* `embed-files`: The raw files are embedded in the application binary.
-* `embed-for-software-renderer`: The files will be loaded by the Slint compiler, optimized for use with the software renderer and embedded in the application binary.
-* `as-absolute-path`: The paths of files are made absolute and will be used at run-time to load the resources from the file system. This is the default.
-
-This target property is initialised from the global `DEFAULT_SLINT_EMBED_RESOURCES` cache variable. Set it to configure the default for all CMake targets.
 
 ### Features
 
@@ -121,8 +110,6 @@ abstraction and window adapter interfaces.
 For more information about the available backends, their system requirements, and configuration
 options, see the [Backend & Renderers Documentation](slint-reference:src/advanced/backends_and_renderers.html).
 
-#### Compile Time Backend Selection
-
 By default Slint will include both the Qt and
 [winit](https://crates.io/crates/winit) back-ends -- if both are detected at
 compile time. You can enable or disable back-ends using the
@@ -134,20 +121,6 @@ The winit back-end needs a renderer. `SLINT_FEATURE_RENDERER_FEMTOVG` and
 `SLINT_FEATURE_RENDERER_SKIA` are the only stable renderers, the other ones are
 experimental.
 
-#### Run Time Backend Selection
-
-It's also possible to select any of the compiled in backends and renderer at
-runtime, using the `SLINT_BACKEND` environment variable.
-
-* `SLINT_BACKEND=Qt` selects the Qt back-end
-* `SLINT_BACKEND=winit` selects the winit back-end
-* `SLINT_BACKEND=winit-femtovg` selects the winit back-end with the femtovg renderer
-* `SLINT_BACKEND=winit-skia` selects the winit back-end with the skia renderer
-* `SLINT_BACKEND=winit-software` selects the winit back-end with the software renderer
-
-If the selected back-end or renderer isn't available, the default will be used
-instead.
-
 ### Cross-compiling
 
 It's possible to cross-compile Slint to a different target architecture when

api/cpp/docs/cmake_reference.md

@@ -0,0 +1,40 @@
+# CMake Reference
+<!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
+
+
+## `slint_target_sources`
+
+```
+slint_target_sources(<target> <files>....)
+```
+
+Use this function to tell cmake about the .slint files of your application, similar to the builtin cmake [target_sources](https://cmake.org/cmake/help/latest/command/target_sources.html) function.
+The function takes care of running the slint-compiler to convert `.slint` files to `.h` files in the build directory,
+and extend  the include directories of your target so that the generated file is found when including it in your application.
+
+
+Given a file called `the_window.slint`, the following example will create a file called `the_window.h` that can
+be included from your .cpp file.
+
+```cmake
+add_executable(my_application main.cpp)
+target_link_libraries(my_application PRIVATE Slint::Slint)
+slint_target_sources(my_application the_window.slint)
+```
+
+## Resource Embedding
+
+By default, images from [`@image-url()`](slint-reference:src/language/syntax/types#images) or fonts that your Slint files reference are loaded from disk at run-time. This minimises build times, but requires that the directory structure with the files remains stable. If you want to build a program that runs anywhere, then you can configure the Slint compiler to embed such sources into the binary.
+
+Set the `SLINT_EMBED_RESOURCES` target property on your CMake target to one of the following values:
+
+* `embed-files`: The raw files are embedded in the application binary.
+* `embed-for-software-renderer`: The files will be loaded by the Slint compiler, optimized for use with the software renderer and embedded in the application binary.
+* `as-absolute-path`: The paths of files are made absolute and will be used at run-time to load the resources from the file system. This is the default.
+
+This target property is initialised from the global `DEFAULT_SLINT_EMBED_RESOURCES` cache variable. Set it to configure the default for all CMake targets.
+
+```cmake
+# Example: when building my_application, specify that the compiler should embed the resources in the binary
+set_property(TARGET my_application PROPERTY SLINT_EMBED_RESOURCES embed-files)
+```

api/cpp/docs/generated_code.md

@@ -1,8 +1,9 @@
 <!-- Copyright © SixtyFPS GmbH <info@slint.dev> ; SPDX-License-Identifier: MIT -->
 # Generated Code
 
-The Slint compiler called by the build system will generate a header file for the root `.slint`
+The Slint compiler [called by the build system](cmake_reference.md#slint_target_sources)
-file. This header file will contain a `class` with the same name as the root
+will generate a header file for the root `.slint` file.
+This header file will contain a `class` with the same name as the root
 component.
 
 This class will have the following public member functions:

api/cpp/docs/index.rst

@@ -33,6 +33,8 @@ Slint C++ documentation
 
    api/library_root
 
+   cmake_reference.md
+
    genindex
 
 .. image:: https://github.com/slint-ui/slint/workflows/CI/badge.svg

api/cpp/docs/overview.md

@@ -23,7 +23,7 @@ handling callbacks to react to events triggered by the user.
 ## Compiled `.slint` Designs
 
 The provided CMake integration makes it easy to compile your Slint sources:
-The `slint_target_sources` CMake command makes the translation automatic. The
+The [`slint_target_sources` CMake command](cmake_reference.md#slint_target_sources) makes the translation automatic. The
 [generated code](generated_code.md) has an API to set and get property values,
 etc. This API uses types from the {ref}`slint <namespace_slint>` namespace, for
 example {cpp:class}`slint::SharedString` or {cpp:class}`slint::Color`.