[{"id":13874,"web_url":"https://patchwork.libcamera.org/comment/13874/","msgid":"<8a060752-0b84-6fa3-32b8-a28ad5c8f3f1@ideasonboard.com>","date":"2020-11-25T10:25:12","subject":"Re: [libcamera-devel] [PATCH v4] Documentation: Add descriptions\n\tfor env. variables","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Hi Sebastian,\n\nOn 20/11/2020 15:52, Sebastian Fricke wrote:\n> Describe the environment variables used in libcamera, excluded\n> variables are `LIBCAMERA_IPA_FORCE_C_API` and `LIBCAMERA_IPA_PROXY_PATH`,\n> the former because it is likely to be removed and the later because\n> it has no current use-case.\n> \n> Add a brief explanation for the IPA configuration and IPA modules.\n> List all the available Log levels and categories and add a short guide\n> on how to use them for debugging.\n> \n> Signed-off-by: Sebastian Fricke <sebastian.fricke.linux@gmail.com>\n> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>\n\nThis is looking like a really good addition, and I've already learnt\nsomething myself from it.\n\nFor the content:\n\nReviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>\n\nWe'll need to look at this to consider how this gets integrated at the\nwebsite documentation. But as the website generator is not public (it\ndiffers from the one in the code base) I can't expect you to do that.\n\n--\nKieran\n\n\n> \n> ---\n> \n> Changes since V3:\n> * Rework the LIBCAMERA_LOG_LEVELS explanation\n> * improve wording at various places\n> * Move the changelog out of the commit description into the email\n> \n> Changes since V2:\n> * replace bullet point list with definition list\n> * Remove the category list as it is too difficult to maintain, instead\n>   explain how the categories are set with the LOG_DECLARE_CATEGORY &\n>   LOG_DEFINE_CATEGORY macros\n> * Remove the short summary for the IPA module, as it can be misleading\n>   and probably not accurate enough\n> * Improve the notes for debugging part by linking to a full explanation\n>   while extending the description in the documentation as well\n> * Add an example for the Log level setting\n> * Remove the documentation from guides and add it to the documentation\n>   base path\n> \n> Changes since V1:\n> * abandon the usage of tables as they are too clunky and difficult to\n> maintain\n> * Fix a wrong example that does not work on most distributions and setups\n> * Improve structure of log categories\n> \n> ---\n> \n>  Documentation/environment_variables.rst | 132 ++++++++++++++++++++++++\n>  Documentation/index.rst                 |   1 +\n>  Documentation/meson.build               |   1 +\n>  3 files changed, 134 insertions(+)\n>  create mode 100644 Documentation/environment_variables.rst\n> \n> diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst\n> new file mode 100644\n> index 0000000..85346af\n> --- /dev/null\n> +++ b/Documentation/environment_variables.rst\n> @@ -0,0 +1,132 @@\n> +Environment variables\n> +=====================\n> +\n> +List of variables\n> +-----------------\n> +\n> +LIBCAMERA_LOG_FILE\n> +   The custom destination for log output.\n> +\n> +   Example value: ``/home/{user}/camera_log.log``\n> +\n> +LIBCAMERA_LOG_LEVELS\n> +   Configure the verbosity of log messages for different categories (`more <#log-levels>`__)\n> +\n> +   Example value: ``*:DEBUG``\n> +\n> +LIBCAMERA_IPA_CONFIG_PATH\n> +   Define custom search locations for IPA configurations (`more <#ipa-configuration>`__)\n> +\n> +   Example value: ``/usr/path/one:/tmp/path/two``\n> +\n> +LIBCAMERA_IPA_MODULE_PATH\n> +   Define custom search locations for IPA modules (`more <#ipa-module>`__)\n> +\n> +   Example value: ``/usr/path/one:/tmp/path/two``\n> +\n> +Further details\n> +---------------\n> +\n> +Notes about debugging\n> +~~~~~~~~~~~~~~~~~~~~~\n> +\n> +The environment variables `LIBCAMERA_LOG_FILE` and `LIBCAMERA_LOG_LEVELS`\n> +are used to modify the destination and verbosity of messages provided by\n> +libcamera.\n> +\n> +The `LIBCAMERA_LOG_LEVELS` variable accepts a comma-separated list of\n> +'category:level' pairs.\n> +\n> +The `level <#log-levels>`__ part is mandatory and can either be\n> +specified by name or by numerical index associated with each level.\n> +\n> +The optional `category <#log-categories>`__ part is a regular\n> +expression, which is matched against the categories defined by each\n> +file in the source base using the logging infrastructure.\n> +\n> +For more information refer to the `API-documentation <http://libcamera.org/api-html/log_8h.html#details>`__\n> +\n> +Examples:\n> +\n> +Enable full debug output to a separate file, for every `category <#log-categories>`__\n> +within a local environment:\n> +\n> +.. code:: bash\n> +\n> +        :~$ LIBCAMERA_LOG_FILE='/tmp/example_log.log' \\\n> +            LIBCAMERA_LOG_LEVELS=0 \\\n> +            cam --list\n\noh wow. I didn't know we could omit the categories. I've always done:\n\tLIBCAMERA_LOG_LEVELS=*:0\n\nEvery day is a school day ';-)\n\n\n> +\n> +Enable full debug output for the categories Camera & V4L2 within a\n> +global environment:\n> +\n> +.. code:: bash\n> +\n> +   :~$ export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,V4L2:DEBUG'\n> +   :~$ cam --list\n> +\n> +Log levels\n> +~~~~~~~~~~~\n> +\n> +This is the list of available log levels, notice that all levels below\n> +the chosen one are printed, while those above are discarded.\n> +\n> +-  DEBUG (0)\n> +-  INFO (1)\n> +-  WARN (2)\n> +-  ERROR (3)\n> +-  FATAL (4)\n> +\n> +Example:\n> +If you choose WARN (2), you will be able to see WARN (2), ERROR (3) & FATAL (4)\n> +but not DEBUG (0) & INFO (1).\n> +\n> +Log categories\n> +~~~~~~~~~~~~~~~\n> +\n> +Every category represents a specific area of the libcamera codebase,\n> +the names can be located within the source code, for example:\n> +`src/libcamera/camera_manager.cpp <https://git.libcamera.org/libcamera/libcamera.git/tree/src/libcamera/camera_manager.cpp#n35>`__\n> +\n> +.. code:: bash\n> +\n> +   LOG_DEFINE_CATEGORY(Camera)\n> +\n> +There are 2 available macros used to assign a category name to a part of the\n> +libcamera codebase:\n> +\n> +LOG_DEFINE_CATEGORY\n> +        This macro is required, in order to use the `LOGC` macro for a\n> +\tparticular category.  It can only be used once for each category.\n> +\tIf you want to create log messages within multiple compilation\n> +\tunits for the same category utilize the `LOG_DECLARE_CATEGORY` macro,\n> +\tin every file except the definition file.\n> +LOG_DECLARE_CATEGORY\n> +        Used for sharing an already defined category in between multiple\n> +\tseparate compilation units.\n> +\n> +Both macros have to be used within the libcamera namespace of the C++ source\n> +code.\n> +\n> +IPA configuration\n> +~~~~~~~~~~~~~~~~~~\n> +\n> +The format and contents of the configuration file are specific to the\n> +IPA (Image Processing Algorithm). It usually contains tuning parameters\n> +for the IPA algorithms stored in JSON format.\n> +The `LIBCAMERA_IPA_CONFIG_PATH` variable can be used to specify custom\n> +storage locations to search for those configuration files.\n> +\n> +`Examples <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa/raspberrypi/data>`__\n> +\n> +IPA module\n> +~~~~~~~~~~~\n> +\n> +In order to locate the correct IPA module for your hardware, libcamera gathers\n> +existing IPA modules from multiple locations. The default locations for this\n> +operation are the installed system path (for example on Debian:\n> +``/usr/local/x86_64-pc-linux-gnu/libcamera``) and the build directory.\n> +With the `LIBCAMERA_IPA_MODULE_PATH`, you can specify a non-default\n> +location to search for IPA modules.\n> +\n> +`Examples for existing IPA modules <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa>`__\n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index ff697d4..c49db18 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -17,3 +17,4 @@\n>     Application Writer's Guide <guides/application-developer>\n>     Pipeline Handler Writer's Guide <guides/pipeline-handler>\n>     Tracing guide <guides/tracing>\n> +   Environment variables <environment_variables>\n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 26a12fc..8086abf 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -53,6 +53,7 @@ if sphinx.found()\n>          'contributing.rst',\n>          'docs.rst',\n>          'index.rst',\n> +        'environment_variables.rst',\n>          'guides/introduction.rst',\n>          'guides/application-developer.rst',\n>          'guides/pipeline-handler.rst',\n>","headers":{"Return-Path":"<libcamera-devel-bounces@lists.libcamera.org>","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 5417ABE08A\n\tfor <parsemail@patchwork.libcamera.org>;\n\tWed, 25 Nov 2020 10:25:18 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id DDBF063407;\n\tWed, 25 Nov 2020 11:25:17 +0100 (CET)","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 A8B8E632EE\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tWed, 25 Nov 2020 11:25:15 +0100 (CET)","from [192.168.0.20]\n\t(cpc89244-aztw30-2-0-cust3082.18-1.cable.virginm.net [86.31.172.11])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 16EF1292;\n\tWed, 25 Nov 2020 11:25:15 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"CrWxei0u\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1606299915;\n\tbh=YQBvBwjuL+/vqln0jTegxRZpoJQlpzXBmK+1kIkaqGA=;\n\th=Reply-To:Subject:To:References:From:Date:In-Reply-To:From;\n\tb=CrWxei0uhQ35gZlIvxTmXuc2EqHNA12uOtVNUkn+RpOUpq6hExeEF9moVNPaERTCY\n\tNrfg3/XA5wa7Z4nZAAFOMGAEVciXIGgxe8RkOLhH79OMLVg9Q+2As2rU8XIssnVYuU\n\t9esPOKFmR4k6wdWZf+/uJzc1VJ/tqwxx5RqR9IZY=","To":"Sebastian Fricke <sebastian.fricke.linux@gmail.com>,\n\tlibcamera-devel@lists.libcamera.org","References":"<20201120155234.29903-1-sebastian.fricke.linux@gmail.com>","From":"Kieran Bingham <kieran.bingham@ideasonboard.com>","Autocrypt":"addr=kieran.bingham@ideasonboard.com; keydata=\n\tmQINBFYE/WYBEACs1PwjMD9rgCu1hlIiUA1AXR4rv2v+BCLUq//vrX5S5bjzxKAryRf0uHat\n\tV/zwz6hiDrZuHUACDB7X8OaQcwhLaVlq6byfoBr25+hbZG7G3+5EUl9cQ7dQEdvNj6V6y/SC\n\trRanWfelwQThCHckbobWiQJfK9n7rYNcPMq9B8e9F020LFH7Kj6YmO95ewJGgLm+idg1Kb3C\n\tpotzWkXc1xmPzcQ1fvQMOfMwdS+4SNw4rY9f07Xb2K99rjMwZVDgESKIzhsDB5GY465sCsiQ\n\tcSAZRxqE49RTBq2+EQsbrQpIc8XiffAB8qexh5/QPzCmR4kJgCGeHIXBtgRj+nIkCJPZvZtf\n\tKr2EAbc6tgg6DkAEHJb+1okosV09+0+TXywYvtEop/WUOWQ+zo+Y/OBd+8Ptgt1pDRyOBzL8\n\tRXa8ZqRf0Mwg75D+dKntZeJHzPRJyrlfQokngAAs4PaFt6UfS+ypMAF37T6CeDArQC41V3ko\n\tlPn1yMsVD0p+6i3DPvA/GPIksDC4owjnzVX9kM8Zc5Cx+XoAN0w5Eqo4t6qEVbuettxx55gq\n\t8K8FieAjgjMSxngo/HST8TpFeqI5nVeq0/lqtBRQKumuIqDg+Bkr4L1V/PSB6XgQcOdhtd36\n\tOe9X9dXB8YSNt7VjOcO7BTmFn/Z8r92mSAfHXpb07YJWJosQOQARAQABtDBLaWVyYW4gQmlu\n\tZ2hhbSA8a2llcmFuLmJpbmdoYW1AaWRlYXNvbmJvYXJkLmNvbT6JAlcEEwEKAEECGwMFCwkI\n\tBwIGFQgJCgsCBBYCAwECHgECF4ACGQEWIQSQLdeYP70o/eNy1HqhHkZyEKRh/QUCXWTtygUJ\n\tCyJXZAAKCRChHkZyEKRh/f8dEACTDsbLN2nioNZMwyLuQRUAFcXNolDX48xcUXsWS2QjxaPm\n\tVsJx8Uy8aYkS85mdPBh0C83OovQR/OVbr8AxhGvYqBs3nQvbWuTl/+4od7DfK2VZOoKBAu5S\n\tQK2FYuUcikDqYcFWJ8DQnubxfE8dvzojHEkXw0sA4igINHDDFX3HJGZtLio+WpEFQtCbfTAG\n\tYZslasz1YZRbwEdSsmO3/kqy5eMnczlm8a21A3fKUo3g8oAZEFM+f4DUNzqIltg31OAB/kZS\n\tenKZQ/SWC8PmLg/ZXBrReYakxXtkP6w3FwMlzOlhGxqhIRNiAJfXJBaRhuUWzPOpEDE9q5YJ\n\tBmqQL2WJm1VSNNVxbXJHpaWMH1sA2R00vmvRrPXGwyIO0IPYeUYQa3gsy6k+En/aMQJd27dp\n\taScf9am9PFICPY5T4ppneeJLif2lyLojo0mcHOV+uyrds9XkLpp14GfTkeKPdPMrLLTsHRfH\n\tfA4I4OBpRrEPiGIZB/0im98MkGY/Mu6qxeZmYLCcgD6qz4idOvfgVOrNh+aA8HzIVR+RMW8H\n\tQGBN9f0E3kfwxuhl3omo6V7lDw8XOdmuWZNC9zPq1UfryVHANYbLGz9KJ4Aw6M+OgBC2JpkD\n\thXMdHUkC+d20dwXrwHTlrJi1YNp6rBc+xald3wsUPOZ5z8moTHUX/uPA/qhGsbkCDQRWBP1m\n\tARAAzijkb+Sau4hAncr1JjOY+KyFEdUNxRy+hqTJdJfaYihxyaj0Ee0P0zEi35CbE6lgU0Uz\n\ttih9fiUbSV3wfsWqg1Ut3/5rTKu7kLFp15kF7eqvV4uezXRD3Qu4yjv/rMmEJbbD4cTvGCYI\n\td6MDC417f7vK3hCbCVIZSp3GXxyC1LU+UQr3fFcOyCwmP9vDUR9JV0BSqHHxRDdpUXE26Dk6\n\tmhf0V1YkspE5St814ETXpEus2urZE5yJIUROlWPIL+hm3NEWfAP06vsQUyLvr/GtbOT79vXl\n\tEn1aulcYyu20dRRxhkQ6iILaURcxIAVJJKPi8dsoMnS8pB0QW12AHWuirPF0g6DiuUfPmrA5\n\tPKe56IGlpkjc8cO51lIxHkWTpCMWigRdPDexKX+Sb+W9QWK/0JjIc4t3KBaiG8O4yRX8ml2R\n\t+rxfAVKM6V769P/hWoRGdgUMgYHFpHGSgEt80OKK5HeUPy2cngDUXzwrqiM5Sz6Od0qw5pCk\n\tNlXqI0W/who0iSVM+8+RmyY0OEkxEcci7rRLsGnM15B5PjLJjh1f2ULYkv8s4SnDwMZ/kE04\n\t/UqCMK/KnX8pwXEMCjz0h6qWNpGwJ0/tYIgQJZh6bqkvBrDogAvuhf60Sogw+mH8b+PBlx1L\n\toeTK396wc+4c3BfiC6pNtUS5GpsPMMjYMk7kVvEAEQEAAYkCPAQYAQoAJgIbDBYhBJAt15g/\n\tvSj943LUeqEeRnIQpGH9BQJdizzIBQkLSKZiAAoJEKEeRnIQpGH9eYgQAJpjaWNgqNOnMTmD\n\tMJggbwjIotypzIXfhHNCeTkG7+qCDlSaBPclcPGYrTwCt0YWPU2TgGgJrVhYT20ierN8LUvj\n\t6qOPTd+Uk7NFzL65qkh80ZKNBFddx1AabQpSVQKbdcLb8OFs85kuSvFdgqZwgxA1vl4TFhNz\n\tPZ79NAmXLackAx3sOVFhk4WQaKRshCB7cSl+RIng5S/ThOBlwNlcKG7j7W2MC06BlTbdEkUp\n\tECzuuRBv8wX4OQl+hbWbB/VKIx5HKlLu1eypen/5lNVzSqMMIYkkZcjV2SWQyUGxSwq0O/sx\n\tS0A8/atCHUXOboUsn54qdxrVDaK+6jIAuo8JiRWctP16KjzUM7MO0/+4zllM8EY57rXrj48j\n\tsbEYX0YQnzaj+jO6kJtoZsIaYR7rMMq9aUAjyiaEZpmP1qF/2sYenDx0Fg2BSlLvLvXM0vU8\n\tpQk3kgDu7kb/7PRYrZvBsr21EIQoIjXbZxDz/o7z95frkP71EaICttZ6k9q5oxxA5WC6sTXc\n\tMW8zs8avFNuA9VpXt0YupJd2ijtZy2mpZNG02fFVXhIn4G807G7+9mhuC4XG5rKlBBUXTvPU\n\tAfYnB4JBDLmLzBFavQfvonSfbitgXwCG3vS+9HEwAjU30Bar1PEOmIbiAoMzuKeRm2LVpmq4\n\tWZw01QYHU/GUV/zHJSFk","Organization":"Ideas on Board","Message-ID":"<8a060752-0b84-6fa3-32b8-a28ad5c8f3f1@ideasonboard.com>","Date":"Wed, 25 Nov 2020 10:25:12 +0000","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101\n\tThunderbird/68.10.0","MIME-Version":"1.0","In-Reply-To":"<20201120155234.29903-1-sebastian.fricke.linux@gmail.com>","Content-Language":"en-GB","Subject":"Re: [libcamera-devel] [PATCH v4] Documentation: Add descriptions\n\tfor env. variables","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","Reply-To":"kieran.bingham@ideasonboard.com","Content-Type":"text/plain; charset=\"us-ascii\"","Content-Transfer-Encoding":"7bit","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>"}},{"id":14332,"web_url":"https://patchwork.libcamera.org/comment/14332/","msgid":"<X+Z4HbtsNb3XDPtp@pendragon.ideasonboard.com>","date":"2020-12-25T23:39:09","subject":"Re: [libcamera-devel] [PATCH v4] Documentation: Add descriptions\n\tfor env. variables","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Sebastian,\n\nThank you for the patch, and sorry for the very late review. We've\nrecently installed a patchwork instance for libcamera, so now I can\ntrack all the patches I need to take care of. Hopefully it will avoid\nsuch delays in the future.\n\nThe change looks good. I have a few minor comments. If you're OK with\nthem, I'll address them when applying the patch and you won't have to\nsend a v5.\n\nYou can spell \"environment\" in full in the subject line.\n\nOn Fri, Nov 20, 2020 at 04:52:34PM +0100, Sebastian Fricke wrote:\n> Describe the environment variables used in libcamera, excluded\n> variables are `LIBCAMERA_IPA_FORCE_C_API` and `LIBCAMERA_IPA_PROXY_PATH`,\n> the former because it is likely to be removed and the later because\n> it has no current use-case.\n> \n> Add a brief explanation for the IPA configuration and IPA modules.\n> List all the available Log levels and categories and add a short guide\n> on how to use them for debugging.\n> \n> Signed-off-by: Sebastian Fricke <sebastian.fricke.linux@gmail.com>\n> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>\n> \n> ---\n> \n> Changes since V3:\n> * Rework the LIBCAMERA_LOG_LEVELS explanation\n> * improve wording at various places\n> * Move the changelog out of the commit description into the email\n> \n> Changes since V2:\n> * replace bullet point list with definition list\n> * Remove the category list as it is too difficult to maintain, instead\n>   explain how the categories are set with the LOG_DECLARE_CATEGORY &\n>   LOG_DEFINE_CATEGORY macros\n> * Remove the short summary for the IPA module, as it can be misleading\n>   and probably not accurate enough\n> * Improve the notes for debugging part by linking to a full explanation\n>   while extending the description in the documentation as well\n> * Add an example for the Log level setting\n> * Remove the documentation from guides and add it to the documentation\n>   base path\n> \n> Changes since V1:\n> * abandon the usage of tables as they are too clunky and difficult to\n> maintain\n> * Fix a wrong example that does not work on most distributions and setups\n> * Improve structure of log categories\n> \n> ---\n> \n>  Documentation/environment_variables.rst | 132 ++++++++++++++++++++++++\n>  Documentation/index.rst                 |   1 +\n>  Documentation/meson.build               |   1 +\n>  3 files changed, 134 insertions(+)\n>  create mode 100644 Documentation/environment_variables.rst\n> \n> diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst\n> new file mode 100644\n> index 0000000..85346af\n> --- /dev/null\n> +++ b/Documentation/environment_variables.rst\n> @@ -0,0 +1,132 @@\n\nThis is missing license information. To match the rest of the\ndocumentation, it should be\n\n.. SPDX-License-Identifier: CC-BY-SA-4.0\n\n> +Environment variables\n> +=====================\n\nHow about a short introduction ? I can propose\n\nThe libcamera behaviour can be tuned through environment variables. This\ndocument lists all the available variables and describes their usage.\n\n> +\n> +List of variables\n> +-----------------\n> +\n> +LIBCAMERA_LOG_FILE\n> +   The custom destination for log output.\n> +\n> +   Example value: ``/home/{user}/camera_log.log``\n> +\n> +LIBCAMERA_LOG_LEVELS\n> +   Configure the verbosity of log messages for different categories (`more <#log-levels>`__)\n\nNitpicking, I'd add a period at the end of the sentence, as the previous\nvariable has one. Same below.\n\n> +\n> +   Example value: ``*:DEBUG``\n> +\n> +LIBCAMERA_IPA_CONFIG_PATH\n> +   Define custom search locations for IPA configurations (`more <#ipa-configuration>`__)\n> +\n> +   Example value: ``/usr/path/one:/tmp/path/two``\n\nHow about a bit more realistic example ?\n\n    Example value: ``${HOME}/.libcamera/share/ipa:/opt/libcamera/vendor/share/ipa``\n\n> +\n> +LIBCAMERA_IPA_MODULE_PATH\n> +   Define custom search locations for IPA modules (`more <#ipa-module>`__)\n> +\n> +   Example value: ``/usr/path/one:/tmp/path/two``\n\nAnd here,\n\n    Example value: ``${HOME}/.libcamera/lib:/opt/libcamera/vendor/lib``\n\n> +\n> +Further details\n> +---------------\n> +\n> +Notes about debugging\n> +~~~~~~~~~~~~~~~~~~~~~\n> +\n> +The environment variables `LIBCAMERA_LOG_FILE` and `LIBCAMERA_LOG_LEVELS`\n> +are used to modify the destination and verbosity of messages provided by\n> +libcamera.\n> +\n> +The `LIBCAMERA_LOG_LEVELS` variable accepts a comma-separated list of\n> +'category:level' pairs.\n> +\n> +The `level <#log-levels>`__ part is mandatory and can either be\n> +specified by name or by numerical index associated with each level.\n> +\n> +The optional `category <#log-categories>`__ part is a regular\n> +expression, which is matched against the categories defined by each\n> +file in the source base using the logging infrastructure.\n\nIt's not a full regular expression, only a string with an optional *\nwildcard match at the end. How about\n\nThe optional `category <#log-categories>`__ is a string matching the categories\ndefined by each file in the source base using the logging infrastructure. It\ncan include a wildcard ('*') character at the end to match multiple categories.\n\n> +\n> +For more information refer to the `API-documentation <http://libcamera.org/api-html/log_8h.html#details>`__\n\nMaybe s/API-documentation/API documentation/ ?\n\nThis should also have a trailing period.\n\n> +\n> +Examples:\n> +\n> +Enable full debug output to a separate file, for every `category <#log-categories>`__\n> +within a local environment:\n> +\n> +.. code:: bash\n> +\n> +        :~$ LIBCAMERA_LOG_FILE='/tmp/example_log.log' \\\n> +            LIBCAMERA_LOG_LEVELS=0 \\\n> +            cam --list\n\nYou can reduce the indentation to match the other examples below.\n\n> +\n> +Enable full debug output for the categories Camera & V4L2 within a\n\nHow about writing\n\n\t[...] categories `Camera` and `V4L2` within [...]\n\nto emphasize both terms ?\n\n> +global environment:\n> +\n> +.. code:: bash\n> +\n> +   :~$ export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,V4L2:DEBUG'\n> +   :~$ cam --list\n> +\n> +Log levels\n> +~~~~~~~~~~~\n\nThere's an extra ~ here. Same in a few locations below.\n\n> +\n> +This is the list of available log levels, notice that all levels below\n> +the chosen one are printed, while those above are discarded.\n> +\n> +-  DEBUG (0)\n> +-  INFO (1)\n> +-  WARN (2)\n> +-  ERROR (3)\n> +-  FATAL (4)\n> +\n> +Example:\n> +If you choose WARN (2), you will be able to see WARN (2), ERROR (3) & FATAL (4)\n> +but not DEBUG (0) & INFO (1).\n\n'and' would be better than '&' in text I think.\n\n> +\n> +Log categories\n> +~~~~~~~~~~~~~~~\n> +\n> +Every category represents a specific area of the libcamera codebase,\n> +the names can be located within the source code, for example:\n> +`src/libcamera/camera_manager.cpp <https://git.libcamera.org/libcamera/libcamera.git/tree/src/libcamera/camera_manager.cpp#n35>`__\n> +\n> +.. code:: bash\n\nThis is C++ code :-)\n\n> +\n> +   LOG_DEFINE_CATEGORY(Camera)\n> +\n> +There are 2 available macros used to assign a category name to a part of the\n\ns/2/two/\n\n> +libcamera codebase:\n> +\n> +LOG_DEFINE_CATEGORY\n> +        This macro is required, in order to use the `LOGC` macro for a\n\nIsn't this LOG, not LOGC ?\n\n> +\tparticular category.  It can only be used once for each category.\n\nShould we avoid mixing tabs and spaces for indentation ?\n\n> +\tIf you want to create log messages within multiple compilation\n> +\tunits for the same category utilize the `LOG_DECLARE_CATEGORY` macro,\n> +\tin every file except the definition file.\n> +LOG_DECLARE_CATEGORY\n> +        Used for sharing an already defined category in between multiple\n\ns/in between/between/\n\n> +\tseparate compilation units.\n> +\n> +Both macros have to be used within the libcamera namespace of the C++ source\n> +code.\n> +\n> +IPA configuration\n> +~~~~~~~~~~~~~~~~~~\n> +\n> +The format and contents of the configuration file are specific to the\n> +IPA (Image Processing Algorithm). It usually contains tuning parameters\n> +for the IPA algorithms stored in JSON format.\n\nNothing above mentions an IPA configuration file, it could be useful to\nintroduce the concept. How about the following ?\n\nIPA modules use configuration files to store parameters. The format and\ncontents of the configuration files is specific to the IPA module. They\nusually contain tuning parameters for the algorithms, in JSON format.\n\n> +The `LIBCAMERA_IPA_CONFIG_PATH` variable can be used to specify custom\n> +storage locations to search for those configuration files.\n> +\n> +`Examples <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa/raspberrypi/data>`__\n> +\n> +IPA module\n> +~~~~~~~~~~~\n> +\n> +In order to locate the correct IPA module for your hardware, libcamera gathers\n\ns/your/the/\n\n> +existing IPA modules from multiple locations. The default locations for this\n> +operation are the installed system path (for example on Debian:\n> +``/usr/local/x86_64-pc-linux-gnu/libcamera``) and the build directory.\n> +With the `LIBCAMERA_IPA_MODULE_PATH`, you can specify a non-default\n> +location to search for IPA modules.\n> +\n> +`Examples for existing IPA modules <https://git.libcamera.org/libcamera/libcamera.git/tree/src/ipa>`__\n\nI'm confused by the example. It points to the source directory for IPA\nmodules, which doesn't really tell me what an example would be for this\nenvironment variable. I'd propose dropping it, as there's already an\nexample above.\n\n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index ff697d4..c49db18 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -17,3 +17,4 @@\n>     Application Writer's Guide <guides/application-developer>\n>     Pipeline Handler Writer's Guide <guides/pipeline-handler>\n>     Tracing guide <guides/tracing>\n> +   Environment variables <environment_variables>\n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 26a12fc..8086abf 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -53,6 +53,7 @@ if sphinx.found()\n>          'contributing.rst',\n>          'docs.rst',\n>          'index.rst',\n> +        'environment_variables.rst',\n\nThis should go before index.rst to keep the alphabetical order (which I\nnow realize is broken by the guides/ directory).\n\n>          'guides/introduction.rst',\n>          'guides/application-developer.rst',\n>          'guides/pipeline-handler.rst',","headers":{"Return-Path":"<libcamera-devel-bounces@lists.libcamera.org>","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 1EC61C0F1B\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri, 25 Dec 2020 23:39:22 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 96B9561591;\n\tSat, 26 Dec 2020 00:39:21 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 0E5F560526\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tSat, 26 Dec 2020 00:39:20 +0100 (CET)","from pendragon.ideasonboard.com (62-78-145-57.bb.dnainternet.fi\n\t[62.78.145.57])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 5E2A980B;\n\tSat, 26 Dec 2020 00:39:19 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"Ft9jBycp\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1608939559;\n\tbh=AM81nGjfqVSfVSRrbvTPbXvm8Xe4ADb1vd9OHzzbjfA=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=Ft9jBycpKqbfEr/3qU0/9nagVa3AOvYROfA/m1HBAjVLluITG0NXgA3tdEUvnMtnN\n\tQ5G1GjBAXE/MLlqHOHdn2z4ExW36lbRGKP7ZZwbSxRxn4SuugRyghafGK9Y4MjyfNx\n\tTASTIlJ5EG55ilmOH016N7zRI/4EmfzBw2yfZWvI=","Date":"Sat, 26 Dec 2020 01:39:09 +0200","From":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","To":"Sebastian Fricke <sebastian.fricke.linux@gmail.com>","Message-ID":"<X+Z4HbtsNb3XDPtp@pendragon.ideasonboard.com>","References":"<20201120155234.29903-1-sebastian.fricke.linux@gmail.com>","MIME-Version":"1.0","Content-Disposition":"inline","In-Reply-To":"<20201120155234.29903-1-sebastian.fricke.linux@gmail.com>","Subject":"Re: [libcamera-devel] [PATCH v4] Documentation: Add descriptions\n\tfor env. variables","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","Cc":"libcamera-devel@lists.libcamera.org","Content-Type":"text/plain; charset=\"us-ascii\"","Content-Transfer-Encoding":"7bit","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>"}}]