Environment Setup¶

This guide walks through setting up a complete development environment for EmbSec Kit, including all tools, dependencies, and optional components.

System Requirements¶

Minimum Requirements¶

OS: Linux, macOS, or WSL2 on Windows
RAM: 4GB minimum, 8GB recommended
Disk: 2GB free space
CPU: x86_64 or ARM64

Supported Platforms¶

Platform	Status	Notes
Ubuntu 20.04+	✓ Full support	Recommended
Debian 11+	✓ Full support	Tested
Arch Linux	✓ Full support	Rolling release
macOS 11+	✓ Full support	Intel & Apple Silicon
WSL2	✓ Full support	Windows 10/11
Native Windows	✗ Limited	Use WSL2 instead

Quick Setup¶

The fastest way to get started:

# Clone repository
git clone https://github.com/embsec/embsec-kit.git
cd embsec-kit

# Run automated setup
make setup

# Verify installation
make qemu-build
make qemu-01-buffer-overflow

Core Dependencies¶

1. Build Tools¶

CMake (3.20+)¶

# Ubuntu/Debian
sudo apt install cmake

# macOS
brew install cmake

# Arch
sudo pacman -S cmake

# From source (if too old)
wget https://github.com/Kitware/CMake/releases/download/v3.28.0/cmake-3.28.0.tar.gz
tar xzf cmake-3.28.0.tar.gz
cd cmake-3.28.0
./bootstrap && make && sudo make install

Ninja Build System¶

# Ubuntu/Debian
sudo apt install ninja-build

# macOS
brew install ninja

# Arch
sudo pacman -S ninja

2. ARM Toolchain¶

GNU ARM Embedded Toolchain¶

# Ubuntu/Debian
sudo apt install gcc-arm-none-eabi

# macOS
brew install --cask gcc-arm-embedded

# Arch
sudo pacman -S arm-none-eabi-gcc arm-none-eabi-gdb

# Manual installation (all platforms)
wget https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-eabi.tar.xz
tar xf arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-eabi.tar.xz
export PATH=$PWD/arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-eabi/bin:$PATH

Verify installation:

arm-none-eabi-gcc --version
arm-none-eabi-gdb --version

3. QEMU¶

QEMU ARM System Emulator¶

# Ubuntu/Debian
sudo apt install qemu-system-arm

# macOS
brew install qemu

# Arch
sudo pacman -S qemu-system-arm

# Build from source (latest features)
git clone https://gitlab.com/qemu-project/qemu.git
cd qemu
./configure --target-list=arm-softmmu
make -j$(nproc)
sudo make install

Verify QEMU:

qemu-system-arm --version
qemu-system-arm -M help | grep lm3s6965evb

4. Python Environment¶

Python 3 and pip¶

# Ubuntu/Debian
sudo apt install python3 python3-pip python3-venv

# macOS (usually pre-installed)
brew install python3

# Arch
sudo pacman -S python python-pip

Python Dependencies¶

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Basic requirements.txt:

pyserial>=3.5
pytest>=7.0
colorama>=0.4

Optional Components¶

1. Hardware Tools¶

OpenOCD (for hardware debugging)¶

# Ubuntu/Debian
sudo apt install openocd

# macOS
brew install openocd

# From source (latest)
git clone https://github.com/openocd-org/openocd.git
cd openocd
./bootstrap
./configure --enable-cmsis-dap
make
sudo make install

lm4flash (for TM4C programming)¶

# Build from source
git clone https://github.com/utzig/lm4tools.git
cd lm4tools/lm4flash
make
sudo cp lm4flash /usr/local/bin/

2. Development Tools¶

Code Editors¶

VS Code (recommended):

# Download from https://code.visualstudio.com/
# Install extensions:
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools
code --install-extension marus25.cortex-debug

Vim/Neovim with plugins:

" ~/.vimrc or init.vim
Plug 'dense-analysis/ale'          " Linting
Plug 'neoclide/coc.nvim'          " LSP support
Plug 'jackguo380/vim-lsp-cxx-highlight'

Static Analysis¶

# Clang tools
sudo apt install clang clang-format clang-tidy

# Cppcheck
sudo apt install cppcheck

# Include-what-you-use
sudo apt install iwyu

3. Documentation Tools¶

MkDocs¶

# Install MkDocs and theme
pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin

# Serve locally
mkdocs serve

# Build static site
mkdocs build

Doxygen¶

# Ubuntu/Debian
sudo apt install doxygen graphviz

# macOS
brew install doxygen graphviz

# Generate docs
doxygen Doxyfile

Platform-Specific Setup¶

Ubuntu/Debian¶

Complete setup script:

#!/bin/bash
# Update system
sudo apt update
sudo apt upgrade -y

# Install all dependencies
sudo apt install -y \
    build-essential \
    cmake ninja-build \
    gcc-arm-none-eabi \
    gdb-multiarch \
    qemu-system-arm \
    python3 python3-pip python3-venv \
    git curl wget \
    openocd \
    minicom screen

# Install VS Code
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/
sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/trusted.gpg.d/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install code

macOS¶

Using Homebrew:

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install \
    cmake ninja \
    qemu \
    python3 \
    openocd \
    minicom

# Install ARM toolchain
brew install --cask gcc-arm-embedded

# Install VS Code
brew install --cask visual-studio-code

Arch Linux¶

Using pacman and AUR:

