Build analyzer uses wrong *.map file when CMakeLists.txt uses add_library()

[parmi93]

After several days of wasted time trying to understand what was causing this issue, I finally realized that if I use the add_library() command in a CMake file, the build analyzer tool, without any reasonable explanation, searches for the *.map file with the wrong name. Specifically, if my VSCodeSTM32 project is located in the my_folder directory, then the build analyzer tool looks for the file my_folder/build/Debug/my_folder.map instead of my_folder/build/Debug/project_name.map.

I ran into this problem because our project is generated by STM32CubeMX, which uses the add_library() command several times in the cmake/stm32cubemx/CMakeLists.txt file.

This is the piece of code that is causing this issue in my main CMakeLists.txt (look in the attached project)

################################################################################################################
if(true) # <-- Use false to fix this BUG
    set(STM32_Drivers_Src
        ${CMAKE_CURRENT_SOURCE_DIR}/temp.c
    )

    add_library(stm32cubemx INTERFACE)

    # Create STM32_Drivers static library
    add_library(STM32_Drivers OBJECT)
    target_sources(STM32_Drivers PRIVATE ${STM32_Drivers_Src})
    target_link_libraries(STM32_Drivers PUBLIC stm32cubemx)
endif()
################################################################################################################

Attaching a small project that reproduces this bug.

[Nawres GHARBI]

Hi @parmi93 

The STM32 VS Code extension does not ask CMake or the toolchain for the final link command. Instead, it infers the expected .map file name from:

• the workspace folder name (e.g. my_folder), and
• the active configuration (e.g. Debug, Release), and then looks for something like:

<workspace>/build/<config>/<workspace>.map

So in your example that's what it is expected:

my_folder/build/Debug/my_folder.map

The root cause is not that add_library() is wrong, but that:

• The extension’s project detection logic is simplistic and strongly tied to the “one executable, same name as folder” layout used in the STM32CubeMX default templates.
• As soon as you introduce additional targets:
  • add_library(stm32cubemx INTERFACE)
  • add_library(STM32_Drivers OBJECT) the extension’s heuristics can misidentify the “main” target or the expected file name. In your case, it falls back to the folder name (my_folder) instead of the actual executable name (project_name).

as workaround I propose

1. Rename the executable to match the folder name If it’s acceptable for your project

 2. Add a post-build command to “mirror” the map file

Keep your real executable name (project_name) but copy/symlink the .map file to the name the extension expects.

set(TARGET_NAME project_name)
set(EXPECTED_MAP_NAME "${CMAKE_PROJECT_NAME}.map")  # typically folder name
set(ACTUAL_MAP_NAME   "${TARGET_NAME}.map")

add_executable(${TARGET_NAME} ...)

# Ensure the linker generates the map file:
target_link_options(${TARGET_NAME} PRIVATE
    "-Wl,-Map=${CMAKE_CURRENT_BINARY_DIR}/${ACTUAL_MAP_NAME}"
)

# After build, copy/duplicate it with the name expected by Build Analyzer
add_custom_command(
    TARGET ${TARGET_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
            "${CMAKE_CURRENT_BINARY_DIR}/${ACTUAL_MAP_NAME}"
            "${CMAKE_CURRENT_BINARY_DIR}/${EXPECTED_MAP_NAME}"
    COMMENT "Duplicating ${ACTUAL_MAP_NAME} to ${EXPECTED_MAP_NAME} for STM32 Build Analyzer"
)

Adjust EXPECTED_MAP_NAME to match what the analyzer is searching for (currently: <workspace_folder>.map in the <config> directory).

[TDJ]

I am showing that if project name specified in CMakeLists.txt like this:
set(CMAKE_PROJECT_NAME <prj_name>)
does not match ${workspaceRootFolderName}, code analyzer is unable to find map file since it looks for ${workspaceRootFolderName}.map while the file is named <prj_name>.map

[vincent_grenet]

@TDJ 
Please be aware that you can invoke build analysis by using the file explorer context menu on any map file

[TDJ]

@vincent_grenet  Thanks, I have not noticed this option yet.
Still, I think the issue I described should be treated as a bug.

[vincent_grenet]

@TDJ 
Thank you for reporting and sharing your feedback.
We will consider your input. We can likely improve in this area.
However, it is not possible to guarantee complete safety. As you pointed out, we must rely on heuristics at some stage. Currently, we use heuristics and recognize the need for further improvement. However, heuristics do not ensure a perfect success rate.
Toolchains are flexible. CMake is a language in itself. As you mentioned, end users can always locate or name the map file as they prefer - we like having end user free -. This is the reason for providing a file explorer contextual entry as a fallback.

[parmi93]

@Nawres GHARBI thanks for the workaround, I modified the script so that it can automatically detect the name of the root folder.

#[[
Workaround for the bugged STM32Cube Build Analyzer extension in VSCode, which looks for the `.map`
file with the wrong name.
It expects a `.map` file named after the project's root folder instead of
`${CMAKE_PROJECT_NAME}.map`, as defined in the auto-generated `gcc-arm-none-eabi.cmake` file by 
STM32CubeMX.
]]
get_filename_component(PROJECT_ROOT_FOLDER_NAME ${CMAKE_SOURCE_DIR} NAME)

set(EXPECTED_MAP_NAME "${PROJECT_ROOT_FOLDER_NAME}.map")
set(ACTUAL_MAP_NAME "${CMAKE_PROJECT_NAME}.map")

add_custom_command(
    TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
            "${CMAKE_CURRENT_BINARY_DIR}/${ACTUAL_MAP_NAME}"
            "${CMAKE_CURRENT_BINARY_DIR}/${EXPECTED_MAP_NAME}"
    COMMENT "Duplicating ${ACTUAL_MAP_NAME} to ${EXPECTED_MAP_NAME} for VSCode's STM32 Build Analyzer"
)

@vincent_grenet 

I would like to reiterate that ours is a project generated by STM32CubeMX, which in the auto-generated gcc-arm-none-eabi.cmake file sets ${CMAKE_PROJECT_NAME}.map as the default name.

Users expect that a project generated by STM32CubeMX can be used in Visual Studio Code without any workaround (note that the Build Analyzer in STM32CubeIDE does not have this issue with CMake projects).

[vincent_grenet]

@parmi93 
Which STM32CubeMX version are you using?
I can share that, when using STM32CubeMX version 6.16, there is no issue - no need to update anything I mean -  based on my current attempt.

[parmi93]

I'm using STM32CubeMX v6.16.1

Did you rename the project’s root folder after generating it with CubeMX and before building it in VSCode?

Attached is a .ioc project that reproduces the issue. Simply generate the project with CubeMX, open it in VSCode, allow VSCode to configure it as an STM32Cube CMake project by clicking “Yes” in the notification at the bottom right, and then build it. You’ll notice that the Build Analyzer cannot find the .map file.

I would also like to point out that this issue does not occur with projects created using the “STM32Cube Project Manager” extension in VSCode.

Attached is an STM32Cube project created via VSCode; you’ll notice that in this case the Build Analyzer has no trouble finding the .map file, even if you rename the project’s root folder. This happens because, unlike projects generated with CubeMX, projects created through VSCode never use CMake’s add_library() function, which is the root cause of this issue (see my first message in this thread).

[parmi93]

I just tried STM32CubeMX v6.17.0, which generates projects with the same issue.