# CMake (/integration/building/cmake) Overview [#overview] CMake is a cross-platform build system generator. It is used to easily integrate a project/library into another project. It also offers the possibility to configure the build with different options, to enable or disable components, or to integrate custom scripts executions during the configuration/build phase. LVGL includes CMake natively, which means that one can use it to configure and build LVGL directly or integrate it into a higher level cmake build. This project uses CMakePresets to ensure an easy build. Find out more on Cmake Presets here: [https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) Prerequisites [#prerequisites] You need to install * CMake with GNU make or Ninja (for Linux builds). Be sure to add ninja/make to your PATH! * The prerequisites listed in `scripts/install-prerequisites.sh/bat` * A python3 interpreter if you wish to use KConfig. How to build this project using cmake [#how-to-build-this-project-using-cmake] Build with Command line [#build-with-command-line] The simplest way to build LVGL using cmake is to use the command line calls: ```bash title="bash" lineNumbers=1 # Method 1 cd mkdir build cd build cmake .. # Configure phase cmake --build . # Build phase # Method 2 cd cmake -B build # Configure phase cmake --build build # build phase ``` Build with cmake presets [#build-with-cmake-presets] Another way to build this project is to use the provided CMakePresets.json or pass options using the command line. The CMakePresets.json file describes some cmake configurations and build phase. It is a way to quickly use a set of predefined cmake options. For now, these configuration presets are available: * `windows-base`: A Windows configuration, using VS MSVC. Uses `lv_conf.h` as the configuration system. * `windows-kconfig`: A Windows configuration, using VS MSVC. Uses Kconfig as the configuration system. * `linux-base`: A Linux configuration, using Ninja and GCC. Uses `lv_conf.h` as the configuration system. * `linux-kconfig`: A Linux configuration, using Ninja and GCC. Uses Kconfig as the configuration system. And these build presets: * `windows-base_dbg`: Windows Debug build. * `windows-base_rel`: Windows Release build. * `linux-base_dbg`: Linux Debug build. * `linux-base_rel`: Linux Release build. Here is how to build using the presets: ```bash title="bash" lineNumbers=1 cmake --preset windows-base cmake --build --preset windows-base_dbg ctest --preset windows-base_dbg ``` Build with IDE [#build-with-ide] The recommended way for consuming CMakePresets is a CMakePresets aware IDE such as * VS 2022 * VS Code * CLion Simply load this project into your IDE and select your desired preset and you are good to go. Build with CMake GUI [#build-with-cmake-gui] Open this project with CMake GUI and select your desired preset. When hitting the generate button, CMake will create solution files (for VS) or Ninja Files (for Linux Ninja Build) The following targets are available. * lvgl (the actual library, required) * lvgl\_thorvg (a vector graphics extension, optional) * lvgl\_examples (example usages, optional) * lvgl\_demos (some demos, optional) All optional targets can be disabled by setting the proper cache variables. If you use cmake to install lvgl, 3 folders will be created. * include/lvgl (contains all public headers) * bin (contains all binaries (\*.dll)) * lib (contains all precompiled source files (\*.lib)) Integrate LVGL to your project using cmake [#integrate-lvgl-to-your-project-using-cmake] The LVGL cmake system is made to be integrated into higher level projects. To do so, simply add this to your project's `CMakeLists.txt`. This snippet adds LVGL and needs an `lv_conf.h` file present next to the lvgl folder: ```cmake title="cmake" lineNumbers=1 add_subdirectory(lvgl) ``` This snippet sets up LVGL and tells it which `lv_conf.h` file to use: ```cmake title="cmake" lineNumbers=1 set(LV_BUILD_CONF_PATH path/to/my_lv_conf.h) add_subdirectory(lvgl) ``` This snippet sets up LVGL and points to the folder where `lv_conf.h` is located: ```cmake title="cmake" lineNumbers=1 set(LV_BUILD_CONF_DIR path/to/directory) add_subdirectory(lvgl) ``` This snippet adds LVGL and specifies to use Kconfig as the configuration system: ```cmake title="cmake" lineNumbers=1 set(LV_BUILD_USE_KCONFIG ON) add_subdirectory(lvgl) ``` This snippet adds LVGL and specifies to use Kconfig as the configuration system and to use a specific defconfig: ```cmake title="cmake" lineNumbers=1 set(LV_BUILD_USE_KCONFIG ON) set(LV_BUILD_DEFCONFIG_PATH path/to/my_defconfig) add_subdirectory(lvgl) ``` To enable the demos and examples set these options: ```cmake title="cmake" lineNumbers=1 set(CONFIG_LV_BUILD_EXAMPLES ON) set(CONFIG_LV_BUILD_DEMOS ON) add_subdirectory(lvgl) ``` Dependency Management [#dependency-management] When `LV_BUILD_SET_CONFIG_OPTS` is enabled, LVGL can automatically resolve, and optionally fetch, the dependencies required by the features enabled in `lv_conf.h`. For example, enabling `LV_USE_WAYLAND` in `lv_conf.h` will cause LVGL to find or fetch the Wayland libraries automatically. Dependency resolution is attempted in this order: 1. `find_package` — uses CMake's built-in package discovery 2. `pkg-config` — uses the system's pkg-config tool (Linux/macOS) 3. `FetchContent` — fetches and builds the dependency from source Each strategy can be disabled globally or per dependency. This is particularly useful for cross-compilation environments where system libraries should not be used. Disabling system resolution globally (e.g. for cross-compilation): ```bash title="bash" lineNumbers=1 cmake -DLV_USE_FIND_PACKAGE=OFF -DLV_USE_PKG_CONFIG=OFF .. ``` Disabling system resolution for a specific dependency only: ```bash title="bash" lineNumbers=1 cmake -DLV_USE_FIND_PACKAGE_FREETYPE=OFF -DLV_USE_PKG_CONFIG_FREETYPE=OFF .. ``` Disabling automatic fetching from source: ```bash title="bash" lineNumbers=1 cmake -DLV_FETCH_DEPENDENCIES=OFF .. ``` Fetched dependency sources are cached in the `.deps` directory at the root of your project, so they are not re-downloaded between builds. Dependency management requires `CONFIG_LV_*` variables to be set (e.g. `CONFIG_LV_USE_WAYLAND`). These can be set manually via `-D` arguments or generated automatically by enabling `LV_BUILD_SET_CONFIG_OPTS`, which parses `lv_conf_internal.h` to derive them. Below is a list of the available options/variables | Variable/Option | Type | Description | | ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | LV\_BUILD\_CONF\_PATH | PATH | Allows to set a custom path for `lv_conf.h` | | LV\_BUILD\_CONF\_DIR | PATH | Allows to set a directory containing `lv_conf.h` | | LV\_BUILD\_USE\_KCONFIG | BOOLEAN | When set KConfig is used as the configuration source. This option is disabled by default. | | LV\_BUILD\_DEFCONFIG\_PATH | PATH | Specify to use a .defconfig file instead of the current .config in a Kconfig setup. | | LV\_BUILD\_LVGL\_H\_SYSTEM\_INCLUDE | BOOLEAN | Enable if LVGL will be installed to the system or your build system uses a sysroot. Turning this option on implies that the resources generated by the image generation script will include `lvgl.h` as a system include. i.e: `#include `. This option is disabled by default. | | LV\_BUILD\_LVGL\_H\_SIMPLE\_INCLUDE | BOOLEAN | When enabled the resources will include `lvgl.h` as a simple include, this option is enabled by default. | | LV\_BUILD\_SET\_CONFIG\_OPTS | BOOLEAN | When enabled, this option runs a script that processes the `lv_conf.h`/Kconfig configuration using `pcpp` to generate corresponding `CONFIG_LV_*` and `CONFIG_LV_BUILD_*` CMake variables based on the contents of `lv_conf_internal.h`. This requires python3 with `venv` and `pip` or access to a working `pcpp`. If KConfig is used, this is enabled automatically. | | LV\_USE\_FIND\_PACKAGE | BOOLEAN | Allow resolving dependencies via `find_package`. Enabled by default. | | LV\_USE\_PKG\_CONFIG | BOOLEAN | Allow resolving dependencies via `pkg-config`. Enabled by default. Requires pkg-config to be installed. | | LV\_FETCH\_DEPENDENCIES | BOOLEAN | Fetch dependencies from source if not found on the system. Enabled by default. | | LV\_USE\_FIND\_PACKAGE\_\ | BOOLEAN | Allow resolving a specific dependency via `find_package`. Defaults to `LV_USE_FIND_PACKAGE`. Example: `LV_USE_FIND_PACKAGE_FREETYPE`. | | LV\_USE\_PKG\_CONFIG\_\ | BOOLEAN | Allow resolving a specific dependency via `pkg-config`. Defaults to `LV_USE_PKG_CONFIG`. Example: `LV_USE_PKG_CONFIG_FREETYPE`. | | LV\_FETCH\_\ | BOOLEAN | Fetch a specific dependency from source. Defaults to `LV_FETCH_DEPENDENCIES`. Example: `LV_FETCH_FREETYPE`. | | CONFIG\_LV\_BUILD\_DEMOS | BOOLEAN | When enabled builds the demos | | CONFIG\_LV\_BUILD\_EXAMPLES | BOOLEAN | When enabled builds the examples | | CONFIG\_LV\_USE\_THORVG\_INTERNAL | BOOLEAN | When enabled the in-tree LVGL version of ThorVG is compiled | | CONFIG\_LV\_USE\_PRIVATE\_API | BOOLEAN | When enabled the private headers `*_private.h` are installed on the system | When `LV_BUILD_SET_CONFIG_OPTS` or `LV_BUILD_USE_KCONFIG` are enabled, the options/variables beginning with the prefix `CONFIG_*` are automatically set to the values found in `lv_conf.h`