language-servers/slint
1
0
Fork 0
mirror of https://github.com/slint-ui/slint.git synced 2025-08-04 10:50:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: Polish the C++ docs (#2229)

Browse source
This commit is contained in:
Tobias Hunger 2023-02-15 15:47:45 +01:00 • committed by GitHub
parent 255fe56c94
commit 1a31c9a50b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 289 additions and 197 deletions
Download patch file Download diff file Expand all files Collapse all files

129
api/cpp/docs/cmake.md
View file

@ -1,4 +1,6 @@
# Installing or Building with CMake
<!-- cSpell: ignore ccmake dslint femtovg skia winit -->
# Installing Or Building With CMake
Slint comes with a CMake integration that automates the compilation step of the `.slint` markup language files and
offers a CMake target for convenient linkage.
@ -8,7 +10,8 @@ You can select the CMake Ninja backend by passing `-GNinja` or setting the `CMAK
## Binary Packages
We also provide binary packages of Slint for use with C++, which eliminates the need to have Rust installed in your development environment.
We offer binary packages of Slint for use with C++. These work without any Rust
development environment.
You can download one of our pre-built binaries for Linux or Windows on x86-64 architectures:
@ -16,18 +19,23 @@ You can download one of our pre-built binaries for Linux or Windows on x86-64 ar
2. Click on the latest release
3. From "Assets" download either `slint-cpp-XXX-Linux-x86_64.tar.gz` for a Linux archive
or `slint-cpp-XXX-win64.exe` for a Windows installer. ("XXX" refers to the version of the latest release)
4. Uncompress the downloaded archive or run the installer.
4. Unpack the downloaded archive or run the installer.
After extracting the artifact or running the installer, you can place the `lib` sub-directory into your `CMAKE_PREFIX_PATH` and `find_package(Slint)` should succeed in locating the package.
You also need to place the `lib` sub-directory in the `PATH` envionment variable on Windows, and the `LD_LIBRARY_PATH` on Linux so that
the DLL can be found at runtime.
After extracting the artifact or running the installer, you need to place the
`lib` sub-directory into your `CMAKE_PREFIX_PATH`. `find_package(Slint)` will
then be able to find Slint from within a `CMakeLists.txt` file.
At runtime you might also need to add the `lib` sub-directory to the `PATH`
environment variable on Windows or the `LD_LIBRARY_PATH` on Linux. This is
necessary to find the Slint libraries when trying to run your program.
In the next section you will learn how to use the installed library in your application
and load `.slint` UI files.
and how to work with `.slint` UI files.
## Building from Sources
## Building From Sources
The recommended and most flexible way to use the C++ API is to build Slint from sources.
The recommended and most flexible way to use the C++ API is to build Slint from
sources.
First you need to install the prerequisites:
@ -37,80 +45,101 @@ First you need to install the prerequisites:
* **[cmake](https://cmake.org/download/)** (3.21 or newer)
* A C++ compiler that supports C++20 (e.g., **MSVC 2019 16.6** on Windows)
You can include Slint in your CMake project using CMake's [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html) feature.
Insert the following snippet into your `CMakeLists.txt` to make CMake download the latest release, compile it and make the CMake integration available:
You can include Slint into your CMake project using CMake's
[`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html)
feature. Insert the following snippet into your `CMakeLists.txt` to make CMake
download the latest released 1.x version, compile it, and make the CMake
integration available:
```cmake
include(FetchContent)
FetchContent_Declare(
Slint
GIT_REPOSITORY https://github.com/slint-ui/slint.git
GIT_TAG release/0.3
GIT_TAG release/1
SOURCE_SUBDIR api/cpp
)
FetchContent_MakeAvailable(Slint)
```
If you prefer to treat Slint as an external CMake package, then you can also build Slint from source like a regular
If you prefer to use Slint as an external CMake package, then you 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`.
### Features
The Slint run-time library supports different features that can be toggled. You might want to enable a feature that is
not enabled by default but that is revelant for you, or you may want to disable a feature that you know you do not need and
therefore reduce the size of the resulting library.
The Slint library supports a set of features, not all of them enabled by default.
You might want to adapt the set of enabled features to optimize your binary
size. For example you might want to support only the wayland stack on Linux.
Enable the `backend-winit-wayland` feature while turning off the
`backend-winit-x11` feature to do so.
The CMake configure step offers CMake options for various feature that are all prefixed with `SLINT_FEATURE_`. For example
you can make a build that exclusively supports Wayland on Linux by enabling the `SLINT_FEATURE_BACKEND_WINIT_WAYLAND` feature and turning
off `SLINT_FEATURE_BACKEND_WINIT`. There are different ways of toggling CMake options. For example on the command line using the `-D` parameter:
Slint's CMake configuration uses CMake options prefixed with `SLINT_FEATURE_` to
expose Slint's feature flags at compile time. To have a wayland-only stack with
the CMake setup you would for example use:
`cmake -DSLINT_FEATURE_BACKEND_WINIT=OFF -DSLINT_FEATURE_BACKEND_WINIT_WAYLAND=ON ...`
Alternatively, after the configure step you can use `cmake-gui` or `ccmake` on the build directory for a list of all features
and their description.
Alternatively, you can use `cmake-gui` or `ccmake` for a more interactive way
to discover and toggle features.
This works when compiling Slint as a package, using `cmake --build` and `cmake --install`, or when including Slint
using `FetchContent`.
This works when compiling Slint as a package, using `cmake --build` and
`cmake --install`, or when including Slint using `FetchContent`.
### Backends
### Back-Ends
Slint needs a backend that will act as liaison between Slint and the OS.
By default, Slint will use the Qt backend, if Qt is installed, otherwise, it
will use [Winit](https://crates.io/crates/winit) with [Femtovg](https://crates.io/crates/femtovg).
Both backends are compiled in. If you want to not compile one of these you need
to disable the `SLINT_FEATURE_BACKEND_WINIT` and `SLINT_FEATURE_RENDERER_WINIT_FEMTOVG` features and enable
the backend and renderer features you choose.
Slint needs a back-end that acts as liaison between Slint and the OS. Several
back-ends can be built into the Slint library at the same time, but only one
is used a run time.
If you enable the Winit backend, you need to also include a renderer.
`SLINT_FEATURE_RENDERER_WINIT_FEMTOVG` is the only stable renderer, the other ones are experimental
It is also possible to select the backend and renderer at runtime when several
are enabled, using the `SLINT_BACKEND` environment variable.
* `SLINT_BACKEND=Qt` selects the Qt backend
* `SLINT_BACKEND=winit` selects the winit backend
* `SLINT_BACKEND=winit-femtovg` selects the winit backend with the femtovg renderer
* `SLINT_BACKEND=winit-skia` selects the winit backend with the skia renderer
* `SLINT_BACKEND=winit-software` selects the winit backend with the software renderer
If the selected backend is not available, the default will be used.
#### Compile Time Back-End 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
`SLINT_FEATURE_BACKEND_` features. For example, to exclude the winit back-end,
you would disable the `SLINT_FEATURE_BACKEND_WINIT` option in your CMake
project configuration.
The winit back-end needs a renderer. `SLINT_FEATURE_RENDERER_WINIT_FEMTOVG` is
the only stable renderer, the other ones are experimental. If you disable the
`SLINT_FEATURE_BACKEND_WINIT`, you will also want to disable the renderer!
#### Run Time Back-End Selection
It's also possible to select any of the compiled in back-ends 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 is possible to cross-compile Slint to a different target architecture when building with CMake. In order to complete
that, you need to make sure that your CMake setup is ready for cross-compilation. You can find more information about
how to set this up in the [upstream CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling).
It's possible to cross-compile Slint to a different target architecture when
building with CMake. You need to make sure your CMake setup is ready for
cross-compilation, as documented in the [upstream CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling).
If you are building against a Yocto SDK, it is sufficient to source the SDK's environment setup file.
Since Slint is implemented using the Rust programming language, you need to determine which Rust target
matches the target architecture that you're compiling to. Please consult the [upstream Rust documentation](https://doc.rust-lang.org/nightly/rustc/platform-support.html) to find the correct target name. Now you need to install the Rust toolchain:
Since Slint is implemented using the Rust programming language, you need to
determine which Rust target matches the target architecture that you're
compiling for. Please consult the [upstream Rust documentation](https://doc.rust-lang.org/nightly/rustc/platform-support.html) to find the correct target name. Now you need to install the Rust toolchain:
```sh
rustup target add <target-name>
```
Then you're ready to invoke CMake and you need to add `-DRust_CARGO_TARGET=<target name>` to the CMake command line.
Then you're ready to iconfigure your CMake project you need to add
`-DRust_CARGO_TARGET=<target name>` to the CMake command line.
This ensures that the Slint library is built for the correct architecture.
For example if you are building against an embedded Linux Yocto SDK targeting an ARM64 board, the following commands
show how to compile:
For example if you are building against an embedded Linux Yocto SDK targeting
an ARM64 board, the following commands show how to compile:
Install the Rust targe toolchain once:
@ -125,10 +154,10 @@ Set up the environment and build:
<!-- cSpell:disable -->
```sh
. /path/to/yocto/sdk/environment-setup-cortexa53-crypto-poky-linux
cd slint
cd <PROJECT_ROOT>
mkdir build
cd build
cmake -DRust_CARGO_TARGET=aarch64-unknown-linux-gnu -DCMAKE_INSTALL_PREFIX=/slint/install/path ..
cmake -DRust_CARGO_TARGET=aarch64-unknown-linux-gnu -DCMAKE_INSTALL_PREFIX=/slint/install/path ...
cmake --build .
cmake --install .
```