idf-build-apps 2.3.1__tar.gz → 2.4.1.dev0__tar.gz

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/.pre-commit-config.yaml

@@ -35,3 +35,5 @@ repos:
           - types-PyYAML
           - types-toml
           - pytest<8  # 8.0.0 does not support python 3.7
+          - argcomplete>=3
+          - annotated_types<0.7.0 # 0.7.0 does not support python 3.7

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.4.1.dev0 (2024-06-17)
+
+### Fix
+
+- use esp32c5 mp as default path
+
+## v2.4.0 (2024-06-17)
+
+### Feat
+
+- support esp32c5 soc header
+- **cli**: add CLI autocompletions
+
 ## v2.3.1 (2024-04-22)
 
 ### Fix

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: idf-build-apps
-Version: 2.3.1
+Version: 2.4.1.dev0
 Summary: Tools for building ESP-IDF related apps.
 Author-email: Fu Hanxi <fuhanxi@espressif.com>
 Requires-Python: >=3.7
@@ -18,6 +18,7 @@ Requires-Dist: pyyaml
 Requires-Dist: packaging
 Requires-Dist: toml; python_version < '3.11'
 Requires-Dist: pydantic~=2.0
+Requires-Dist: argcomplete>=3
 Requires-Dist: typing-extensions ; extra == "dev" and ( python_version < '3.8')
 Requires-Dist: sphinx ; extra == "doc"
 Requires-Dist: sphinx-rtd-theme ; extra == "doc"
@@ -68,10 +69,11 @@ pipx install idf-build-apps
 
 `idf-build-apps` is a python package that could be used as a library or a CLI tool.
 
-As a CLI tool, it contains two sub-commands.
+As a CLI tool, it contains three sub-commands.
 
 - `find` to find the buildable applications
 - `build` to build the found applications
+- `completions` to activate autocompletions or print instructions for manual activation
 
 For detailed explanation to all CLI options, you may run
 
@@ -79,6 +81,7 @@ For detailed explanation to all CLI options, you may run
 idf-build-apps -h
 idf-build-apps find -h
 idf-build-apps build -h
+idf-build-apps completions -h
 ```
 
 As a library, you may check the [API documentation][api-doc] for more information. Overall it provides

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/README.md

@@ -31,10 +31,11 @@ pipx install idf-build-apps
 
 `idf-build-apps` is a python package that could be used as a library or a CLI tool.
 
-As a CLI tool, it contains two sub-commands.
+As a CLI tool, it contains three sub-commands.
 
 - `find` to find the buildable applications
 - `build` to build the found applications
+- `completions` to activate autocompletions or print instructions for manual activation
 
 For detailed explanation to all CLI options, you may run
 
@@ -42,6 +43,7 @@ For detailed explanation to all CLI options, you may run
 idf-build-apps -h
 idf-build-apps find -h
 idf-build-apps build -h
+idf-build-apps completions -h
 ```
 
 As a library, you may check the [API documentation][api-doc] for more information. Overall it provides

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/docs/manifest.md

