Split app.cmake into two parts to fix CMake deprecation warning

[multiplemonomials]

Summary of changes

Up until now, CMake projects using Mbed had to include app.cmake near the top of their CMakeLists.txt files. This worked fine for a while, but it did have the side effect of calling enable_languages() before project(), which now triggers a warning in CMake 3.31 (apparently you weren't supposed to ever do it that way... who knew).

Unfortunately, there was no way to fix this without breaking changes for projects using Mbed, as the existing app.cmake file had to be split up. However, I did what I could to try and ease the pain:

• New CMake files are named more clearly (where did they get something so generic as app.cmake, anyway??)
• Removed the need to call mbed_finalize_build() at the end of the CMake file (CMake 3.19 actually added a way to do this automatically).
• Deprecation warning added which links back to this PR

Impact of changes

Should not actually break any projects, but adds a new, preferred way to structure CMakeLists.txt and adds several deprecation warnings if you are using the old way.

Migration actions required

Up until now, a basic CMakeLists.txt looked like:

cmake_minimum_required(VERSION 3.19)
cmake_policy(VERSION 3.19)

set(MBED_APP_JSON_PATH mbed_app.json5)

include(mbed-os/tools/cmake/app.cmake)

add_subdirectory(mbed-os)

project(MyMbedApp) # here you can change your project name

add_executable(${CMAKE_PROJECT_NAME} main.cpp)
target_link_libraries(${CMAKE_PROJECT_NAME} mbed-os) # Can also link to mbed-baremetal here
mbed_set_post_build(${CMAKE_PROJECT_NAME})

mbed_finalize_build()

Going forward, this should be changed to:

cmake_minimum_required(VERSION 3.19)
cmake_policy(VERSION 3.19...3.22)

set(MBED_APP_JSON_PATH mbed_app.json5)

include(mbed-os/tools/cmake/mbed_toolchain_setup.cmake)
project(MyMbedApp # here you can change your project name
    LANGUAGES C CXX ASM) 
include(mbed_project_setup)

add_subdirectory(mbed-os)

add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} mbed-os) # Can also link to mbed-baremetal here
mbed_set_post_build(${PROJECT_NAME})

Basically:

• include(mbed-os/tools/cmake/app.cmake) replaced with include(mbed-os/tools/cmake/mbed_toolchain_setup.cmake)
• The project() call must be immediately after include(mbed-os/tools/cmake/mbed_toolchain_setup.cmake)
• include(mbed_project_setup) must be immediately after project().

Documentation

Will update docs to use new structure when merged

---

Pull request type

[] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[] Feature update (New feature / Functionality change / New API)
[X] Major update (Breaking change E.g. Return code change / API behaviour change)

---

Test results

[] No Tests required for this change (E.g docs only update)
[X] Covered by existing mbed-os tests (Greentea or Unittest)
[] Tests / results supplied as part of this PR

---

[JohnK1987]

One point about GCC finding.

I noticed the VS Code uses GCC 11.3.1 every time and this even though I have GCC 12 and 13 installed. Then I found it uses the one from STM32 package especially from STM32CubeCLT. This probably caused because it is first in the list and rest are probably ignored.

My list:

[proc] Executing command: C:\ST\STM32CubeCLT\GNU-tools-for-STM32\bin\arm-none-eabi-gcc-11.3.1.exe -v
[proc] Executing command: C:\ST\STM32CubeCLT\GNU-tools-for-STM32\bin\arm-none-eabi-gcc.exe -v
[proc] Executing command: "C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\12.3 rel1\bin\arm-none-eabi-gcc-12.3.1.exe" -v
[proc] Executing command: "C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\12.3 rel1\bin\arm-none-eabi-gcc.exe" -v
[proc] Executing command: "C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\13.2 Rel1\bin\arm-none-eabi-gcc-13.2.1.exe" -v
[proc] Executing command: "C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\13.2 Rel1\bin\arm-none-eabi-gcc.exe" -v
[proc] Executing command: chcp
[proc] Executing command: C:\ST\STM32CubeCLT\GNU-tools-for-STM32\bin\arm-none-eabi-gcc.exe -v
[proc] Executing command: "C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\13.2 Rel1\bin\arm-none-eabi-gcc.exe" -v
[proc] Executing command: "C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\12.3 rel1\bin\arm-none-eabi-gcc.exe" -v
[kit] Found Kit (trusted): GCC 11.3.1 arm-none-eabi
[kit] Found Kit (trusted): GCC 11.3.1 arm-none-eabi
[kit] Found Kit (trusted): GCC 13.2.1 arm-none-eabi
[kit] Found Kit (trusted): GCC 13.2.1 arm-none-eabi
[kit] Found Kit (trusted): GCC 12.3.1 arm-none-eabi
[kit] Found Kit (trusted): GCC 12.3.1 arm-none-eabi
[kit] Found Kit (trusted): Visual Studio Build Tools 2019 Release - x86
[kit] Found Kit (trusted): Visual Studio Build Tools 2019 Release - x86_amd64
[kit] Found Kit (trusted): Visual Studio Build Tools 2019 Release - amd64_x86
[kit] Found Kit (trusted): Visual Studio Build Tools 2019 Release - amd64

The fact about it is working just with STM32CubeCLT is cool because you save another space but this can be issue for someone who want to use latest GCC or a specific one for some compatibility reason. Maybe we should make a not in wiki about this. Or any idea how to solve this?

[JojoS62]

I choose the gcc version manually, in the VSCode Cmake extension you can select the kit you want.

[JohnK1987]

yeah, but...

[JojoS62]

'Scan for kits' needs the gcc in the search path, then it is added to the list. The list can be edited also manually, somewhere hidden in the VSCode settings

[JohnK1987]

I ofc know about the list and possibility to choose but how the wiki says, it should stay unspecified because CMake will find and choose it automatically because of another functionality.

BTW that is what we both did wrong. Some new users reported something is wrong and we said "No, everything is ok" but that was because we are choosing the kit manually, however the wiki say something else. So we did it wrong and these new users were right.

[JojoS62]

because of another functionality.

Do you know what is different by using unspecified?

[JohnK1987]

It is written on the picture above.

Without this setting, switching between targets requires to clean the build dir and starts always a build all. By using this setting, each variant has its own build dir.

When I made videos for video guides for "how to start" that i recognize the behaviour was different and lefebvresam was right in one of his issue.

[JojoS62]

Hmm, I have a build dir per target and build variation because it is defined in settings.json to use the environment variables.
Do you have also a dir per gcc version? I would not prefer that.

[JohnK1987]

No, I like just basic project structure so I have it exactly how is described - https://github.com/mbed-ce/mbed-os/wiki/Project-Setup:-VS-Code#loading-your-project

[JojoS62]

That is exactly what I’m using also.

[multiplemonomials]

@JohnK1987 Yeah probably it's because the STM32CubeCLT one is first on your PATH. Moving the other one ahead on your PATH and then doing a fresh build should (TM) fix this issue, I'd hope

[JojoS62]

I have tried this commit, removed mbed_finalize_build(), but left old include app.cmake. It did work also, So the result in this case is only getting some warnings?

[JojoS62]

tested and it worked