[{"id":34865,"web_url":"https://patchwork.libcamera.org/comment/34865/","msgid":"<083630f6-b94a-4747-a7b5-c0c618eabdc7@ideasonboard.com>","date":"2025-07-11T15:28:46","subject":"Re: [PATCH v12 08/12] config: Add global configuration file\n\tdocumentation","submitter":{"id":216,"url":"https://patchwork.libcamera.org/api/people/216/","name":"Barnabás Pőcze","email":"barnabas.pocze@ideasonboard.com"},"content":"Hi\n\n2025. 07. 02. 15:10 keltezéssel, Milan Zamazal írta:\n> Extend (and rename) the documentation of environment variables with\n> information about the configuration file.\n> \n> Signed-off-by: Milan Zamazal \n> ---\n> Documentation/documentation-contents.rst | 2 +-\n> Documentation/index.rst | 2 +-\n> Documentation/meson.build | 2 +-\n> ...ariables.rst => runtime_configuration.rst} | 105 ++++++++++++++++--\n> 4 files changed, 99 insertions(+), 12 deletions(-)\n> rename Documentation/{environment_variables.rst => runtime_configuration.rst} (66%)\n> \n> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst\n> index 5c1118493..4be3729cf 100644\n> --- a/Documentation/documentation-contents.rst\n> +++ b/Documentation/documentation-contents.rst\n> @@ -7,7 +7,7 @@\n> * :doc:`/feature_requirements`\n> * :doc:`/guides/application-developer`\n> * :doc:`/python-bindings`\n> - * :doc:`/environment_variables`\n> + * :doc:`/runtime_configuration`\n> * :doc:`/api-html/index`\n> * :doc:`/code-of-conduct`\n> * |\n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 251112fbd..200de6f67 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -12,13 +12,13 @@\n> \n> Application Writer's Guide \n> Camera Sensor Model \n> - Environment variables \n> Feature Requirements \n> IPA Writer's guide \n> Lens driver requirements \n> libcamera Architecture \n> Pipeline Handler Writer's Guide \n> Python Bindings \n> + Runtime configuration \n> Sensor driver requirements \n> SoftwareISP Benchmarking \n> Tracing guide \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 0fc5909d0..6d5af0f62 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -128,7 +128,6 @@ if sphinx.found()\n> 'contributing.rst',\n> 'design/ae.rst',\n> 'documentation-contents.rst',\n> - 'environment_variables.rst',\n> 'feature_requirements.rst',\n> 'guides/application-developer.rst',\n> 'guides/ipa.rst',\n> @@ -140,6 +139,7 @@ if sphinx.found()\n> 'libcamera_architecture.rst',\n> 'mali-c55.dot',\n> 'python-bindings.rst',\n> + 'runtime_configuration.rst',\n> 'sensor_driver_requirements.rst',\n> 'software-isp-benchmarking.rst',\n> '../README.rst',\n> diff --git a/Documentation/environment_variables.rst b/Documentation/runtime_configuration.rst\n> similarity index 66%\n> rename from Documentation/environment_variables.rst\n> rename to Documentation/runtime_configuration.rst\n> index 6f1235587..f1fea1c1c 100644\n> --- a/Documentation/environment_variables.rst\n> +++ b/Documentation/runtime_configuration.rst\n> @@ -2,15 +2,98 @@\n> \n> .. include:: documentation-contents.rst\n> \n> -Environment variables\n> +Runtime configuration\n> =====================\n> \n> -The libcamera behaviour can be tuned through environment variables. This\n> -document lists all the available variables and describes their usage.\n> +The libcamera behaviour can be tuned through a configuration file or\n> +environment variables. This document lists all the configuration options\n> +and describes their usage.\n> +\n> +General rules\n> +-------------\n> +\n> +The configuration file is looked up in the following locations, in this\n> +order:\n> +\n> +- $XDG_CONFIG_HOME/libcamera/configuration.yaml\n> +- LIBCAMERA_SYSCONF_DIR/configuration.yaml\n> +- /etc/libcamera/configuration.yaml\n\nShould be `LIBCAMERA_DATA_DIR` instead of /etc.\n\n\n> +\n> +The first configuration file found wins, contingent configuration files\n> +in other locations are ignored.\n\nMy native language is not English, but I am wondering if \"contingent\" is the\nword to use here? I think I would personally just omit the word entirely, or\nsay \"subsequent\", or \"[...] other configuration files in different locations [...]\".\n\n\n> +\n> +Settings in environment variables take precedence over settings in\n> +configuration files. This allows overriding behaviour temporarily\n> +without the need to modify configuration files.\n> +\n> +Configuration options\n> +---------------------\n> +\n> +Here is an overview of the available configuration options, in the YAML\n> +file structure:\n> +\n> +::\n> +\n> + configuration:\n> + ipa:\n> + config_paths: # full paths to directories, separated by colons\n> + force_isolation: # true/false\n> + module_paths: # full paths to directories, separated by colons\n> + ipas:\n> + rkisp1:\n> + tuning_file: # full path\n> + rpi:\n> + tuning_file: # full path\n> + pipelines_match_list: # pipeline names, separated by commas\n> + pipelines:\n> + rpi:\n> + target: TARGET\n> + pipeline_handler:\n> + ...\n\nrpi:\n bcm2835:\n pipeline_handler:\n ...\n pisp:\n pipeline_handler:\n ...\n\n\n> + simple:\n> + supported_devices:\n> + - driver: # driver name, e.g. `mxc-isi`\n> + software_isp: # true/false\n> +\n> +Configuration file example\n> +--------------------------\n> +\n> +::\n> +\n> + ---\n> + version: 1\n> + configuration:\n> + ipa:\n> + config_paths:\n> + - /home/user/.libcamera/share/ipa\n> + - /opt/libcamera/vendor/share/ipa\n> + module_paths:\n> + - /home/user/.libcamera/lib\n> + - /opt/libcamera/vendor/lib\n> + proxy_paths:\n> + - /home/user/.libcamera/proxy/worker\n> + - /opt/libcamera/vendor/proxy/worker\n> + force_isolation: true\n> + ipas:\n> + rpi:\n> + tuning_file: /home/pi/imx283.json\n> + pipelines_match_list: rkisp1,simple\n> + pipelines:\n> + rpi:\n> + target: bcm2835\n> + pipeline_handler:\n> + min_unicam_buffers: 2\n> + min_total_unicam_buffers: 2\n\nSame here.\n\n\nRegards,\nBarnabás Pőcze\n\n\n> + simple:\n> + supported_devices:\n> + - driver: mxc-isi\n> + software_isp: true\n> \n> List of variables\n> -----------------\n> \n> +The corresponding configuration file paths, if available, are listed in parentheses.\n> +\n> LIBCAMERA_LOG_FILE\n> The custom destination for log output.\n> \n> @@ -24,27 +107,27 @@ LIBCAMERA_LOG_LEVELS\n> LIBCAMERA_LOG_NO_COLOR\n> Disable coloring of log messages (`more `__).\n> \n> -LIBCAMERA_IPA_CONFIG_PATH\n> +LIBCAMERA_IPA_CONFIG_PATH (ipa.config_paths)\n> Define custom search locations for IPA configurations (`more `__).\n> \n> Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa``\n> \n> -LIBCAMERA_IPA_FORCE_ISOLATION\n> +LIBCAMERA_IPA_FORCE_ISOLATION (ipa.force_isolation)\n> When set to a non-empty string, force process isolation of all IPA modules.\n> \n> Example value: ``1``\n> \n> -LIBCAMERA_IPA_MODULE_PATH\n> +LIBCAMERA_IPA_MODULE_PATH (ipa.module_paths)\n> Define custom search locations for IPA modules (`more `__).\n> \n> Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib``\n> \n> -LIBCAMERA_IPA_PROXY_PATH\n> +LIBCAMERA_IPA_PROXY_PATH (ipa.proxy_paths)\n> Define custom full path for a proxy worker for a given executable name.\n> \n> Example value: ``${HOME}/.libcamera/proxy/worker:/opt/libcamera/vendor/proxy/worker``\n> \n> -LIBCAMERA_PIPELINES_MATCH_LIST\n> +LIBCAMERA_PIPELINES_MATCH_LIST (pipelines_match_list)\n> Define an ordered list of pipeline names to be used to match the media\n> devices in the system. The pipeline handler names used to populate the\n> variable are the ones passed to the REGISTER_PIPELINE_HANDLER() macro in the\n> @@ -55,6 +138,10 @@ LIBCAMERA_PIPELINES_MATCH_LIST\n> LIBCAMERA_RPI_CONFIG_FILE\n> Define a custom configuration file to use in the Raspberry Pi pipeline handler.\n> \n> + Instead of using a separate configuration file, the whole\n> + configuration can be put directly to the global configuration file as\n> + outlined above.\n> +\n> Example value: ``/usr/local/share/libcamera/pipeline/rpi/vc4/minimal_mem.yaml``\n> \n> LIBCAMERA__TUNING_FILE\n> @@ -156,7 +243,7 @@ code.\n> IPA configuration\n> ~~~~~~~~~~~~~~~~~\n> \n> -IPA modules use configuration files to store parameters. The format and\n> +IPA modules use their own configuration files to store parameters. The format and\n> contents of the configuration files is specific to the IPA module. They usually\n> contain tuning parameters for the algorithms, in JSON format.\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id CD7C3C3237\n\tfor ;\n\tFri, 11 Jul 2025 15:28:50 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 8CF4168F1D;\n\tFri, 11 Jul 2025 17:28:50 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id E938268F16\n\tfor ;\n\tFri, 11 Jul 2025 17:28:49 +0200 (CEST)","from [192.168.33.21] (185.221.140.39.nat.pool.zt.hu\n\t[185.221.140.39])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 22F042C5;\n\tFri, 11 Jul 2025 17:28:20 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"SRWkaKVe\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1752247700;\n\tbh=IN+pP5XR6d/ZGW+YGUa1bK/oWl4QH+AMmV4TQLkiTA8=;\n\th=Date:Subject:To:Cc:References:From:In-Reply-To:From;\n\tb=SRWkaKVeGKy1P6WCqDsdoVTsFBEqyAF3VwVUs9IuY8L8GILd2UUSCN1z9Kw4Pzkml\n\thE2+I3wRnSDEZMYyHWzLMRsmXAn49GB2MgfbvO/xnT1H0QE2SXgVqKV3b9DAZkNY+Y\n\tUxnLEyt2A9ki6ZjDwwdQ0XkXJqhCeBFMgU/XckEA=","Message-ID":"<083630f6-b94a-4747-a7b5-c0c618eabdc7@ideasonboard.com>","Date":"Fri, 11 Jul 2025 17:28:46 +0200","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v12 08/12] config: Add global configuration file\n\tdocumentation","To":"Milan Zamazal , libcamera-devel@lists.libcamera.org","Cc":"Kieran Bingham ,\n\tLaurent Pinchart ","References":"<20250702131032.47654-1-mzamazal@redhat.com>\n\t<20250702131032.47654-9-mzamazal@redhat.com>","From":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","Content-Language":"en-US, hu-HU","In-Reply-To":"<20250702131032.47654-9-mzamazal@redhat.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"8bit","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]