fix(tools): set *_IS_TOP_LEVEL cmake values at project() calls (IDFGH-16745)

[benedekkupper]

Description

As the comment at line 607 explains what's done here:

Set the variables that project() normally sets

However, with cmake 3.21, two more variables are added to this list:
PROJECT_IS_TOP_LEVEL,
<PROJECT-NAME>_IS_TOP_LEVEL

When these aren't set correctly, builds fail in various ways, with rather vague error messages:
https://github.com/IntergatedCircuits/esp-idf-examples/actions/runs/19098336995/job/54563853753

With this change added, these variables are set as expected.

The condition used to set the value for these variables might be subject to change, I'm open for adjusting it as needed.

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.

---

Note

Sets PROJECT_IS_TOP_LEVEL and <PROJECT-NAME>_IS_TOP_LEVEL in tools/cmake/project.cmake for CMake >= 3.21 based on whether the project is top-level.

• Build/CMake:
  • Update tools/cmake/project.cmake to set PROJECT_IS_TOP_LEVEL and <PROJECT-NAME>_IS_TOP_LEVEL (CMake >= 3.21) after the project() call, based on CMAKE_CURRENT_SOURCE_DIR == CMAKE_SOURCE_DIR.

^{Written by Cursor Bugbot for commit c9c61f0. This will update automatically on new commits. Configure here.}

[github-actions]

	Warnings
⚠️	The **target branch** for this Pull Request **must be the default branch** of the project (`master`). If you would like to add this feature to a different branch, please state this in the PR description and we will consider it.

👋 Hello benedekkupper, 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.
- Resolve all warnings (⚠️ ) before requesting a review from human reviewers - they will appreciate it.
- 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 c9c61f0

[cursor]

This is the final PR Bugbot will review for you during this billing cycle

Your free Bugbot reviews will reset on November 20

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[fhrbata]

I think this does not mimic how cmake sets PROJECT_IS_TOP_LEVEL. Specifically

The variable value will be true in:
a directory added by add_subdirectory() that does not also contain a project() call`

as described in docs

[benedekkupper]

There's also a change in the documentation between 3.23 and 3.24, so if we want to handle these variables completely up to spec, this should be reflected too. I'm a bit out of my depth here, do you have a proposal for the condition here?

[fhrbata]

There's also a change in the documentation between 3.23 and 3.24, so if we want to handle these variables completely up to spec, this should be reflected too.

Ah, nice catch, I haven't noticed the change between 3.23 and 3.24.

I'm a bit out of my depth here, do you have a proposal for the condition here?

TBH I'm not sure neither. I guess it would be best to fully understand how the IsRootMakefile() function, used to set the PROJECT_IS_TOP_LEVEL variable, is implemented. I tried to take a look, but I would definitely need more time to understand the logic.

My worry is that with this change, which does not fully mimic cmake's behavior, we may fix problems for one set of people, but at the same time, we may change the expected behavior for others and break their components. At this point, I'm not sure this issue can be fully resolved, but I could be completely off here.

We are currently working on a next version of the build system, which is currently available as technical preview and it does not have this issue.

Thank you very much for looking into this problem!

[benedekkupper]

Does that mean that there won't be further releases from 5.5? What is the timeline for releasing this new build system?

[dobairoland]

Does that mean that there won't be further releases from 5.5?

Please see https://github.com/espressif/esp-idf?tab=readme-ov-file#esp-idf-release-support-schedule. We will release bugfix releases for v5.5 up until 2028. All PRs should be targeted to the master branch and we can backport them to v5.5 if possible (patch is without breaking changes).

The build system what you know in v5.5 will be available in v6.0 as well. This is referred as cmakev1 in #17833. cmakev2 is available from v6.0 in preview state. cmakev2 will became the default build some later version of ESP-IDF. I'm unable to tell when will this happen.

[benedekkupper]

I still think it is better to fix this in 5.5 one way or another, I don't believe that anybody is depending on the current wrong behavior and gets a worse experience with this fix.

[fhrbata]

Hello @benedekkupper ,

I still think it is better to fix this in 5.5 one way or another, I don't believe that anybody is depending on the current wrong behavior and gets a worse experience with this fix.

This build system quirk is present for a long time and people may have worked around it already. For example there is another issue #17773 and the ESP_PLATFORM variable was used as a workaround(if(PROJECT_IS_TOP_LEVEL AND NOT ESP_PLATFORM)). Maybe this is something that could be used for your use case too. Note I don't think that your change would break this particular workaround, but we cannot be sure how the PROJECT_IS_TOP_LEVEL may be used in other components.

IIUC with the change you proposed we would actually set the PROJECT_IS_TOP_LEVEL variable always to OFF for components, which is now always ON. As stated above, I think this may break components which already worked around this unfortunate behavior.

I agree that it would be best to fix this, but I'm not sure if replacing one quirky behavior with another is the ideal solution. I of course can be wrong and maybe others have a different opinion.

Thank you very much