The Embedded New Testament

The "Holy Bible" for embedded engineers

---

Project maintained by theEmbeddedGeorge Hosted on GitHub Pages — Theme by mattgraham

Build Systems

Understanding build systems through concepts, not just syntax. Learn why build systems matter and how to think about software construction.

📋 Table of Contents

• Concept → Why it matters → Minimal example → Try it → Takeaways
• Core Concepts
• Build System Types
• Make Build System
• CMake Build System
• Advanced Features
• Guided Labs
• Check Yourself
• Cross-links

---

Concept → Why it matters → Minimal example → Try it → Takeaways

Concept: A build system is like a smart factory that takes your source code and transforms it into a working program, automatically handling all the complex steps in between.

Why it matters: Without a build system, you’d have to manually remember and type every compilation command, manage dependencies, and ensure everything is built in the right order. This becomes impossible as projects grow, leading to build errors, forgotten steps, and wasted time.

Minimal example: A simple project with three source files that depend on each other. The build system automatically compiles them in the correct order and links them together.

Try it: Start with a single source file, then add more files and watch how the build system automatically handles the growing complexity.

Takeaways: Build systems automate the complex process of turning source code into executable programs, making development faster, more reliable, and less error-prone.

---

📋 Quick Reference: Key Facts

Build System Fundamentals

• Automation: Automates compilation, linking, and packaging processes
• Dependency Management: Tracks relationships between source files and libraries
• Incremental Builds: Only rebuilds what changed, saving time
• Cross-Platform: Works across different operating systems and architectures
• Parallel Processing: Can compile multiple files simultaneously

Build System Types

• Make-based: Traditional, script-based systems (GNU Make, BSD Make)
• CMake-based: Modern, cross-platform build generators
• IDE-integrated: Built into development environments
• Cloud-based: Distributed builds for large projects

Key Benefits

• Consistency: Produces reproducible builds across environments
• Efficiency: Optimizes build process with caching and parallelization
• Maintainability: Centralized build configuration and rules
• Scalability: Handles projects from small to enterprise-scale
• Integration: Works with version control and CI/CD systems

Common Build Tools

• Make: Traditional build automation tool
• CMake: Cross-platform build system generator
• Ninja: Fast build system used by many modern projects
• Autotools: GNU build system for complex projects
• SCons: Python-based build system

---

🧠 Core Concepts

What is a Build System?

A build system is a tool that automates the process of converting source code into executable programs. Think of it as a recipe that knows exactly what ingredients (source files) are needed and in what order to combine them.

┌─────────────────────────────────────────────────────────────┐
│                    Build System Flow                        │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │   Source    │───▶│   Build     │───▶│  Executable │    │
│  │   Files     │    │   System    │    │   Program   │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│         │                   │                   │          │
│         ▼                   ▼                   ▼          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │ Dependencies│    │ Compilation │    │   Linking   │    │
│  │   Graph     │    │   Rules     │    │   Process   │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│                                                           │
│  The build system knows:                                  │
│  • Which files depend on which                            │
│  • What order to compile things                            │
│  • How to link everything together                        │
│  • What to rebuild when files change                      │
└─────────────────────────────────────────────────────────────┘

Why Not Just Compile Manually?

Manual Compilation Approach:

┌─────────────────────────────────────────────────────────────┐
│                    Manual Compilation                      │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  $ gcc -c main.c -o main.o                               │
│  $ gcc -c helper.c -o helper.o                           │
│  $ gcc -c utils.c -o utils.o                             │
│  $ gcc main.o helper.o utils.o -o myprogram              │
│                                                           │
│  ❌ Problems:                                             │
│  • Have to remember all commands                          │
│  • Easy to forget a file                                  │
│  • No dependency checking                                 │
│  • Rebuild everything every time                          │
│  • Different commands for different platforms             │
│  • No parallel compilation                                │
└─────────────────────────────────────────────────────────────┘

Build System Approach:

┌─────────────────────────────────────────────────────────────┐
│                    Build System Approach                   │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  $ make                                                    │
│                                                           │
│  ✅ Benefits:                                             │
│  • Single command builds everything                       │
│  • Only rebuilds what changed                             │
│  • Automatic dependency checking                          │
│  • Parallel compilation possible                          │
│  • Works across different platforms                       │
│  • Easy to add new files                                 │
└─────────────────────────────────────────────────────────────┘

Dependency Management

The key insight is that build systems understand dependencies - which files need other files to be built first:

