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