.. SPDX-License-Identifier: CC-BY-SA-4.0

Environment variables
=====================

The libcamera behaviour can be tuned through environment variables. This
document lists all the available variables and describes their usage.

List of variables
-----------------

LIBCAMERA_LOG_FILE
   The custom destination for log output.

   Example value: ``/home/{user}/camera_log.log``

LIBCAMERA_LOG_LEVELS
   Configure the verbosity of log messages for different categories (`more <Log levels_>`__).

   Example value: ``*:DEBUG``

LIBCAMERA_IPA_CONFIG_PATH
   Define custom search locations for IPA configurations (`more <IPA configuration_>`__).

   Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa``

LIBCAMERA_IPA_MODULE_PATH
   Define custom search locations for IPA modules (`more <IPA module_>`__).

   Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib``

Further details
---------------

Notes about debugging
~~~~~~~~~~~~~~~~~~~~~

The environment variables ``LIBCAMERA_LOG_FILE`` and ``LIBCAMERA_LOG_LEVELS``
are used to modify the destination and verbosity of messages provided by
libcamera.

The ``LIBCAMERA_LOG_LEVELS`` variable accepts a comma-separated list of
'category:level' pairs.

The `level <Log levels_>`__ part is mandatory and can either be specified by
name or by numerical index associated with each level.

The optional `category <Log categories_>`__ is a string matching the categories
defined by each file in the source base using the logging infrastructure. It
can include a wildcard ('*') character at the end to match multiple categories.

For more information refer to the `API documentation <http://libcamera.org/api-html/log_8h.html#details>`__.

Examples:

Enable full debug output to a separate file, for every `category <Log categories_>`__
within a local environment:

.. code:: bash

   :~$ LIBCAMERA_LOG_FILE='/tmp/example_log.log' \
       LIBCAMERA_LOG_LEVELS=0 \
       cam --list

Enable full debug output for the categories ``Camera`` and ``V4L2`` within a
global environment:

.. code:: bash

   :~$ export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,V4L2:DEBUG'
   :~$ cam --list

Log levels
~~~~~~~~~~~

This is the list of available log levels, notice that all levels below
the chosen one are printed, while those above are discarded.

-  DEBUG (0)
-  INFO (1)
-  WARN (2)
-  ERROR (3)
-  FATAL (4)

Example:
If you choose WARN (2), you will be able to see WARN (2), ERROR (3) and FATAL (4)
but not DEBUG (0) and INFO (1).

Log categories
~~~~~~~~~~~~~~~

Every category represents a specific area of the libcamera codebase,
the names can be located within the source code, for example:
`src/libcamera/camera_manager.cpp <https://git.libcamera.org/libcamera/libcamera.git/tree/src/libcamera/camera_manager.cpp#n35>`__

.. code:: cpp

   LOG_DEFINE_CATEGORY(Camera)

There are two available macros used to assign a category name to a part of the
libcamera codebase:

LOG_DEFINE_CATEGORY
   This macro is required, in order to use the ``LOGC`` macro for a particular
   category. It can only be used once for each category. If you want to create
   log messages within multiple compilation units for the same category utilize
   the ``LOG_DECLARE_CATEGORY`` macro, in every file except the definition file.
LOG_DECLARE_CATEGORY
   Used for sharing an already defined category between multiple separate
   compilation units.

Both macros have to be used within the libcamera namespace of the C++ source
code.

IPA configuration
~~~~~~~~~~~~~~~~~

IPA modules use configuration files to store parameters. The format and
contents of the configuration files is sp<span class="hl kwa">&lt;svg</span> <span class="hl kwb">xmlns</span>=<span class="hl str">&quot;http://www.w3.org/2000/svg&quot;</span> <span class="hl kwb">width</span>=<span class="hl str">&quot;24&quot;</span> <span class="hl kwb">height</span>=<span class="hl str">&quot;24&quot;</span> <span class="hl kwb">viewBox</span>=<span class="hl str">&quot;0 0 24 24&quot;</span> <span class="hl kwb">fill</span>=<span class="hl str">&quot;none&quot;</span> <span class="hl kwb">stroke</span>=<span class="hl str">&quot;currentColor&quot;</span> <span class="hl kwb">stroke-width</span>=<span class="hl str">&quot;2&quot;</span> <span class="hl kwb">stroke-linecap</span>=<span class="hl str">&quot;round&quot;</span> <span class="hl kwb">stroke-linejoin