Metadata-Version: 2.4
Name: esp-bmgr-assist
Version: 0.6.0
Summary: ESP Board Manager Python package for idf.py extensions
Author: ESP Board Manager Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/espressif/esp-bmgr-py
Keywords: esp-idf,board-manager,idf.py,extensions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=5.1
Dynamic: license-file

# esp-bmgr-assist

PyPI package: `esp-bmgr-assist`  
Python package: `esp_bmgr_py`

`esp-bmgr-assist` injects into the `idf.py` startup flow through a `.pth` hook, then discovers and loads the [ESP Board Manager](https://components.espressif.com/components/espressif/esp_board_manager) extension automatically.

PyPI 包名：`esp-bmgr-assist`  
Python 包目录：`esp_bmgr_py`

`esp-bmgr-assist` 通过 `.pth` 注入 `idf.py` 启动流程，帮助工程自动发现并加载 [ESP Board Manager](https://components.espressif.com/components/espressif/esp_board_manager) 扩展。

## Features / 功能

- Automatically appends the detected board manager path to `IDF_EXTRA_ACTIONS_PATH`.
- Supports local and managed component discovery:
  - `components/esp_board_manager`
  - `components/espressif__esp_board_manager`
  - `managed_components/espressif__esp_board_manager`
- Supports first-use bootstrap on `idf.py bmgr ...` and the legacy `idf.py gen-bmgr-config ...`.
- Resolves the real project directory correctly for `-C` / `--project-dir`.
- Can locate board manager through direct dependencies or transitive dependencies resolved by the project dependency graph.

- 自动把可用的 board manager 路径加入 `IDF_EXTRA_ACTIONS_PATH`。
- 支持本地组件和托管组件发现：
  - `components/esp_board_manager`
  - `components/espressif__esp_board_manager`
  - `managed_components/espressif__esp_board_manager`
- 支持在 `idf.py bmgr ...` 和兼容旧命令 `idf.py gen-bmgr-config ...` 首次使用时自动自举。
- 支持正确处理 `-C` / `--project-dir` 等项目目录参数。
- 支持通过直接依赖或项目依赖图解析出的传递依赖定位 board manager。

## Installation / 安装

Install this package into the Python environment used by ESP-IDF.

请安装在 ESP-IDF 对应的 Python 虚拟环境中。

Install from PyPI:

```bash
pip install esp-bmgr-assist
```

Install from source:

```bash
pip install /path/to/esp-bmgr-py
```

Upgrade an existing installation from PyPI:

```bash
pip install --upgrade esp-bmgr-assist
```

Upgrade from a local checkout after new changes:

```bash
pip install --upgrade /path/to/esp-bmgr-py
```

## Usage / 使用方法

Recommended command:

```bash
idf.py bmgr
```

Legacy command kept for compatibility:

```bash
idf.py gen-bmgr-config
```

Debug mode:

```bash
export ESP_BMGR_DEBUG=1
idf.py bmgr
```

Assist preflight warnings are enabled by default for build-like commands:

```bash
idf.py build
```

Disable them when needed:

```bash
export ESP_BMGR_ASSIST_PREFLIGHT=0
idf.py build
```

Assist can warn about:
- missing `components/gen_bmgr_codes/*` generated artifacts
- `CONFIG_IDF_TARGET` mismatch between `sdkconfig` and `board_manager.defaults`

The assist-side preflight currently focuses on build-like commands and intentionally skips
interactive/config-only commands such as `set-target`, `menuconfig`, `confserver`, and
`config-report`.

推荐命令：

```bash
idf.py bmgr
```

兼容旧命令：

```bash
idf.py gen-bmgr-config
```

调试模式：

```bash
export ESP_BMGR_DEBUG=1
idf.py bmgr
```

assist 侧预检查默认会在 build 一类命令上启用：

```bash
idf.py build
```

如需关闭，可设置：

```bash
export ESP_BMGR_ASSIST_PREFLIGHT=0
idf.py build
```

开启时，assist 会额外提示：
- `components/gen_bmgr_codes/*` 生成物缺失
- `sdkconfig` 与 `board_manager.defaults` 的 `CONFIG_IDF_TARGET` 不匹配

当前 assist 预检查只针对 build 一类命令，不会对 `set-target`、`menuconfig`、
`confserver`、`config-report` 这类交互/配置命令输出这些 warning。

## Compatibility And Known Issues / 兼容与已知问题

### Older package behavior / 旧版本行为

Starting from `0.3.1`, this package no longer declares core dependencies managed by ESP-IDF itself, such as `idf-component-manager`. This avoids accidentally upgrading key packages inside the IDF environment during `pip install`.

从 `0.3.1` 起，本包不再声明 `idf-component-manager` 等由 ESP-IDF 自身管理的核心依赖，避免在 `pip install` 时误升级 IDF 环境中的关键包。

If you installed `0.3.0` before and later saw `check-python-dependencies` failures, repair the current IDF environment first, then reinstall a newer `esp-bmgr-assist`.

如果之前安装过 `0.3.0`，之后出现 `check-python-dependencies` 失败，请先修复当前 IDF 环境，再重新安装更新版本的 `esp-bmgr-assist`。

### `InvalidVersion` / `4.0.0-unsupported`

This is usually caused by broken third-party package metadata already present in the current Python environment, often in mixed or Conda-based environments. It is not caused by `esp-bmgr-assist` itself.

这通常是当前 Python 环境里已有第三方包的元数据不符合 PEP 440，常见于混用或 Anaconda 环境，不是 `esp-bmgr-assist` 自身逻辑导致的。

Recommended actions:

1. Use the official ESP-IDF Python environment.
2. Reinstall or remove the package named in the error log.
3. Create a clean virtual environment if needed.

建议按下面顺序处理：

1. 优先使用 ESP-IDF 官方 Python 虚拟环境。
2. 重装或卸载报错中点名的包。
3. 必要时新建干净的虚拟环境后再安装。

### `IDF_EXTRA_ACTIONS_PATH` separator / 多路径分隔符

Use `;` as the separator for multiple `IDF_EXTRA_ACTIONS_PATH` entries, matching ESP-IDF behavior on all platforms. Do not use `:`.

多个 `IDF_EXTRA_ACTIONS_PATH` 路径请使用分号 `;` 分隔，与 ESP-IDF 在各平台上的行为保持一致。不要使用 `:`。
