CMake Build System

This repository provides the CMake infrastructure required to build STM32-based projects and other modules within the STM Template architecture.
It is designed to be used as a Git submodule and separates complex build logic from project sources, ensuring consistency, versioning, and reusability across repositories.

🧩 Overview

The build system is divided into two layers:

Project Layer
Project root folder CMakeLists.txt represents project part for CMake build and provides a minimal entry point for CMake. Its sole purpose is to invoke the centralized build logic:
```
include(${CMAKE_CURRENT_LIST_DIR}/CMake/Build.cmake)
```
Platform Layer
This script contains all major build definitions, functions, and configuration steps.
It manages:
- Build options checks
- Project initialization and target setup
- Toolchain detection and configuration
- Build type handling (Debug / Release / Test)
- Include path propagation
- Dependency and module registration

This separation ensures that the root project remains clean and easy to maintain while the detailed logic is versioned and shareable as a standalone submodule.

⚙️ Placeholder Source Files

CMake requires at least one valid source file to generate a build system.
For this reason, Platform.c and Platform.h are included as empty placeholders and version storage.
They serve only as stubs during the initial configuration phase and are not compiled into the final firmware.

🧩 Integration as Submodule

This repository is meant to be added as a Git submodule:

git submodule add git@ssh.dev.azure.com:v3/Dlzen/STM_Template/CMake CMake

In the parent project, the main CMakeLists.txt should include:

include("${CMAKE_SOURCE_DIR}/STM_Template/CMake/Build.cmake")

After initialization, the parent project can extend or override specific build steps via custom CMake scripts or options.

📜 Versioning

Because the build logic evolves independently from the application code, each version of this repository is tagged and can be referenced explicitly by parent repositories.
This allows stable builds across multiple firmware generations and branches.

🧩 Future Extensions

Planned additions include:

Integration test implementation
CMake presets implementation

📁 Directory Layout

CMake/
 ├── Build.cmake                # Core build logic called from the root CMakeLists.txt
 ├── Platform.c                 # Placeholder source file required by CMake during project initialization
 ├── Platform.h                 # Placeholder header file (currently empty)
 ├── ArtifactsManager           # Artifactory management functionality
 |    ├── Artifacts.cmake       # Artifacts manager CMake script
 |    └── README.md             # Artifacts manager module description and usage informations
 ├── HelperTools                # Project initialization and support functionality
 |    ├── Scripts               # Location of CMake scripts
 |    ├── Templates             # Location of templates used by CMake scripts
 |    ├── Setup.bat             # Windows script to easier calling CMake scripts
 |    └── README.md             # Helper tools module description and usage informations 
 └── README.md                  # CMake module description and usage informations

🧱 Example Usage

Below is a minimal example of how to use this CMake Build System in a parent project.

ProjectRootDir/CMakeLists.txt

################################################################################
# Author: Mr.Nobody
# file:  CMakeLists.txt
# brief: Project part CMake functionality. 
#
# User shall not change platform functionality, for project necessary 
# functionality can user implement in this file.     
#
# usage: Edit "VARIABLES"-section to suit project requirements.
#        For debug build:
#           cmake -S . -B Build_Debug -GNinja -DCMAKE_BUILD_TYPE=Debug -DTARGET_MCU=STM32WXXXyZ -DDOXYGEN_ENABLED=OFF
#           cmake --build Build_Debug
#        For release build:
#           cmake -S . -B Build_Release -GNinja -DCMAKE_BUILD_TYPE=Release -DTARGET_MCU=STM32WXXXyZ -DDOXYGEN_ENABLED=OFF
#           cmake --build Build_Release
################################################################################
#
# Necessary operators:
#
# CMAKE_BUILD_TYPE
#    - Debug
#    - Release
#    - UnitTest
#    - IntegrationTest
#
# TARGET_MCU
#    - STM32WXXXyZ
#      Where:
#       W - STM32 Family ID (single letter)
#       XXX - STM32 Family specification (three symbols)
#       y - Must stay unchanged
#       Z - Flash size identification ( A - 0K,6 - 32K, 8 - 64K, B - 128K ...)
#      Example: STM32G474xE
#
# Optional operators. If not specified default value will be used
#
# DOXYGEN_ENABLED
#    - OFF (default)
#    - ON
#
################################################################################

cmake_minimum_required(VERSION 3.25)

#=============================== Constant values ==============================#

set(BUILD_TYPE_ALLOWED_VALUES           "Debug"
                                        "Release"
                                        "UnitTest"
                                        "IntegrationTest")
                                        
# Doxygen is not available by default. If artifact is loaded, this macro will be set to ON
add_definitions(-DDOXYGEN_STATE=OFF)

#======================== Project configuration values ========================#
# Set project configuration values such as project name, type, CPU, FPU, runtime library, and compile commands export
set(PROJECT_NAME                        "Project_Template_${CMAKE_BUILD_TYPE}")
set(CMAKE_EXPORT_COMPILE_COMMANDS       ON)

