Build and Flash¶

This guide covers building Nexus for different platforms and flashing to target hardware.

Build System Overview ¶

Nexus uses CMake as its build system with Python scripts for convenience. The build process:

Configuration: Kconfig generates nexus_config.h
CMake Configuration: Selects platform, toolchain, and options
Compilation: Builds libraries and applications
Linking: Creates executables or firmware images
Post-processing: Generates .bin, .hex files for embedded targets

Build Methods ¶

There are three ways to build Nexus:

Python Scripts (Recommended) - Cross-platform, easy to use
CMake Directly - More control, standard CMake workflow
IDE Integration - Visual Studio, VS Code, CLion

Using Python Build Scripts ¶

The Python build script provides a unified interface across platforms.

Basic Usage ¶

# Build for native platform (default)
python scripts/building/build.py

# Build for specific platform
python scripts/building/build.py --platform stm32f4

# Build with specific toolchain
python scripts/building/build.py --platform stm32f4 --toolchain arm-none-eabi

Build Options ¶

# Build type
python scripts/building/build.py -t debug      # Debug build
python scripts/building/build.py -t release    # Release build

# Clean build
python scripts/building/build.py -c            # Clean before build

# Parallel build
python scripts/building/build.py -j 8          # Use 8 cores

# Verbose output
python scripts/building/build.py -v            # Show all commands

# Specific application
python scripts/building/build.py --app blinky  # Build only blinky

Combined Options ¶

# Release build for STM32F4 with 8 parallel jobs
python scripts/building/build.py --platform stm32f4 -t release -j 8

# Clean debug build for native with verbose output
python scripts/building/build.py -c -t debug -v

Using CMake Directly ¶

For more control, use CMake directly.

Native Platform ¶

# Configure
cmake -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DNEXUS_PLATFORM=native \
    -DNEXUS_BUILD_TESTS=ON \
    -DNEXUS_BUILD_EXAMPLES=ON

# Build
cmake --build build --config Release

# Or with parallel jobs
cmake --build build --config Release -j 8

STM32F4 Platform ¶

# Configure
cmake -B build-stm32f4 \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=stm32f4 \
    -DNEXUS_BUILD_TESTS=OFF \
    -DNEXUS_BUILD_EXAMPLES=ON

# Build
cmake --build build-stm32f4 --config Release

STM32H7 Platform ¶

# Configure
cmake -B build-stm32h7 \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=stm32h7 \
    -DNEXUS_BUILD_TESTS=OFF

# Build
cmake --build build-stm32h7 --config Release

GD32 Platform ¶

# Configure
cmake -B build-gd32 \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=gd32

# Build
cmake --build build-gd32 --config Release

Build Configuration ¶

CMake Options ¶

Option	Type	Default	Description
`NEXUS_PLATFORM`	STRING	native	Target platform
`NEXUS_OSAL_BACKEND`	STRING	baremetal	OSAL backend
`NEXUS_BUILD_TESTS`	BOOL	ON	Build unit tests
`NEXUS_BUILD_EXAMPLES`	BOOL	ON	Build examples
`NEXUS_ENABLE_COVERAGE`	BOOL	OFF	Enable coverage
`CMAKE_BUILD_TYPE`	STRING	Debug	Build type

Platform Options ¶

Platform	Description
`native`	Native platform for host testing
`stm32f4`	STM32F4 series (Cortex-M4)
`stm32h7`	STM32H7 series (Cortex-M7)
`gd32`	GD32 series

OSAL Backend Options ¶

Backend	Description
`baremetal`	No RTOS (default)
`freertos`	FreeRTOS integration
`rtthread`	RT-Thread integration
`zephyr`	Zephyr RTOS integration

Build Type Options ¶

Build Type	Description
`Debug`	Debug build with symbols, no optimization
`Release`	Release build with optimization
`RelWithDebInfo`	Release with debug info
`MinSizeRel`	Minimum size release

Kconfig Configuration ¶

Using Defconfig ¶

Each platform has a default configuration:

# Copy platform defconfig
cp platforms/native/defconfig .config

# Or for STM32F4
cp platforms/stm32/defconfig_stm32f4 .config

# Build with this configuration
cmake -B build
cmake --build build

