diff --git a/docs/TEMPLATE_EXAMPLE_README.md b/docs/TEMPLATE_EXAMPLE_README.md index 662ef7bf6f..7582438e00 100644 --- a/docs/TEMPLATE_EXAMPLE_README.md +++ b/docs/TEMPLATE_EXAMPLE_README.md @@ -133,6 +133,6 @@ For any technical queries, please open an [issue](https://github.com/espressif/e _Provide references to important documents_ -- Link to the ESP-IDF feature's API reference, for example [ESP-IDF: ESP Timer feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html) +- _Link to the ESP-IDF feature's API reference, for example [ESP-IDF: ESP Timer feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html)_ - [ESP-IDF Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html#get-started) - [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) (Kconfig Options) diff --git a/examples/README.md b/examples/README.md index a170cc7489..9d2eccc18a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -58,7 +58,7 @@ idf.py set-target esp32 ### Configure the Project -For information about Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html) > ESP Timer (High Resolution Timer). +For information about Kconfig options, see [Project Configuration](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/kconfig.html). To conveniently check or modify Kconfig options for this example in a project configuration menu, run: diff --git a/examples/get-started/sample_project/CMakeLists.txt b/examples/get-started/sample_project/CMakeLists.txt index 664d45871d..0cc87a6edb 100644 --- a/examples/get-started/sample_project/CMakeLists.txt +++ b/examples/get-started/sample_project/CMakeLists.txt @@ -1,5 +1,3 @@ -# For more information about build system see -# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html # The following five lines of boilerplate have to be in your project's # CMakeLists in this exact order for cmake to work correctly cmake_minimum_required(VERSION 3.16) diff --git a/examples/get-started/sample_project/README.md b/examples/get-started/sample_project/README.md index 2475132307..ffc38814c2 100644 --- a/examples/get-started/sample_project/README.md +++ b/examples/get-started/sample_project/README.md @@ -1,35 +1,45 @@ -| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 | -| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | - # _Sample project_ -(See the README.md file in the upper level 'examples' directory for more information about examples.) +(For general overview of examples and their usage, see the `README.md` file in the upper level 'examples' directory.) -This is the simplest buildable example. The example is used by command `idf.py create-project` -that copies the project to user specified path and set it's name. For more information follow the [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project) +> **Note**: +> +> After you click any link to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html), go to the top of the sidebar, then make sure you have the appropriate **Espressif chip** (target) and **ESP-IDF version** selected in the dropdown menus. +This is the example of a simplest buildable project. It is also used by the command `idf.py create-project` which copies these files to the path specified by the user and sets the project name. +This sample projects contains: -## How to use example -We encourage the users to use the example as a template for the new projects. -A recommended way is to follow the instructions on a [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project). - -## Example folder contents - -The project **sample_project** contains one source file in C language [main.c](main/main.c). The file is located in folder [main](main). - -ESP-IDF projects are built using CMake. The project build configuration is contained in `CMakeLists.txt` -files that provide set of directives and instructions describing the project's source files and targets -(executable, library, or both). - -Below is short explanation of remaining files in the project folder. - -``` -├── CMakeLists.txt +```sh +├── CMakeLists.txt # Build configuration declaring entire project ├── main -│   ├── CMakeLists.txt -│   └── main.c -└── README.md This is the file you are currently reading +│   ├── CMakeLists.txt # File that registers the main component +│   └── main.c # Source file for the main component +└── README.md # File you are currently browsing ``` -Additionally, the sample project contains Makefile and component.mk files, used for the legacy Make based build system. -They are not used or needed when building with CMake and idf.py. + +If you want to develop a project for the legacy build system based on Make that requires `Makefile` and `component.mk` files, see [esp-idf-template](https://github.com/espressif/esp-idf-template). + + +## Usage + +For brief instructions on how to configure, build, and flash the project, see [Examples README](https://github.com/espressif/esp-idf/blob/master/examples/README.md#using-examples) > Using Examples. + + +## Further Development + +For further steps on how to develop the project, see the following: + +- Managing the project: + - [IDF Frontend](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project) document + - ESP-IDF Getting Started video ([YouTube](https://youtu.be/J8zc8mMNKtc?t=340), [bilibili](https://www.bilibili.com/video/BV1114y1r7du/?t=336)) + - [Overview](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#example-project) of an example project + - [Build System](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/build-system.html) document +- Writing code: + - Find appropriate bits of code in [application examples](https://github.com/espressif/esp-idf/tree/master/examples) + - Write your own code following the [API references](https://docs.espressif.com/projects/esp-idf/en/stable/api-reference/index.html) + + +## Documentation + +If you want to contribute this project as an ESP-IDF application example, please write this README based on the [example README template](https://github.com/espressif/esp-idf/blob/master/docs/TEMPLATE_EXAMPLE_README.md). diff --git a/tools/ci/check_build_test_rules.py b/tools/ci/check_build_test_rules.py index 4748f29917..1e2060bdfe 100755 --- a/tools/ci/check_build_test_rules.py +++ b/tools/ci/check_build_test_rules.py @@ -426,9 +426,10 @@ if __name__ == '__main__': if check_all: check_dirs = {IDF_PATH} _exclude_dirs = [os.path.join(IDF_PATH, 'tools', 'unit-test-app'), - os.path.join(IDF_PATH, 'tools', 'test_build_system', 'build_test_app')] + os.path.join(IDF_PATH, 'tools', 'test_build_system', 'build_test_app'), + os.path.join(IDF_PATH, 'examples', 'get-started', 'sample_project')] else: - _exclude_dirs = [] + _exclude_dirs = [os.path.join(IDF_PATH, 'examples', 'get-started', 'sample_project')] extra_default_build_targets_list: List[str] = [] bypass_check_test_targets_list: List[str] = []