docs: Add chip target to direct CMake example code snippet in build system docs (IDFGH-14339)

[Dazza0]

Description

The Build System documentation provides and example code snippet on how to use CMake and Ninja directly, bypassing the idf.py frontend.

However, the snippet does not demonstrate how to set the chip target using CMake (equivalent to idf.py set-target). This PR updates the example code snippets to set the chip target.

Related

• Build System documentation

Testing

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

	Messages
📖	🎉 Good Job! All checks are passing!

👋 Hello Dazza0, we appreciate your contribution to this project!

---

📘 Please review the project's Contributions Guide for key guidelines on code, documentation, testing, and more.

---

🖊️ Please also make sure you have read and signed the Contributor License Agreement for this project.

---

Click to see more instructions ...

This automated output is generated by the PR linter DangerJS, which checks if your Pull Request meets the project's requirements and helps you fix potential issues.

DangerJS is triggered with each push event to a Pull Request and modify the contents of this comment.

Please consider the following:
- Danger mainly focuses on the PR structure and formatting and can't understand the meaning behind your code or changes.
- Danger is not a substitute for human code reviews; it's still important to request a code review from your colleagues.
- To manually retry these Danger checks, please navigate to the Actions tab and re-run last Danger workflow.

Review and merge process you can expect ...

We do welcome contributions in the form of bug reports, feature requests and pull requests via this public GitHub repository.

This GitHub project is public mirror of our internal git repository

1. An internal issue has been created for the PR, we assign it to the relevant engineer.
2. They review the PR and either approve it or ask you for changes or clarifications.
3. Once the GitHub PR is approved, we synchronize it into our internal git repository.
4. In the internal git repository we do the final review, collect approvals from core owners and make sure all the automated tests are passing.
- At this point we may do some adjustments to the proposed change, or extend it by adding tests or documentation.
5. If the change is approved and passes the tests it is merged into the default branch.
5. On next sync from the internal git repository merged change will appear in this public GitHub repository.

Generated by 🚫 dangerJS against a4bbaed

[dobairoland]

Thanks @Dazza0 for the contribution. You are right that this could be explained. But the comment for that code snippet states that it is equivalent to running idf.py build. So I think this should be explained separately, if necessary.

On the other hand, the sentence just before it states that "When idf.py does something, it prints each command that it runs for easy reference.". I see it as a guide how to find the right cmake commands to run if someone wants to bypass idf.py. If we go into details then we will have to expand this short section with a complete guide for cmake underneath idf.py.

It is definitely worth considering but probably only after the related build system improvements we plan to do soon.

[Dazza0]

@dobairoland

So I think this should be explained separately, if necessary.

Would this information be better placed in the Using ESP-IDF in Custom CMake Projects. I think it's likely the main use case for users needing to call CMake directly is if they are trying to integrate IDF into an existing CMake.

For context, this is what I'm trying to achieve. I have an existing CMake project that needs to build on multiple MCU families (e.g., STM32, PIC32, ESP32).

I see it as a guide how to find the right cmake commands to run if someone wants to bypass idf.py. If we go into details then we will have to expand this short section with a complete guide for cmake underneath idf.py.

Would it be possible to provide a short list of what targets are exposed to the underlying build system. Comparing the target list between ninja help and idf.py --help, it seems like ninja has a subset of idf.py targets (e.g., has ninja menuconfig|flash|monitor but not ninja gdb|openocd. Thus it would be helpful to know what targets are officially exposed.

[dobairoland]

Would this information be better placed in the Using ESP-IDF in Custom CMake Projects. I think it's likely the main use case for users needing to call CMake directly is if they are trying to integrate IDF into an existing CMake.

I think it could have a separate section much earlier, e.g. between https://docs.espressif.com/projects/esp-idf/en/v5.3.2/esp32/api-guides/build-system.html#using-cmake-directly and https://docs.espressif.com/projects/esp-idf/en/v5.3.2/esp32/api-guides/build-system.html#flashing-with-ninja-or-make.

Would it be possible to provide a short list of what targets are exposed to the underlying build system. Comparing the target list between ninja help and idf.py --help, it seems like ninja has a subset of idf.py targets (e.g., has ninja menuconfig|flash|monitor but not ninja gdb|openocd. Thus it would be helpful to know what targets are officially exposed.

Ah, you are right. We used to have all idf.py targets available in cmake as well but we deviated from this when we added the debugging targets. This certainly needs to be addressed or, as you suggest, describe the limitation in the documentation. There is one issue with having a list there. I don't think anyone would remember to update it over time when we add/remove a new target.

Thanks for the suggestions!