Building EmbSec Kit¶

This guide covers how to build the EmbSec Kit framework and labs for both hardware targets and QEMU emulation.

Prerequisites¶

Before building, ensure you have all required dependencies installed:

• CMake (3.20 or later)
• ARM GCC Toolchain (arm-none-eabi-gcc)
• Ninja build system (recommended)
• Python 3 (for testing and utility scripts)
• QEMU (for emulation)

Installing Dependencies¶

Ubuntu/Debian¶

sudo apt update
sudo apt install cmake ninja-build gcc-arm-none-eabi qemu-system-arm python3

macOS¶

brew install cmake ninja arm-none-eabi-gcc qemu python3

Arch Linux¶

sudo pacman -S cmake ninja arm-none-eabi-gcc qemu-system-arm python

Quick Start¶

The easiest way to get started is using the Makefile wrapper:

# One-time setup
make setup

# Build for QEMU
make qemu-build

# Build for hardware
make build

Build System Overview¶

EmbSec Kit uses CMake as its primary build system with several components:

• CMake - Main build configuration
• CMakePresets.json - Predefined build configurations
• Makefile - Convenience wrapper for common tasks
• Toolchain files - Cross-compilation configurations

Building for Hardware (TM4C123GH6PM)¶

Using CMake Presets¶

# Configure with embedded preset
cmake --preset embedded

# Build all targets
cmake --build build

# Build specific targets
cmake --build build --target labs        # All labs
cmake --build build --target embsec-sdk  # SDK only
cmake --build build --target 01-buffer-overflow  # Specific lab

Using Make Wrapper¶

# Configure and build everything
make configure
make build

# Build specific components
make sdk   # Build SDK only
make labs  # Build all labs

Build Types¶

• Debug (default) - Includes debug symbols, no optimization
• Release - Optimized for size and speed
• MinSizeRel - Optimized for minimum size
• RelWithDebInfo - Release with debug info

To change build type:

cmake --preset embedded -DCMAKE_BUILD_TYPE=Release

Building for QEMU (LM3S6965)¶

QEMU builds use a different toolchain configuration for the emulated Stellaris LM3S6965 board.

Using Toolchain File¶

# Configure for QEMU
cmake -B build-qemu --toolchain sdk/cmake/LM3S6965Toolchain.cmake \
      -DCMAKE_BUILD_TYPE=Debug -DEMBSEC_BUILD_LABS=ON

# Build
cmake --build build-qemu --target labs

Using Make Wrapper¶

# Configure and build for QEMU
make qemu-build

# Run a lab in QEMU
make qemu-01-buffer-overflow

Build Options¶

CMake Options¶

Example:

cmake -B build -DEMBSEC_BUILD_TESTS=ON -DEMBSEC_VERBOSE=ON

Environment Variables¶

Build Outputs¶

After building, you'll find:

build/
├── labs/
│   ├── 01-buffer-overflow/
│   │   ├── 01-buffer-overflow      # ELF executable
│   │   ├── 01-buffer-overflow.bin  # Binary format
│   │   ├── 01-buffer-overflow.hex  # Intel HEX format
│   │   └── 01-buffer-overflow.map  # Linker map
│   └── ...
├── sdk/
│   └── libembsec-sdk.a            # SDK static library
└── compile_commands.json          # For IDE integration

Lab-Specific Builds¶

Building Individual Labs¶

# Using CMake
cmake --build build --target 01-buffer-overflow

# Using Make
make 01-buffer-overflow

Packaging Labs¶

Create distributable packages:

# Package all labs
make package-labs

# Package specific lab
make package-lab LAB=01-buffer-overflow

Packages are created in build/packages/ as ZIP files.

Cross-Compilation Details¶

ARM Cortex-M4 (Hardware)¶

The hardware build targets the TM4C123GH6PM microcontroller:

• CPU: ARM Cortex-M4F
• FPU: Single-precision
• Thumb: Thumb-2 instruction set
• Flags: -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16

ARM Cortex-M3 (QEMU)¶

The QEMU build targets the LM3S6965 microcontroller:

• CPU: ARM Cortex-M3
• Thumb: Thumb-2 instruction set
• Flags: -mcpu=cortex-m3 -mthumb

TivaWare Integration¶

The build system expects TivaWare at vendor/tivaware/. If not found:

1. Download TivaWare from TI
2. Extract to vendor/tivaware/
3. Rebuild

The build will warn but continue without TivaWare support.

Common Build Issues¶

CMake Version Too Old¶

CMake Error: CMake 3.20 or higher is required

Update CMake or use a newer version from pip:

pip install --user cmake

ARM Toolchain Not Found¶

arm-none-eabi-gcc not found! Please install ARM toolchain.

Ensure the ARM toolchain is in your PATH:

export PATH=/path/to/arm-none-eabi/bin:$PATH

QEMU Build Fails¶

Ensure you're using the correct toolchain:

cmake -B build-qemu --toolchain sdk/cmake/LM3S6965Toolchain.cmake

Linker Script Not Found¶

This usually means the common files aren't accessible. Check:

• You're building from the project root
• The labs/common/ directory exists

Advanced Build Configuration¶

Custom Toolchain¶

Create your own toolchain file:

# MyToolchain.cmake
set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_C_COMPILER /custom/path/arm-none-eabi-gcc)
# ... more settings

Use it:

cmake -B build --toolchain MyToolchain.cmake

Out-of-Tree Builds¶

Always use out-of-source builds:

# Good
cmake -B build-custom -S .

# Bad (will error)
cmake .

Parallel Builds¶

Speed up compilation:

# Using CMake
cmake --build build -j8

# Using Make wrapper (auto-detects cores)
make -j

IDE Integration¶

VS Code¶

The build system generates compile_commands.json for IntelliSense:

1. Install C/C++ extension
2. Configure: .vscode/c_cpp_properties.json

   {
       "configurations": [{
           "name": "EmbSec",
           "compileCommands": "${workspaceFolder}/build/compile_commands.json"
       }]
   }
   

CLion¶

1. Open project root
2. Select "embedded" preset
3. Build configuration will be auto-detected

Continuous Integration¶

The project includes GitLab CI configuration:

# .gitlab-ci.yml
build:
  script:
    - cmake --preset embedded
    - cmake --build build

Next Steps¶

• Testing - Run tests and validate builds
• Debugging - Debug labs with GDB
• Environment Setup - Complete development setup