# Core packages
sudo pacman -S \
    base-devel \
    cmake ninja \
    arm-none-eabi-gcc arm-none-eabi-gdb \
    qemu-system-arm \
    python python-pip \
    openocd \
    code

# AUR packages (using yay)
yay -S lm4flash-git

Windows (WSL2)¶

Install WSL2:
```
wsl --install -d Ubuntu
```
Inside WSL2:
```
# Follow Ubuntu instructions above
```

GUI support (for debugging):

# Install X server on Windows (VcXsrv or WSLg)
# In WSL2:
export DISPLAY=:0

Environment Configuration¶

Shell Configuration¶

Add to ~/.bashrc or ~/.zshrc:

# EmbSec development environment
export EMBSEC_ROOT="$HOME/projects/embsec-kit"
export PATH="$PATH:$EMBSEC_ROOT/tools/scripts"

# ARM toolchain
export PATH="$PATH:/opt/arm-gnu-toolchain/bin"

# Aliases
alias embsec="cd $EMBSEC_ROOT"
alias qemu-arm="qemu-system-arm -M lm3s6965evb"

# Functions
embsec-debug() {
    make debug-$1
}

embsec-test() {
    make unittest-lab LAB=$1
}

Git Configuration¶

# Set up Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Helpful aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.cm commit

# Editor
git config --global core.editor "code --wait"

IDE Configuration¶

VS Code¶

.vscode/settings.json:

{
    "cmake.configureOnOpen": true,
    "cmake.defaultVariants": {
        "buildType": {
            "default": "debug"
        }
    },
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
    "files.associations": {
        "*.h": "c",
        "*.c": "c"
    },
    "editor.formatOnSave": true,
    "C_Cpp.clang_format_fallbackStyle": "LLVM"
}

.vscode/launch.json:

id=__codelineno-26-1 name=__codelineno-26-1 href=#__codelineno-26-1>{ "version": "0.2.0", "configurations": [ { "name": "Debug Lab (QEMU)", "type": "cortex-debug", "request": "launch", "servertype": "qemu", "cwd": "${workspaceRoot}", "executable": "${workspaceRoot}/build/labs/${input:labName}/${input:labName}", "cpu": "cortex-m3", "machine": "lm3s6965evb" } ], "inputs": [ { "id": "labName", "type": "promptString", "description": "Lab name (e.g., 01-buffer-overflow)" } ] class=p>}

CLion¶

Open project root
Select CMake preset: "embedded"
Configure toolchain:
Name: ARM Embedded
C Compiler: arm-none-eabi-gcc
C++ Compiler: arm-none-eabi-g++
Debugger: arm-none-eabi-gdb

Verification¶

Check Installation¶

Run verification script:

#!/bin/bash
# verify_setup.sh

echo "Checking EmbSec development environment..."

# Function to check command
check_cmd() {
    if command -v $1 &> /dev/null; then
        echo "✓ $1: $(command -v $1)"
        $1 --version 2>&1 | head -1
    else
        echo "✗ $1: NOT FOUND"
        return 1
    fi
}

# Check all tools
check_cmd cmake
check_cmd ninja
check_cmd arm-none-eabi-gcc
check_cmd arm-none-eabi-gdb
check_cmd qemu-system-arm
check_cmd python3
check_cmd git

# Check QEMU board support
echo -n "✓ QEMU board support: "
qemu-system-arm -M help 2>&1 | grep -q lm3s6965evb && echo "lm3s6965evb found" || echo "NOT FOUND"

# Check Python modules
echo "✓ Python modules:"
python3 -c "import serial; print('  - pyserial:', serial.__version__)"

Test Build¶

# Test basic build
cmake --preset qemu
cmake --build build-qemu --target 01-buffer-overflow

# Test execution
qemu-system-arm -M lm3s6965evb -kernel build-qemu/labs/01-buffer-overflow/01-buffer-overflow -nographic

Troubleshooting¶

Common Issues¶

Permission denied for serial ports:

# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and back in

QEMU crashes immediately:

Check binary is built for correct target
Verify using LM3S6965 toolchain for QEMU
Check memory regions in linker script

CMake can't find compiler:

# Explicitly set compiler
export CC=arm-none-eabi-gcc
export CXX=arm-none-eabi-g++

Python module not found:

# Ensure virtual environment is activated
source venv/bin/activate

# Or install globally
pip3 install --user pyserial

Getting Help¶

Check documentation: docs/
Run diagnostics: make info
Enable verbose output: VERBOSE=1 make
Check GitLab issues
Ask on forums/Discord

Advanced Setup¶

Docker Environment¶

Dockerfile for consistent environment:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    build-essential \
    cmake ninja-build \
    gcc-arm-none-eabi \
    qemu-system-arm \
    python3 python3-pip \
    git

WORKDIR /workspace

Build and use:

docker build -t embsec-dev .
docker run -it -v $(pwd):/workspace embsec-dev

CI/CD Integration¶

GitLab runner setup:

# .gitlab-ci.yml
variables:
  GIT_SUBMODULE_STRATEGY: recursive

before_script:
  - apt-get update -qq
  - apt-get install -y -qq cmake ninja-build gcc-arm-none-eabi

build:
  script:
    - cmake --preset qemu
    - cmake --build build-qemu

Next Steps¶

Building - Build your first lab
Testing - Run the test suite
Debugging - Set up debugging workflow
Review Lab Guide - Start learning!