Manual Configuration ¶

Edit .config file directly:

# Platform selection
CONFIG_PLATFORM_STM32F4=y

# Enable GPIO
CONFIG_HAL_GPIO=y
CONFIG_HAL_GPIO_A_5=y
CONFIG_HAL_GPIO_A_5_MODE=OUTPUT_PP

# Enable UART
CONFIG_HAL_UART=y
CONFIG_HAL_UART_1=y
CONFIG_HAL_UART_1_BAUDRATE=115200

Using menuconfig (Linux/macOS)¶

# Install menuconfig dependencies
pip install kconfiglib

# Run menuconfig
python scripts/kconfig/generate_config.py --menuconfig

# Build with new configuration
cmake -B build
cmake --build build

See Configuration for detailed Kconfig usage.

Build Output ¶

Native Platform ¶

build/
├── applications/
│   ├── blinky/
│   │   └── blinky.exe          # Windows
│   │   └── blinky              # Linux/macOS
│   ├── shell_demo/
│   │   └── shell_demo.exe
│   └── config_demo/
│       └── config_demo.exe
└── tests/
    └── nexus_tests.exe

Embedded Platforms ¶

build-stm32f4/
├── applications/
│   ├── blinky/
│   │   ├── blinky.elf          # ELF with debug symbols
│   │   ├── blinky.bin          # Raw binary
│   │   ├── blinky.hex          # Intel HEX format
│   │   └── blinky.map          # Memory map
│   ├── shell_demo/
│   │   ├── shell_demo.elf
│   │   ├── shell_demo.bin
│   │   └── shell_demo.hex
│   └── config_demo/
│       ├── config_demo.elf
│       ├── config_demo.bin
│       └── config_demo.hex
└── hal/
    └── libnexus_hal.a

File Formats ¶

Format	Description
`.elf`	Executable with debug symbols (for debugging)
`.bin`	Raw binary (for flashing)
`.hex`	Intel HEX format (for some programmers)
`.map`	Memory map showing symbol addresses and sizes

Flashing to Hardware ¶

STM32F4 Discovery ¶

Using OpenOCD¶

# Flash ELF file
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
    -c "program build-stm32f4/applications/blinky/blinky.elf verify reset exit"

# Flash BIN file
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
    -c "program build-stm32f4/applications/blinky/blinky.bin 0x08000000 verify reset exit"

Using st-flash¶

# Flash BIN file
st-flash write build-stm32f4/applications/blinky/blinky.bin 0x8000000

# Erase flash
st-flash erase

Using STM32CubeProgrammer¶

Open STM32CubeProgrammer
Connect to ST-Link
Select .hex or .bin file
Set start address (0x08000000 for STM32F4)
Click "Download"

STM32H7 Nucleo ¶

Using OpenOCD¶

# Flash ELF file
openocd -f interface/stlink.cfg -f target/stm32h7x.cfg \
    -c "program build-stm32h7/applications/blinky/blinky.elf verify reset exit"

Using st-flash¶

# Flash BIN file
st-flash --connect-under-reset write build-stm32h7/applications/blinky/blinky.bin 0x8000000

GD32 Boards ¶

Using OpenOCD¶

# Flash ELF file
openocd -f interface/stlink.cfg -f target/gd32vf103.cfg \
    -c "program build-gd32/applications/blinky/blinky.elf verify reset exit"

Using J-Link¶

# Create J-Link script
cat > flash.jlink << EOF
connect
device GD32VF103CBT6
speed 4000
loadfile build-gd32/applications/blinky/blinky.bin 0x08000000
r
g
exit
EOF

# Flash
JLinkExe -CommanderScript flash.jlink

Debugging ¶

Native Platform ¶

Using GDB¶

# Start GDB
gdb ./build/applications/blinky/blinky

# GDB commands
(gdb) break main
(gdb) run
(gdb) next
(gdb) print variable
(gdb) continue

Using LLDB¶

# Start LLDB
lldb ./build/applications/blinky/blinky

# LLDB commands
(lldb) breakpoint set --name main
(lldb) run
(lldb) next
(lldb) print variable
(lldb) continue

STM32F4 Platform ¶