# Setup compiler settings
set(CMAKE_C_STANDARD                    11)
set(CMAKE_C_STANDARD_REQUIRED           ON)
set(CMAKE_C_EXTENSIONS                  ON)

#=========================== DO NOT CHANGE THIS PART ==========================#
#============================ Artifacts preparation ===========================#

# Check, if artifact manager is used in project.
if(EXISTS ${CMAKE_SOURCE_DIR}/EmB_Platform/CMake/ArtifactsManager/Artifacts.cmake)
    # Run artifacts configuration before build.
    include(${CMAKE_SOURCE_DIR}/EmB_Platform/CMake/ArtifactsManager/Artifacts.cmake)
endif()

#========================== Build flags configuration =========================#

## Default build configuration
if(CMAKE_BUILD_TYPE MATCHES Debug)
    set(CMAKE_C_FLAGS               "${CMAKE_C_FLAGS} ${OPTIMIZATION_NONE} ${DEBUG_LEVEL_3}")
endif()
if(CMAKE_BUILD_TYPE MATCHES Release)
    set(CMAKE_C_FLAGS               "${CMAKE_C_FLAGS} ${OPTIMIZATION_NONE} ${DEBUG_LEVEL_0}")
endif()

set(CMAKE_ASM_FLAGS                 "${CMAKE_C_FLAGS} ${ASSEMBLER_MODE}")
set(CMAKE_ASM_FLAGS                 "${CMAKE_ASM_FLAGS} ${GENERATE_DEPENDENCY_FILE}")
set(CMAKE_ASM_FLAGS                 "${CMAKE_ASM_FLAGS} ${GENERATE_DEPENDENCY_FILE}")

set(CMAKE_CXX_FLAGS                 "${CMAKE_C_FLAGS} ${DISABLE_RTTI}")
set(CMAKE_CXX_FLAGS                 "${CMAKE_CXX_FLAGS} ${DISABLE_EXCEPTIONS}")
set(CMAKE_CXX_FLAGS                 "${CMAKE_CXX_FLAGS} ${DISABLE_THREADSAFE_STATICS}")

set(CMAKE_C_FLAGS                   "${CMAKE_C_FLAGS} ${LINKER_NANO}")
                                    
#================================ MCU build ===================================#

# Core project settings
project(${PROJECT_NAME} 
        VERSION 0.1.0
        HOMEPAGE_URL "https://embedbits.com"
        LANGUAGES C CXX ASM)

# Include main CMake script
include("${CMAKE_SOURCE_DIR}/EmB_Platform/CMake/Build.cmake")

#========================= User specific commands =============================#

target_compile_definitions(${CMAKE_PROJECT_NAME}
    INTERFACE
    
    PRIVATE
    
    PUBLIC
)

# Link directories setup
target_link_directories(${CMAKE_PROJECT_NAME}
    INTERFACE
    
    PRIVATE
    
    PUBLIC
)

# Add sources to executable
target_sources(${CMAKE_PROJECT_NAME}
    INTERFACE
    
    PRIVATE
    
    PUBLIC
)

# Add include paths
target_include_directories(${CMAKE_PROJECT_NAME}
    INTERFACE
    
    PRIVATE
    
    PUBLIC
)

# Add project symbols (macros)
target_compile_definitions(${CMAKE_PROJECT_NAME}
    INTERFACE
    
    PRIVATE
    
    PUBLIC
)

# Add linked libraries
target_link_libraries(${CMAKE_PROJECT_NAME}
    INTERFACE
    
    PRIVATE
    
    PUBLIC
)

#==================== User specific pre-processing commands ===================#

#add_custom_command(
#    TARGET ${CMAKE_PROJECT_NAME}
#    PRE_BUILD
#    COMMAND
#) 

#=================== User specific post-processing commands ===================#

add_custom_command(
    TARGET ${CMAKE_PROJECT_NAME}
    POST_BUILD
    COMMENT "Total Size:"
    COMMAND ${CMAKE_SIZE} ARGS $<TARGET_FILE:${CMAKE_PROJECT_NAME}>
)

add_custom_command(
    TARGET ${CMAKE_PROJECT_NAME}
    POST_BUILD
    COMMENT "Generating .bin file."
    COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:${CMAKE_PROJECT_NAME}> ${CMAKE_PROJECT_NAME}.bin 
)

add_custom_command(
    TARGET ${CMAKE_PROJECT_NAME} 
    POST_BUILD
    COMMENT "Generating .hex file."
    COMMAND ${CMAKE_OBJCOPY} -O ihex $<TARGET_FILE:${CMAKE_PROJECT_NAME}> ${CMAKE_PROJECT_NAME}.hex
)

🛠️ Requirements

CMake ≥ 3.25

📜 License

This project is licensed under the Creative Commons Attribution–NonCommercial 4.0 International (CC BY-NC 4.0).

🧩 Overview​

⚙️ Placeholder Source Files​

🧩 Integration as Submodule​

📜 Versioning​

🧩 Future Extensions​

📁 Directory Layout​

🧱 Example Usage​

ProjectRootDir/CMakeLists.txt​

🛠️ Requirements​

📜 License​