1.. _configuration: 2 3============= 4Configuration 5============= 6 7 8 9.. _lv_conf: 10 11lv_conf.h 12********* 13 14 15Creating lv_conf.h 16------------------ 17 18When setting up your project for the first time, copy ``lvgl/lv_conf_template.h`` to 19``lv_conf.h`` next to the ``lvgl`` folder. Change the first ``#if 0`` to ``1`` to 20enable the file's content and set the :c:macro:`LV_COLOR_DEPTH` define to align with 21the color depth used by your display panel. See comments in ``lv_conf.h`` for 22details. 23 24The layout of the files should look like this:: 25 26 lvgl/ 27 lv_conf.h 28 other files and folders in your project 29 30Alternatively, ``lv_conf.h`` can be copied to another place but then you 31should add the :c:macro:`LV_CONF_INCLUDE_SIMPLE` define to your compiler 32options (e.g. ``-DLV_CONF_INCLUDE_SIMPLE`` for GCC compiler) and set the 33include path manually (e.g. ``-I../include/gui``). In this case LVGL 34will attempt to include ``lv_conf.h`` simply with ``#include "lv_conf.h"``. 35 36You can even use a different name for ``lv_conf.h``. The custom path can 37be set via the :c:macro:`LV_CONF_PATH` define. For example 38``-DLV_CONF_PATH="/home/joe/my_project/my_custom_conf.h"``. If this define 39is set :c:macro:`LV_CONF_SKIP` is assumed to be ``0``. Please notice, 40when defining the :c:macro:`LV_CONF_PATH`, you need to make sure it is 41defined as a string, otherwise a build error will be raised. 42 43If :c:macro:`LV_CONF_SKIP` is defined, LVGL will not try to include 44``lv_conf.h``. Instead you can pass the config defines using build 45options. For example ``"-DLV_COLOR_DEPTH=32 -DLV_USE_BUTTON=1"``. Unset 46options will get a default value which is the same as the content of 47``lv_conf_template.h``. 48 49LVGL also can be used via ``Kconfig`` and ``menuconfig``. You can use 50``lv_conf.h`` together with Kconfig as well, but keep in mind that the values 51from ``lv_conf.h`` or build settings (``-D...``) override the values 52set in Kconfig. To ignore the configs from ``lv_conf.h`` simply remove 53its content, or define :c:macro:`LV_CONF_SKIP`. 54 55 56.. _configuration_settings: 57 58Configuration Settings 59---------------------- 60 61Once the ``lv_conf.h`` file is in place, you can modify this header to configure 62LVGL's behavior, disable unused modules and features, adjust the size of buffers, etc. 63 64The comments in ``lv_conf.h`` explain the meaning of each setting. Be sure 65to at least set :c:macro:`LV_COLOR_DEPTH` according to your display's color 66depth. Note that the examples and demos explicitly need to be enabled 67in ``lv_conf.h`` if you need them. 68 69TODO: Add all things related to ``lv_conf.h`` file and its contents. 70 71 72Multiple Instances of LVGL 73~~~~~~~~~~~~~~~~~~~~~~~~~~ 74It is possible to run multiple, independent instances of LVGL. To enable its 75multi-instance feature, set :c:macro:`LV_GLOBAL_CUSTOM` in ``lv_conf.h`` 76and provide a custom function to :cpp:func:`lv_global_default` using ``__thread`` or 77``pthread_key_t``. It will allow running multiple LVGL instances by storing LVGL's 78global variables in TLS (Thread-Local Storage). 79 80For example: 81 82.. code-block:: c 83 84 lv_global_t * lv_global_default(void) 85 { 86 static __thread lv_global_t lv_global; 87 return &lv_global; 88 } 89 90 91 92Kconfig 93******* 94TODO: Add how to use LVGL with Kconfig. 95 96