Skip to content

Configuration Reference

This document details all configuration options available in the EmbSec Kit build system.

CMake Configuration Options

Build Options

EMBSEC_BUILD_LABS

Enable/disable building of lab exercises.

  • Type: BOOL
  • Default: ON
  • Example: -DEMBSEC_BUILD_LABS=OFF

EMBSEC_BUILD_TESTS

Enable/disable building of unit tests.

  • Type: BOOL
  • Default: OFF
  • Example: -DEMBSEC_BUILD_TESTS=ON

EMBSEC_BUILD_DOCS

Enable/disable building of documentation.

  • Type: BOOL
  • Default: OFF
  • Example: -DEMBSEC_BUILD_DOCS=ON

EMBSEC_VERBOSE

Enable verbose output during build.

  • Type: BOOL
  • Default: OFF
  • Example: -DEMBSEC_VERBOSE=ON

Standard CMake Options

CMAKE_BUILD_TYPE

Specifies the build configuration.

  • Type: STRING
  • Values: Debug, Release, RelWithDebInfo, MinSizeRel
  • Default: Debug
  • Example: -DCMAKE_BUILD_TYPE=Release

CMAKE_INSTALL_PREFIX

Installation directory prefix.

  • Type: PATH
  • Default: /usr/local (Unix) or C:/Program Files (Windows)
  • Example: -DCMAKE_INSTALL_PREFIX=/opt/embsec

CMAKE_TOOLCHAIN_FILE

Cross-compilation toolchain file.

  • Type: FILEPATH
  • Example: -DCMAKE_TOOLCHAIN_FILE=sdk/cmake/TM4CToolchain.cmake

Toolchain Files

TM4C Hardware Toolchain

File: sdk/cmake/TM4CToolchain.cmake

Configures for TM4C123GH6PM microcontroller:

  • Compiler: arm-none-eabi-gcc
  • Target: Cortex-M4F
  • FPU: Hardware floating-point
  • Optimization: Size-optimized for embedded

QEMU Emulation Toolchain

File: sdk/cmake/LM3S6965Toolchain.cmake

Configures for LM3S6965 QEMU emulation:

  • Compiler: arm-none-eabi-gcc
  • Target: Cortex-M3
  • FPU: Software floating-point
  • Optimization: Debug-friendly

Environment Variables

Build Control

BUILD_DIR

Specifies the build directory for hardware builds.

  • Default: build
  • Used by: Makefile

BUILD_QEMU_DIR

Specifies the build directory for QEMU builds.

  • Default: build-qemu
  • Used by: Makefile, test scripts

BUILD_TYPE

Sets the CMake build type when using Make targets.

  • Default: Debug
  • Values: Debug, Release
  • Used by: Makefile

Tool Paths

The build system automatically searches for required tools in PATH:

Required Tools

  • cmake - Build system generator
  • arm-none-eabi-gcc - ARM cross-compiler
  • arm-none-eabi-objcopy - Binary utilities
  • arm-none-eabi-size - Size reporting

Optional Tools

  • qemu-system-arm - ARM system emulator
  • lm4flash - TI Stellaris/Tiva flash programmer
  • clang-format - Code formatter
  • python3 - Test runner
  • mkdocs - Documentation generator

Python Environment

PYTHONPATH

Extended by test scripts to include common test utilities:

  • Adds labs/common to path for test_framework.py

Configuration Files

CMake Preset Configuration

File: CMakePresets.json

Defines named configuration presets:

{
  "configurePresets": [
    {
      "name": "embedded",
      "toolchainFile": "${sourceDir}/sdk/cmake/TM4CToolchain.cmake",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "EMBSEC_BUILD_LABS": "ON"
      }
    }
  ]
}

Lab Configuration

File: labs/*/metadata.yml

Per-lab metadata:

name: "Buffer Overflow"
difficulty: "beginner"
topics:
  - "memory corruption"
  - "stack exploitation"
estimated_time: "2 hours"
prerequisites:
  - "C programming"
  - "Assembly basics"

Docker Environment

File: tools/docker/env.example

Docker container configuration: 

# User configuration
USER_UID=1000
USER_GID=1000

# Tool versions
ARM_TOOLCHAIN_VERSION=10.3-2021.10
QEMU_VERSION=6.2.0

Compiler Flags

Debug Configuration

Common flags for debug builds:

  • -g - Debug symbols
  • -O0 - No optimization
  • -DDEBUG - Debug macro defined
  • -fno-omit-frame-pointer - Better stack traces

Release Configuration

Common flags for release builds:

  • -O2 or -Os - Optimization
  • -DNDEBUG - Disable assertions
  • -flto - Link-time optimization

ARM-Specific Flags

Cortex-M4F (TM4C)

-mcpu=cortex-m4
-mthumb
-mfloat-abi=hard
-mfpu=fpv4-sp-d16

Cortex-M3 (LM3S)

-mcpu=cortex-m3
-mthumb
-mfloat-abi=soft

Security Flags

Labs may use different security flags:

  • -fno-stack-protector - Disable stack canaries
  • -z execstack - Allow executable stack
  • -no-pie - Disable position-independent executable

Lab-Specific Configuration

Compile Definitions

Each lab receives:

  • LAB_NAME - String name of the lab
  • LAB_SALT - Unique salt for flag generation
  • Custom definitions from embsec_add_lab()

Memory Layout

Controlled by linker script labs/common/tm4c123gh6pm.ld:

  • Flash: 256KB starting at 0x00000000
  • SRAM: 32KB starting at 0x20000000
  • Stack: Top of SRAM growing down
  • Heap: After BSS growing up

Build Profiles

Development Profile

cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DEMBSEC_VERBOSE=ON \
  -DEMBSEC_BUILD_TESTS=ON

Release Profile

cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DEMBSEC_BUILD_DOCS=ON

Testing Profile

cmake -B build-test \
  --preset host-debug \
  -DEMBSEC_BUILD_TESTS=ON

Documentation Profile

cmake -B build-docs \
  --preset docs

Platform-Specific Notes

Linux

  • Default install prefix: /usr/local
  • Tool search paths: /usr/bin, /usr/local/bin
  • Package manager tools usually work

macOS

  • May need to install tools via Homebrew
  • Default install prefix: /usr/local
  • XCode command line tools required

Windows

  • Use WSL2 or MSYS2 recommended
  • Native Windows builds not fully supported
  • Path separators handled by CMake

Troubleshooting Configuration

Common Issues

  1. Toolchain not found
  2. Ensure arm-none-eabi-gcc is in PATH

  3. Install via package manager or download from ARM

  4. TivaWare not found

  5. Warning is non-fatal for QEMU builds
  6. Required for hardware builds

  7. Place in vendor/tivaware/

  8. CMake version too old

  9. Requires CMake 3.20 or newer
  10. Update via package manager or download

Verification Commands

Check configuration: 

cmake -B build --preset embedded
cmake -L build | grep EMBSEC

Check toolchain: 

arm-none-eabi-gcc --version
qemu-system-arm --version

See Also