┌─────────────────────────────────────────────────────────────┐
│                    Dependency Graph                        │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │   main.c    │    │  helper.c   │    │   utils.c   │    │
│  └─────┬───────┘    └─────┬───────┘    └─────┬───────┘    │
│        │                  │                  │            │
│        ▼                  ▼                  ▼            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │   main.o    │    │  helper.o   │    │   utils.o   │    │
│  └─────┬───────┘    └─────┬───────┘    └─────┬───────┘    │
│        │                  │                  │            │
│        └──────────────────┼──────────────────┘            │
│                           │                               │
│                           ▼                               │
│                    ┌─────────────┐                        │
│                    │ myprogram   │                        │
│                    └─────────────┘                        │
│                                                           │
│  Build order: utils.o → helper.o → main.o → myprogram     │
│                                                           │
│  If helper.c changes, only helper.o and myprogram         │
│  need to be rebuilt (not utils.o or main.o)               │
└─────────────────────────────────────────────────────────────┘

---

🏗️ Build System Types

Make-Based Systems

Make is the traditional build system that uses rules and dependencies:

Strengths:

• Simple and direct
• Widely supported
• Good for small to medium projects
• Easy to understand and debug

Weaknesses:

• Limited cross-platform support
• No built-in dependency resolution
• Can become complex for large projects
• Platform-specific syntax differences

CMake-Based Systems

CMake is a modern build system generator that creates platform-specific build files:

Strengths:

• Cross-platform compatibility
• Automatic dependency resolution
• Supports complex project structures
• Generates IDE project files
• Modern C++ features

Weaknesses:

• More complex than Make
• Steeper learning curve
• Generated files can be hard to debug
• Overkill for simple projects

IDE-Integrated Systems

Many IDEs have their own build systems:

Examples:

• Arduino IDE: Built-in build system for Arduino projects
• STM32CubeIDE: Eclipse-based with integrated build tools
• IAR Workbench: Proprietary build system
• Keil MDK: ARM-specific build tools

---

🔧 Make Build System

Basic Makefile Structure

A Makefile is a set of rules that tell the build system what to do:

# Simple Makefile for embedded project
PROJECT_NAME = my_project
TARGET = $(PROJECT_NAME).elf

# Source files
SRCS = main.c helper.c utils.c

# Object files (replace .c with .o)
OBJS = $(SRCS:.c=.o)

# Compiler and flags
CC = arm-none-eabi-gcc
CFLAGS = -mcpu=cortex-m4 -Wall -O2

# Default target
all: $(TARGET)

# Link the program
$(TARGET): $(OBJS)
	$(CC) $(OBJS) -o $@

# Compile source files
%.o: %.c
	$(CC) $(CFLAGS) -c $< -o $@

# Clean build files
clean:
	rm -f $(OBJS) $(TARGET)

Key Concepts:

• Targets: What you want to build (like all, clean)
• Dependencies: What needs to exist before building a target
• Rules: Commands to execute when building a target
• Variables: Reusable values (like CC, CFLAGS)

How Make Works

1. Reads the Makefile to understand the project structure
2. Builds a dependency graph to see what depends on what
3. Determines what needs to be built based on what changed
4. Executes the rules in the correct order
5. Only rebuilds what’s necessary (incremental builds)

---

🚀 CMake Build System

Basic CMakeLists.txt

CMake uses a more declarative approach:

# CMakeLists.txt for embedded project
cmake_minimum_required(VERSION 3.16)
project(MyProject)

# Set C standard
set(CMAKE_C_STANDARD 99)

# Set compiler flags
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mcpu=cortex-m4 -Wall -O2")

# Add source files
set(SOURCES
    main.c
    helper.c
    utils.c
)

# Create executable
add_executable(${PROJECT_NAME} ${SOURCES})

Key Concepts:

• Declarative: You describe what you want, not how to do it
• Cross-platform: Same file works on different systems
• Modern: Supports modern C/C++ features
• Flexible: Easy to add libraries and complex configurations

CMake Build Process

┌─────────────────────────────────────────────────────────────┐
│                    CMake Build Process                      │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │ CMakeLists. │───▶│   CMake     │───▶│   Makefile  │    │
│  │     txt     │    │  Generator  │    │   (or other)│    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│                                                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │   Source    │───▶│   Build     │───▶│  Executable │    │
│  │   Files     │    │   System    │    │   Program   │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│                                                           │
│  CMake generates the build system, then the build         │
│  system builds your program                               │
└─────────────────────────────────────────────────────────────┘

---