Using OpenOCD + GDB¶

Terminal 1 (OpenOCD):

# Start OpenOCD
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

Terminal 2 (GDB):

# Start GDB
arm-none-eabi-gdb build-stm32f4/applications/blinky/blinky.elf

# Connect to OpenOCD
(gdb) target remote localhost:3333

# Reset and halt
(gdb) monitor reset halt

# Load program
(gdb) load

# Set breakpoint
(gdb) break main

# Continue
(gdb) continue

Using VS Code¶

Install Cortex-Debug extension and use this launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug STM32F4",
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "openocd",
            "cwd": "${workspaceRoot}",
            "executable": "${workspaceRoot}/build-stm32f4/applications/blinky/blinky.elf",
            "configFiles": [
                "interface/stlink.cfg",
                "target/stm32f4x.cfg"
            ],
            "svdFile": "${workspaceRoot}/vendors/st/cmsis/stm32f4xx.svd"
        }
    ]
}

Press F5 to start debugging.

Using J-Link¶

# Start J-Link GDB server
JLinkGDBServer -device STM32F407VG -if SWD -speed 4000

# In another terminal, start GDB
arm-none-eabi-gdb build-stm32f4/applications/blinky/blinky.elf
(gdb) target remote localhost:2331
(gdb) monitor reset
(gdb) load
(gdb) break main
(gdb) continue

Serial Console ¶

For applications using UART (shell_demo, config_demo):

Windows ¶

Using PuTTY:

Download PuTTY from https://www.putty.org/
Select "Serial"
Set COM port (check Device Manager)
Set baud rate: 115200
Click "Open"

Using TeraTerm:

Download TeraTerm from https://ttssh2.osdn.jp/
File → New Connection → Serial
Select COM port
Setup → Serial Port: 115200, 8N1
Click "OK"

Linux ¶

Using screen:

# Find device
ls /dev/ttyUSB* /dev/ttyACM*

# Connect
screen /dev/ttyUSB0 115200

# Exit: Ctrl+A, then K

Using minicom:

# Configure
sudo minicom -s

# Connect
sudo minicom -D /dev/ttyUSB0 -b 115200

# Exit: Ctrl+A, then X

Using picocom:

# Connect
picocom -b 115200 /dev/ttyUSB0

# Exit: Ctrl+A, then Ctrl+X

macOS ¶

Using screen:

# Find device
ls /dev/tty.*

# Connect
screen /dev/tty.usbserial-* 115200

# Exit: Ctrl+A, then K

Troubleshooting ¶

Build Issues ¶

CMake configuration fails

CMake Error: Could not find toolchain file

Solution: Ensure ARM toolchain is installed and in PATH.

Compilation errors

error: 'CONFIG_HAL_GPIO' undeclared

Solution: Regenerate configuration:

python scripts/kconfig/generate_config.py --config .config --output nexus_config.h

Linker errors

undefined reference to 'hal_gpio_init'

Solution: Ensure all required libraries are linked in CMakeLists.txt.

Flash Issues ¶

Cannot connect to ST-Link

Error: libusb_open() failed with LIBUSB_ERROR_ACCESS

Solution (Linux): Add udev rules and user to dialout group:

sudo usermod -a -G dialout $USER
# Log out and log back in

Solution (Windows): Install ST-Link driver.

Flash verification failed

Solution: Erase flash before programming:

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
    -c "init" -c "reset halt" -c "flash erase_sector 0 0 last" -c "exit"

Wrong start address

Ensure correct flash start address:

STM32F4: 0x08000000
STM32H7: 0x08000000
GD32: 0x08000000

Debug Issues ¶

GDB cannot connect

Solution: Ensure OpenOCD is running and listening on port 3333.

Breakpoints not working

Solution: Build with debug symbols:

cmake -B build -DCMAKE_BUILD_TYPE=Debug

No serial output

Solution: Check UART configuration and connections:

Baud rate: 115200
Data bits: 8
Stop bits: 1
Parity: None
Flow control: None

Next Steps ¶

Now that you can build and flash:

First Application - Create your own application
Configuration - Customize your build with Kconfig
Examples Tour - Explore more examples
IDE Integration - Set up your IDE