@@ -19,6 +19,33 @@ One typical manifest file look like this:
     - ...
 ```
 
+## Terms
+
+### Supported Targets
+
+This refers to the targets that are fully supported by the ESP-IDF project. You may check the supported targets by running `idf.py --list-targets`.
+
+`idf-build-apps` will get this information dynamically from your `$IDF_PATH`. For ESP-IDF release 5.3, the supported targets are:
+
+- esp32
+- esp32s2
+- esp32c3
+- esp32s3
+- esp32c2
+- esp32c6
+- esp32h2
+- esp32p4
+
+### Preview Targets
+
+This refers to the targets that are still in preview status. You may check the preview targets by running `idf.py --list-targets --preview`.
+
+`idf-build-apps` will get this information dynamically from your `$IDF_PATH`. For ESP-IDF release 5.3, the preview targets are:
+
+- linux
+- esp32c5
+- esp32c61
+
 ## `if` Clauses
 
 ### Operands
@@ -30,7 +57,7 @@ One typical manifest file look like this:
   - `IDF_VERSION_MAJOR`
   - `IDF_VERSION_MINOR`
   - `IDF_VERSION_PATCH`
-  - `INCLUDE_DEFAULT` (The default value of officially supported targets is 1, otherwise is 0)
+  - `INCLUDE_DEFAULT` (The default value of supported targets is 1, and the default value of preview targets is 0)
   - `CONFIG_NAME` (config name defined in [](project:#config-rules))
   - environment variables, default to `0` if not set
 - String, must be double-quoted. e.g., `"esp32"`, `"12345"`
@@ -53,7 +80,9 @@ All operators are binary operators. For more than two operands, you may use the
 
 ## Enable/Disable Rules
 
-By default, we enable build and test for all supported targets. In other words, if an app supports all supported targets, it does not need to be added in a manifest file. The manifest files are files that set the violation rules for apps.
+By default, we enable build and test for all supported targets. In other words, all preview targets are disabled.
+
+To simplify the manifest file, if an app needs to be build and tested on all supported targets, it does not need to be added in a manifest file. The manifest files are files that set the violation rules for apps.
 
 Three rules (disable rules are calculated after the `enable` rule):
 - `enable`: run CI build/test jobs for targets that match any of the specified conditions only

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/idf_build_apps/__init__.py

@@ -8,7 +8,7 @@ Tools for building ESP-IDF related apps.
 # ruff: noqa: E402
 # avoid circular imports
 
-__version__ = '2.3.1'
+__version__ = '2.4.1.dev0'
 
 from .session_args import (
     SessionArgs,

idf_build_apps-2.4.1.dev0/idf_build_apps/autocompletions.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+from typing import Optional
+
+from .utils import AutocompleteActivationError
+
+
+def append_to_file(file_path: str, content: str) -> None:
+    """Add commands to shell configuration file
+
+    :param file_path: path to shell configurations file
+    :param content: commands to add
+    """
+    if os.path.exists(file_path):
+        with open(file_path) as file:
+            if content.strip() in file.read():
+                print(f'Autocompletion already set up in {file_path}')
+                return
+    with open(file_path, 'a') as file:
+        file.write(f'\n# Begin added by idf-build-apps \n{content} \n# End added by idf-build-apps')
+    print(f'Autocompletion added to {file_path}')
+
+
+def activate_completions(shell_type: Optional[str]) -> None:
+    """Activates autocompletion for supported shells.
+
+    :raises AutocompleteActivationError: if the $SHELL env variable is empty, or if the detected shell is unsupported.
+    """
+    supported_shells = ['bash', 'zsh', 'fish']
+
+    if shell_type == 'auto':
+        shell_type = os.path.basename(os.environ.get('SHELL', ''))
+
+    if not shell_type:
+        raise AutocompleteActivationError('$SHELL is empty. Please provide your shell type with the `--shell` option')
+
+    if shell_type not in supported_shells:
+        raise AutocompleteActivationError('Unsupported shell. Autocompletion is supported for bash, zsh and fish.')
+
+    if shell_type == 'bash':
+        completion_command = 'eval "$(register-python-argcomplete idf-build-apps)"'
+    elif shell_type == 'zsh':
+        completion_command = (
+            'autoload -U bashcompinit && bashcompinit && eval "$(register-python-argcomplete idf-build-apps)"'
+        )
+    elif shell_type == 'fish':
+        completion_command = 'register-python-argcomplete --shell fish idf-build-apps | source'
+
+    rc_file = {'bash': '~/.bashrc', 'zsh': '~/.zshrc', 'fish': '~/.config/fish/completions/idf-build-apps.fish'}
+
+    shell_rc = os.path.expanduser(rc_file[shell_type])
+    append_to_file(shell_rc, completion_command)

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/idf_build_apps/constants.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
 import enum
@@ -95,3 +95,37 @@ class BuildStage(str, enum.Enum):
     @classmethod
     def max_length(cls) -> int:
         return max(len(v.value) for v in cls.__members__.values())
+
+
+completion_instructions = """
+With `--activate` option detect your shell type and add the appropriate commands to your shell's config file
+so that it is run on startup. You will likely have to restart
+or re-login for the autocompletion to start working.
+
+You can also specify your shell by the `--shell` option.
+
+If you do not want automaticall modifying your shell config file
+you can manually add commands provided below to activate autocompletion
+or run them in your current terminal session for one-time activation.
+
+Once again, you will likely have to restart
+or re-login for the autocompletion to start working.
+
+bash:
+    eval "$(register-python-argcomplete idf-build-apps)"
+
+zsh:
+    To activate completions in zsh, first make sure compinit is marked for
+    autoload and run autoload:
+
+    autoload -U compinit
+    compinit
+
+    Afterwards you can enable completions for idf-build-apps:
+
+    eval "$(register-python-argcomplete idf-build-apps)"
+
+fish:
+    # Not required to be in the config file, only run once
+    register-python-argcomplete --shell fish idf-build-apps >~/.config/fish/completions/idf-build-apps.fish
+"""

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/idf_build_apps/main.py

@@ -1,3 +1,5 @@
+# PYTHON_ARGCOMPLETE_OK
+
 # SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
@@ -10,6 +12,7 @@ import sys
 import textwrap
 import typing as t
 
+import argcomplete
 from pydantic import (
     Field,
     create_model,
@@ -24,16 +27,14 @@ from .app import (
     CMakeApp,
     MakeApp,
 )
+from .autocompletions import activate_completions
 from .build_apps_args import (
     BuildAppsArgs,
 )
 from .config import (
     get_valid_config,
 )
-from .constants import (
-    ALL_TARGETS,
-    BuildStatus,
-)
+from .constants import ALL_TARGETS, BuildStatus, completion_instructions
 from .finder import (
     _find_apps,
 )
@@ -50,6 +51,7 @@ from .manifest.manifest import (
     Manifest,
 )
 from .utils import (
+    AutocompleteActivationError,
     InvalidCommand,
     files_matches_patterns,
     get_parallel_start_stop,
@@ -606,10 +608,27 @@ def get_parser() -> argparse.ArgumentParser:
         help='enable colored output by default on UNIX-like systems. enable this flag to make the logs uncolored.',
     )
 
-    find_parser = actions.add_parser('find', parents=[common_args], formatter_class=IdfBuildAppsCliFormatter)
+    find_parser = actions.add_parser(
+        'find',
+        help='Find the buildable applications. Run `idf-build-apps find --help` for more information on a command',
+        description='Find the buildable applications in the given path or paths for specified chips. '
+        '`--path` and `--target` options must be provided. '
+        'By default, print the found apps in stdout. '
+        'To find apps for all chips use the `--target` option with the `all` argument.',
+        parents=[common_args],
+        formatter_class=IdfBuildAppsCliFormatter,
+    )
+
     find_parser.add_argument('-o', '--output', help='Print the found apps to the specified file instead of stdout')
 
-    build_parser = actions.add_parser('build', parents=[common_args], formatter_class=IdfBuildAppsCliFormatter)
+    build_parser = actions.add_parser(
+        'build',
+        help='Build the found applications. Run `idf-build-apps build --help` for more information on a command',
+        description='Build the application in the given path or paths for specified chips. '
+        '`--path` and `--target` options must be provided.',
+        parents=[common_args],
+        formatter_class=IdfBuildAppsCliFormatter,
+    )
     build_parser.add_argument(
         '--build-verbose',
         action='store_true',
@@ -674,14 +693,48 @@ def get_parser() -> argparse.ArgumentParser:
         help='Path to the junitxml file. If specified, the junitxml file will be generated. Can expand placeholder @p',
     )
 
+    completions_parser = actions.add_parser(
+        'completions',
+        help='Add the autocompletion activation script to the shell rc file. '
+        'Run `idf-build-apps complations --help` for more information on a command',
+        description='Without `--activate` option print instructions for manual activation. '
+        'With `--activate` option add the autocompletion activation script to the shell rc file '
+        'for bash, zsh, or fish. Other shells are not supported. '
+        'The `--shell` option used only with the `--activate` option, '
+        'if provided, add the autocompletion activation script to the given shell; '
+        'without this argument, will detect shell type automatically. '
+        'May need to restart or re-login for the autocompletion to start working',
+        formatter_class=IdfBuildAppsCliFormatter,
+    )
+    completions_parser.add_argument(
+        '-a', '--activate', action='store_true', help='Activate autocompletion automatically and permanently'
+    )
+    completions_parser.add_argument(
+        '-s',
+        '--shell',
+        choices=['bash', 'zsh', 'fish'],
+        help='Specify the shell type for the autocomplite activation script. ',
+    )
+
     return parser
 
 
+def handle_completions(args: argparse.Namespace) -> None:
+    if args.activate:
+        if not args.shell:
+            args.shell = 'auto'
+        activate_completions(args.shell)
+    elif not args.activate and args.shell:
+        raise AutocompleteActivationError('The --shell option can only be used with the --activate option.')
+    else:
+        print(completion_instructions)
+
+
 def validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
     # validate cli subcommands
-    if args.action not in ['find', 'build']:
+    if args.action not in ['find', 'build', 'completions']:
         parser.print_help()
-        raise InvalidCommand('subcommand is required. {find, build}')
+        raise InvalidCommand('subcommand is required. {find, build, completions}')
 
     if not args.paths:
         raise InvalidCommand(
@@ -728,8 +781,13 @@ def apply_config_args(args: argparse.Namespace) -> None:
 
 def main():
     parser = get_parser()
+    argcomplete.autocomplete(parser)
     args = parser.parse_args()
 
+    if args.action == 'completions':
+        handle_completions(args)
+        sys.exit(0)
+
     apply_config_args(args)
     validate_args(parser, args)
 

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/idf_build_apps/manifest/soc_header.py

@@ -82,35 +82,41 @@ class SocHeader(dict):
         super().__init__(**soc_header_dict)
 
     @staticmethod
-    def _get_dir_from_candidates(candidates: t.List[str]) -> t.Optional[str]:
+    def _get_dirs_from_candidates(candidates: t.List[str]) -> t.List[str]:
+        dirs = []
         for d in candidates:
             if not os.path.isdir(d):
                 LOGGER.debug('folder "%s" not found. Skipping...', os.path.abspath(d))
             else:
-                return d
+                dirs.append(d)
 
-        return None
+        return dirs
 
     @classmethod
     def _parse_soc_header(cls, target: str) -> t.Dict[str, t.Any]:
-        soc_headers_dir = cls._get_dir_from_candidates([
+        soc_headers_dirs = cls._get_dirs_from_candidates([
+            # master c5 mp
+            os.path.abspath(os.path.join(IDF_PATH, 'components', 'soc', target, 'mp', 'include', 'soc')),
             # other branches
             os.path.abspath(os.path.join(IDF_PATH, 'components', 'soc', target, 'include', 'soc')),
             # release/v4.2
             os.path.abspath(os.path.join(IDF_PATH, 'components', 'soc', 'soc', target, 'include', 'soc')),
         ])
-        esp_rom_headers_dir = cls._get_dir_from_candidates([
-            os.path.join(IDF_PATH, 'components', 'esp_rom', target),
+        esp_rom_headers_dirs = cls._get_dirs_from_candidates([
+            # master c5 mp
+            os.path.abspath(os.path.join(IDF_PATH, 'components', 'esp_rom', target, 'mp', target)),
+            # others
+            os.path.abspath(os.path.join(IDF_PATH, 'components', 'esp_rom', target)),
         ])
 
         header_files: t.List[str] = []
-        if soc_headers_dir:
-            header_files += [str(p.resolve()) for p in Path(soc_headers_dir).glob(cls.CAPS_HEADER_FILEPATTERN)]
-        if esp_rom_headers_dir:
-            header_files += [str(p.resolve()) for p in Path(esp_rom_headers_dir).glob(cls.CAPS_HEADER_FILEPATTERN)]
+        for d in [*soc_headers_dirs, *esp_rom_headers_dirs]:
+            LOGGER.debug('Checking dir %s', d)
+            header_files += [str(p.resolve()) for p in Path(d).glob(cls.CAPS_HEADER_FILEPATTERN)]
 
         output_dict = {}
         for f in header_files:
+            LOGGER.debug('Checking header file %s', f)
             for line in get_defines(f):
                 try:
                     res = parse_define(line)

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/idf_build_apps/utils.py

@@ -85,6 +85,10 @@ class BuildError(RuntimeError):
     pass
 
 
+class AutocompleteActivationError(SystemExit):
+    pass
+
+
 class InvalidCommand(SystemExit):
     def __init__(self, msg: str) -> None:
         super().__init__('Invalid Command: ' + msg.strip())

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
     "packaging",
     "toml; python_version < '3.11'",
     "pydantic~=2.0",
+    "argcomplete>=3"
 ]
 
 [project.optional-dependencies]
@@ -60,7 +61,7 @@ idf-build-apps = "idf_build_apps:main.main"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.3.1"
+version = "2.4.1.dev0"
 tag_format = "v$version"
 version_files = [
     "idf_build_apps/__init__.py",

{idf_build_apps-2.3.1 → idf_build_apps-2.4.1.dev0}/setup.py

@@ -13,7 +13,7 @@ package_data = \
 {'': ['*']}
 
 install_requires = \
-['pyparsing', 'pyyaml', 'packaging', 'pydantic~=2.0']
+['pyparsing', 'pyyaml', 'packaging', 'pydantic~=2.0', 'argcomplete>=3']
 
 extras_require = \
 {":python_version < '3.11'": ['toml'],
@@ -30,7 +30,7 @@ entry_points = \
 {'console_scripts': ['idf-build-apps = idf_build_apps:main.main']}
 
 setup(name='idf-build-apps',
-      version='2.3.1',
+      version='2.4.1.dev0',
       description='Tools for building ESP-IDF related apps.',
       author=None,
       author_email='Fu Hanxi <fuhanxi@espressif.com>',