Metadata-Version: 2.1
Name: idf-build-apps
Version: 2.4.1.dev0
Summary: Tools for building ESP-IDF related apps.
Author-email: Fu Hanxi <fuhanxi@espressif.com>
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: pyparsing
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"
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: 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: 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
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: test

# idf-build-apps

[![Documentation Status](https://readthedocs.com/projects/espressif-idf-build-apps/badge/?version=latest)](https://espressif-docs.readthedocs-hosted.com/projects/idf-build-apps/en/latest/)
[![pypi_package_version](https://img.shields.io/pypi/v/idf-build-apps)](https://pypi.org/project/idf_build_apps/)
[![supported_python_versions](https://img.shields.io/pypi/pyversions/idf-build-apps)](https://pypi.org/project/idf_build_apps/)

`idf-build-apps` is a tool that helps users find and build [ESP-IDF][esp-idf], and [ESP8266 RTOS][esp8266-rtos] projects in a large scale.

## What is an `app`?

A project using [ESP-IDF][esp-idf] SDK, or [ESP8266 RTOS][esp8266-rtos] SDK typically contains:

- Build recipe in CMake or Make and the main component with app sources
- (Optional) One or more [sdkconfig][sdkconfig] files

`app` is the abbreviation for application. An application is a set of binary files that is being built with the specified [sdkconfig][sdkconfig] and the target chip. `idf-build-apps` could build one project into a number of applications according to the matrix of these two parameters.

## Installation

```shell
pip install idf-build-apps
```

or `pipx`

```shell
pipx install idf-build-apps
```

## Basic Usage

`idf-build-apps` is a python package that could be used as a library or a CLI tool.

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

```shell
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

- Two functions, `find_apps` and `build_apps`
- Two classes, `CMakeApp` and `MakeApp`

## Quick CLI Example

To build [ESP-IDF hello world example project][hello-world] with ESP32:

```shell
idf-build-apps build -p $IDF_PATH/examples/get-started/hello_world/ --target esp32
```

The binary files will be generated under `$IDF_PATH/examples/get-started/hello_world/build` directory.

## Documentation

For detailed information, please refer to [our documentation site][doc]!

## Contributing

Thanks for your contribution! Please refer to our [Contributing Guide](CONTRIBUTING.md)

[esp-idf]: https://github.com/espressif/esp-idf
[esp8266-rtos]: https://github.com/espressif/ESP8266_RTOS_SDK
[sdkconfig]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html
[hello-world]: https://github.com/espressif/esp-idf/tree/master/examples/get-started/hello_world
[supported-targets]: https://github.com/espressif/esp-idf/tree/v5.0#esp-idf-release-and-soc-compatibility
[doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/
[api-doc]: https://docs.espressif.com/projects/idf-build-apps/en/latest/api/modules.html

