idf-build-apps 2.5.3__tar.gz → 2.6.0__tar.gz

{idf_build_apps-2.5.3 → idf_build_apps-2.6.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -17,13 +17,13 @@ repos:
           - --use-current-year
         exclude: 'idf_build_apps/vendors/'
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.6.2'
+    rev: 'v0.8.4'
     hooks:
       - id: ruff
         args: ['--fix']
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.11.2'
+    rev: 'v1.14.1'
     hooks:
       - id: mypy
         args: ['--warn-unused-ignores']
@@ -45,4 +45,5 @@ repos:
         files: "docs\/.+rst$"
         additional_dependencies:
           - sphinx-argparse
+          - sphinx-tabs
           - sphinxcontrib-mermaid

{idf_build_apps-2.5.3 → idf_build_apps-2.6.0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.6.0 (2025-01-02)
+
+### Feat
+
+- `manifest_rootpath` support env vars expansion
+
+### Fix
+
+- DeprecationWarning: 'count' is passed as positional argument when `re.sub`
+- add `py.typed` file to be used in mypy
+- negative value for soc caps integer
+- **config_file**: recursively load config file for TOML file
+
 ## v2.5.3 (2024-10-04)
 
 ### Feat

{idf_build_apps-2.5.3 → idf_build_apps-2.6.0}/CONTRIBUTING.md

@@ -16,12 +16,15 @@ Here's a table shows the supported ESP-IDF versions and the corresponding Python
 | 5.1             | 3.7+                              | main (2.x)              |
 | 5.2             | 3.7+                              | main (2.x)              |
 | 5.3             | 3.8+                              | main (2.x)              |
-| master (5.4)    | 3.8+                              | main (2.x)              |
+| 5.4             | 3.8+                              | main (2.x)              |
+| master (5.5)    | 3.9+                              | main (2.x)              |
 
 `idf-build-apps` is following the semantic versioning. The major version of `idf-build-apps` is the same as the ESP-IDF version it supports. For example, `idf-build-apps` 1.x supports ESP-IDF 4.x, and `idf-build-apps` 2.x supports ESP-IDF 5.x.
 
 In order to compatible to all 5.x ESP-IDF versions, please don't forget to keep the code compatible with python 3.7, even it's end of life on 2023-06-05.
 
+Besides, pydantic dropped 3.7 support since 2.6.0. Don't rely on pydantic 2.6.0+ since we're still supporting python 3.7.
+
 ## Setup the Dev Environment
 
 1. Create virtual environment
@@ -65,7 +68,7 @@ pytest
 We use [sphinx][sphinx] and [autodoc][autodoc] for generating documentation and API references. Besides, we treat warnings as errors while building the documentation. Please fix them before your commits got merged.
 
 ```shell
-cd docs && make html
+cd docs/en && make html
 ```
 
 For documentation preview, you may use any browser you prefer. The executable has to be searchable in `PATH`. For example we're using firefox here.

{idf_build_apps-2.5.3 → idf_build_apps-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: idf-build-apps
-Version: 2.5.3
+Version: 2.6.0
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7
@@ -27,9 +27,10 @@ Requires-Dist: sphinx_copybutton ; extra == "doc"
 Requires-Dist: myst-parser ; extra == "doc"
 Requires-Dist: sphinxcontrib-mermaid ; extra == "doc"
 Requires-Dist: sphinx-argparse ; extra == "doc"
+Requires-Dist: sphinx-tabs ; extra == "doc"
 Requires-Dist: pytest ; extra == "test"
 Requires-Dist: pytest-cov ; extra == "test"
-Project-URL: changelog, https://github.com/espressif/idf-build-apps/blob/master/CHANGELOG.md
+Project-URL: changelog, https://github.com/espressif/idf-build-apps/blob/main/CHANGELOG.md
 Project-URL: documentation, https://docs.espressif.com/projects/idf-build-apps
 Project-URL: homepage, https://github.com/espressif/idf-build-apps
 Project-URL: repository, https://github.com/espressif/idf-build-apps

{idf_build_apps-2.5.3 → idf_build_apps-2.6.0}/docs/conf_common.py

@@ -30,6 +30,7 @@ extensions = [
     'myst_parser',
     'sphinxcontrib.mermaid',
     'sphinxarg.ext',
+    'sphinx_tabs.tabs',
 ]
 
 templates_path = ['_templates']

idf_build_apps-2.6.0/docs/en/references/config_file.rst

@@ -0,0 +1,162 @@
+#############################################
+ Configuration File ``.idf_build_apps.toml``
+#############################################
+
+There are many CLI options available for ``idf-build-apps``. While these options provide usage flexibility, they also make the CLI command too long and difficult to read. However, a configuration file allows defining all these options in a more readable and maintainable way.
+
+***********************
+ Config File Discovery
+***********************
+
+``idf-build-apps`` supports a few ways to specify the configuration file (in order of precedence):
+
+-  specify via CLI argument ``--config-file <config file path>``
+-  ``.idf_build_apps.toml`` in the current directory
+-  ``.idf_build_apps.toml`` in the parent directories, until it reaches the root of the file system
+-  ``pyproject.toml`` with ``[tool.idf-build-apps]`` section
+-  ``pyproject.toml`` in the parent directories, until it reaches the root of the file system
+
+*******
+ Usage
+*******
+
+We recommend using the ``.idf_build_apps.toml`` file for non-Python projects and the ``pyproject.toml`` file for Python projects. When using the ``pyproject.toml`` file, define the configuration options in the ``[tool.idf-build-apps]`` section.
+
+Here's a simple example of a configuration file:
+
+.. tabs::
+
+   .. group-tab::
+
+      ``.idf_build_apps.toml``
+
+      .. code:: toml
+
+         paths = [
+             "components",
+             "examples",
+         ]
+         target = "esp32"
+         recursive = true
+
+         # config rules
+         config = [
+             "sdkconfig.*=",
+             "=default",
+         ]
+
+   .. group-tab::
+
+      ``pyproject.toml``
+
+      .. code:: toml
+
+         [tool.idf-build-apps]
+         paths = [
+             "components",
+             "examples",
+         ]
+         target = "esp32"
+         recursive = true
+
+         # config rules
+         config = [
+             "sdkconfig.*=",
+             "=default",
+         ]
+
+Running ``idf-build-apps build`` with the above configuration is equivalent to the following CLI command:
+
+.. code:: shell
+
+   idf-build-app build \
+     --paths components examples \
+     --target esp32 \
+     --recursive \
+     --config-rules "sdkconfig.*=" "=default" \
+     --build-dir "build_@t_@w"
+
+`TOML <https://toml.io/en/>`__ supports native data types. In order to get the config name and type of the corresponding CLI option, you may refer to the help messages by using ``idf-build-apps find -h`` or ``idf-build-apps build -h``.
+
+For instance, the ``--paths`` CLI option help message shows:
+
+.. code:: text
+
+   -p PATHS [PATHS ...], --paths PATHS [PATHS ...]
+                        One or more paths to look for apps.
+                         - default: None
+                         - config name: paths
+                         - config type: list[str]
+
+This indicates that in the configuration file, you should specify it with the name ``paths``, and the type should be a “list of strings”.
+
+.. code:: toml
+
+   paths = [
+       "foo",
+       "bar",
+   ]
+
+*************************
+ CLI Argument Precedence
+*************************
+
+CLI arguments take precedence over the configuration file. This helps to override the configuration file settings when required.
+
+For example, if the configuration file has the following content:
+
+.. tabs::
+
+   .. group-tab::
+
+      ``.idf_build_apps.toml``
+
+      .. code:: toml
+
+         target = "esp32"
+         config_rules = [
+             "sdkconfig.*=",
+             "=default",
+         ]
+
+   .. group-tab::
+
+      ``pyproject.toml``
+
+      .. code:: toml
+
+         [tool.idf-build-apps]
+         target = "esp32"
+         config_rules = [
+             "sdkconfig.*=",
+             "=default",
+         ]
+
+Override String Configuration
+=============================
+
+To override the ``str`` type configuration, (e.g., ``target``), you can pass the CLI argument directly:
+
+.. code:: shell
+
+   idf-build-apps build --target esp32s2
+
+Override List Configuration
+===========================
+
+To override the ``list[str]`` type configuration, (e.g., ``config_rules``), you can override it by passing the CLI argument. For example:
+
+.. code:: shell
+
+   idf-build-apps build --config-rules "foo=bar"
+
+Or you can unset the configuration by passing an empty string:
+
+.. code:: shell
+
+   idf-build-apps build --config-rules ""
+
+Override Boolean Configuration
+==============================
+
+Not supported yet.

{idf_build_apps-2.5.3 → idf_build_apps-2.6.0}/idf_build_apps/__init__.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
 """
@@ -8,7 +8,7 @@ Tools for building ESP-IDF related apps.
 # ruff: noqa: E402
 # avoid circular imports
 
-__version__ = '2.5.3'
+__version__ = '2.6.0'
 
 from .session_args import (
     SessionArgs,