⚡ Advanced Features

Parallel Builds

Modern build systems can compile multiple files simultaneously:

┌─────────────────────────────────────────────────────────────┐
│                    Parallel vs Sequential                   │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  Sequential Build:                                        │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐            │
│  │file1│─▶│file2│─▶│file3│─▶│file4│─▶│link │            │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘            │
│  Total time: 5 units                                      │
│                                                           │
│  Parallel Build:                                          │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐                      │
│  │file1│  │file2│  │file3│  │file4│                      │
│  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘                      │
│     │        │        │        │                          │
│     └────────┼────────┼────────┘                          │
│               ▼        ▼                                  │
│            ┌─────┐  ┌─────┐                              │
│            │link │  │link │                              │
│            └─────┘  └─────┘                              │
│  Total time: 2 units (with 4 cores)                      │
└─────────────────────────────────────────────────────────────┘

Incremental Builds

Build systems only rebuild what changed:

┌─────────────────────────────────────────────────────────────┐
│                    Incremental Build                       │
├─────────────────────────────────────────────────────────────┤
│                                                           │
│  First Build:                                             │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐                      │
│  │file1│  │file2│  │file3│  │file4│                      │
│  └─────┘  └─────┘  └─────┘  └─────┘                      │
│                                                           │
│  After changing file2:                                    │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐                      │
│  │file1│  │file2│  │file3│  │file4│                      │
│  │     │  │ ❌   │  │     │  │     │                      │
│  └─────┘  └─────┘  └─────┘  └─────┘                      │
│                                                           │
│  Only rebuild:                                            │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐                      │
│  │     │  │file2│  │     │  │     │                      │
│  │     │  │     │  │     │  │     │                      │
│  └─────┘  └─────┘  └─────┘  └─────┘                      │
│                                                           │
│  ✅ Saves time and ensures consistency                     │
└─────────────────────────────────────────────────────────────┘

---

🧪 Guided Labs

Lab 1: Simple Makefile

Objective: Understand basic Makefile concepts.

Setup: Create a project with two source files that depend on each other.

Steps:

1. Create main.c and helper.c files
2. Write a simple Makefile with basic rules
3. Build the project and observe the output
4. Modify one file and rebuild - notice what gets recompiled

Expected Outcome: Understanding of how Make tracks dependencies and only rebuilds what’s necessary.

Lab 2: CMake Basics

Objective: Learn modern CMake approach.

Setup: Convert the Make project to use CMake.

Steps:

1. Create a CMakeLists.txt file
2. Configure the project with CMake
3. Build using the generated build system
4. Compare with the Make approach

Expected Outcome: Understanding of CMake’s declarative approach and cross-platform benefits.

Lab 3: Build Optimization

Objective: Learn about build performance.

Setup: Create a larger project with many source files.

Steps:

1. Add more source files to the project
2. Measure build time with single-threaded builds
3. Enable parallel builds and measure improvement
4. Experiment with different optimization flags

Expected Outcome: Understanding of how build systems can optimize the build process.

---

✅ Check Yourself

Understanding Check

• Can you explain why build systems are better than manual compilation?
• Do you understand what dependencies are and why they matter?
• Can you explain the difference between Make and CMake?
• Do you understand what incremental builds are?
• Can you explain why parallel builds are faster?

Application Check

• Can you create a basic Makefile for a simple project?
• Do you know how to write a basic CMakeLists.txt file?
• Can you add new source files to an existing build system?
• Do you understand how to clean and rebuild projects?
• Can you configure build options and compiler flags?

Analysis Check

• Can you choose between Make and CMake for different projects?
• Do you understand the trade-offs of different build configurations?
• Can you optimize build performance for your specific needs?
• Do you know how to debug build system issues?
• Can you design a build system for a complex embedded project?

---

🔗 Cross-links

Related Topics

• Cross-Compilation Setup: Setting up build systems for different target architectures
• Version Control Workflows: Integrating build systems with version control
• System Integration: Understanding how build systems fit into the development workflow
• Embedded C Programming: Understanding the source code that build systems compile

Further Reading

• GNU Make Manual: Official Make documentation and examples
• CMake Documentation: Official CMake user guide and reference
• Build System Best Practices: Industry standards and recommendations
• Embedded Build Systems: Specialized considerations for embedded development

Industry Standards

• POSIX Make: Standard Make behavior across Unix-like systems
• CMake: Industry-standard build system generator
• GNU Build System: Autotools for complex projects
• Ninja: Fast build system used by many modern projects