Development Environment

This guide covers setting up a complete development environment for Nexus, including IDEs, debuggers, and development tools.

Overview

A proper development environment significantly improves productivity. This guide covers:

• IDE configuration (VS Code, CLion, Eclipse)

• Debugger setup (GDB, OpenOCD, J-Link)

• Code analysis tools

• Documentation tools

• Platform-specific configurations

Prerequisites

Before setting up your development environment, ensure you have completed:

• Environment Setup - Basic tool installation

• Quick Start - Verified build works

IDE Setup

Visual Studio Code

VS Code is the recommended IDE for Nexus development.

Installation

Windows:

winget install Microsoft.VisualStudioCode

Linux:

sudo snap install code --classic

macOS:

brew install --cask visual-studio-code

Required Extensions

Install these extensions for optimal development:

# C/C++ development
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cpptools-extension-pack
code --install-extension ms-vscode.cmake-tools
code --install-extension twxs.cmake

# Debugging
code --install-extension marus25.cortex-debug

# Code quality
code --install-extension llvm-vs-code-extensions.vscode-clangd
code --install-extension notskm.clang-tidy

# Documentation
code --install-extension cschlosser.doxdocgen
code --install-extension lextudio.restructuredtext

# Git
code --install-extension eamodio.gitlens

# Python (for scripts)
code --install-extension ms-python.python

Workspace Configuration

Nexus includes pre-configured VS Code settings in .vscode/:

.vscode/
├── settings.json          # Workspace settings
├── tasks.json             # Build tasks
├── launch.json            # Debug configurations
├── c_cpp_properties.json  # IntelliSense configuration
└── extensions.json        # Recommended extensions

settings.json - Key settings:

{
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
    "cmake.configureOnOpen": true,
    "cmake.buildDirectory": "${workspaceFolder}/build",
    "editor.formatOnSave": true,
    "editor.rulers": [80],
    "files.trimTrailingWhitespace": true,
    "files.insertFinalNewline": true,
    "C_Cpp.clang_format_style": "file",
    "clang-tidy.executable": "clang-tidy",
    "clang-tidy.lintOnSave": true
}

tasks.json - Build tasks:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build (Native Debug)",
            "type": "shell",
            "command": "python",
            "args": ["scripts/building/build.py", "-t", "debug"],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Build (STM32F4 Release)",
            "type": "shell",
            "command": "python",
            "args": [
                "scripts/building/build.py",
                "--platform", "stm32f4",
                "-t", "release"
            ]
        },
        {
            "label": "Run Tests",
            "type": "shell",
            "command": "python",
            "args": ["scripts/test/test.py"]
        },
        {
            "label": "Format Code",
            "type": "shell",
            "command": "python",
            "args": ["scripts/tools/format.py"]
        },
        {
            "label": "Generate Documentation",
            "type": "shell",
            "command": "python",
            "args": ["scripts/tools/docs.py"]
        }
    ]
}

launch.json - Debug configurations:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Native Application",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/build/applications/blinky/blinky",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        },
        {
            "name": "Debug STM32F4 (OpenOCD)",
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "openocd",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build-stm32f4/applications/blinky/blinky.elf",
            "device": "STM32F407VG",
            "configFiles": [
                "interface/stlink.cfg",
                "target/stm32f4x.cfg"
            ],
            "svdFile": "${workspaceFolder}/vendors/st/cmsis/stm32f4xx.svd",
            "runToMain": true,
            "preLaunchTask": "Build (STM32F4 Release)"
        },
        {
            "name": "Debug STM32F4 (J-Link)",
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "jlink",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build-stm32f4/applications/blinky/blinky.elf",
            "device": "STM32F407VG",
            "interface": "swd",
            "runToMain": true
        }
    ]
}

c_cpp_properties.json - IntelliSense:

{
    "configurations": [
        {
            "name": "Native",
            "includePath": [
                "${workspaceFolder}/**",
                "${workspaceFolder}/hal/include",
                "${workspaceFolder}/osal/include",
                "${workspaceFolder}/framework/*/include"
            ],
            "defines": [
                "NEXUS_PLATFORM_NATIVE",
                "DEBUG"
            ],
            "compilerPath": "/usr/bin/gcc",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "gcc-x64",
            "configurationProvider": "ms-vscode.cmake-tools"
        },
        {
            "name": "STM32F4",
            "includePath": [
                "${workspaceFolder}/**",
                "${workspaceFolder}/hal/include",
                "${workspaceFolder}/osal/include",
                "${workspaceFolder}/vendors/st/cmsis/Include"
            ],
            "defines": [
                "NEXUS_PLATFORM_STM32F4",
                "STM32F407xx",
                "USE_HAL_DRIVER"
            ],
            "compilerPath": "/usr/bin/arm-none-eabi-gcc",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "gcc-arm"
        }
    ],
    "version": 4
}

Keyboard Shortcuts

Useful VS Code shortcuts for Nexus development:

Shortcut	Action
Ctrl+Shift+B	Run build task
F5	Start debugging
Ctrl+Shift+P	Command palette
Ctrl+P	Quick file open
Ctrl+Shift+F	Search in files
F12	Go to definition
Shift+F12	Find all references
Ctrl+K Ctrl+F	Format selection
Ctrl+/	Toggle comment

CLion

CLion is a powerful C/C++ IDE from JetBrains.

Installation

Download from https://www.jetbrains.com/clion/

Student License: Free for students with .edu email

Configuration

1. Open Project:

   • File → Open → Select nexus directory

   • CLion will detect CMakeLists.txt automatically

2. Configure CMake:

   • File → Settings → Build, Execution, Deployment → CMake

   • Add profiles:

     • Debug (Native): -DNEXUS_PLATFORM=native -DNEXUS_BUILD_TESTS=ON

     • Release (Native): -DNEXUS_PLATFORM=native -DCMAKE_BUILD_TYPE=Release

     • STM32F4: -DNEXUS_PLATFORM=stm32f4 -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake

3. Configure Toolchains:

   • File → Settings → Build, Execution, Deployment → Toolchains

   • Add ARM toolchain:

     • Name: ARM GCC

     • CMake: System CMake

     • Make: System Make

     • C Compiler: /usr/bin/arm-none-eabi-gcc

     • C++ Compiler: /usr/bin/arm-none-eabi-g++

     • Debugger: /usr/bin/arm-none-eabi-gdb

4. Configure Code Style:

   • File → Settings → Editor → Code Style → C/C++

   • Scheme: Project

   • Import .clang-format settings

5. Configure External Tools:

   • File → Settings → Tools → External Tools

   • Add tools:

     • Format Code: python scripts/tools/format.py

     • Run Tests: python scripts/test/test.py

     • Generate Docs: python scripts/tools/docs.py

Run Configurations

Create run configurations for common tasks:

Build Configuration:

• Name: Build Native

• Target: All targets

• Configuration: Debug

Test Configuration:

• Name: Run Tests

• Target: nexus_tests

• Configuration: Debug

• Program arguments: --gtest_output=xml:test_results.xml

Debug Configuration:

• Name: Debug Blinky

• Target: blinky

• Configuration: Debug

Eclipse

Eclipse CDT is a popular open-source IDE.

Installation

Linux:

sudo apt install eclipse-cdt

Windows/macOS: Download from https://www.eclipse.org/downloads/

Configuration

1. Import Project:

   • File → Import → C/C++ → Existing Code as Makefile Project

   • Browse to nexus directory

   • Toolchain: Linux GCC or Cross GCC

2. Configure CMake:

   • Project → Properties → C/C++ Build

   • Builder Settings:

     • Build command: cmake --build build

     • Build directory: ${workspace_loc:/nexus}/build

3. Configure Indexer:

   • Project → Properties → C/C++ General → Paths and Symbols

   • Add include paths:

     • ${workspace_loc:/nexus}/hal/include

     • ${workspace_loc:/nexus}/osal/include

     • ${workspace_loc:/nexus}/framework/*/include

4. Configure Code Style:

   • Window → Preferences → C/C++ → Code Style → Formatter

   • Import .clang-format settings

Debugger Setup

GDB (GNU Debugger)

GDB is the standard debugger for C/C++ on Linux.

Installation

Linux:

sudo apt install gdb

macOS:

brew install gdb

Windows: Included with MinGW or use WSL

Configuration

Create ~/.gdbinit for custom settings:

# Enable pretty printing
set print pretty on
set print object on
set print static-members on
set print vtbl on
set print demangle on
set demangle-style gnu-v3

# History
set history save on
set history size 10000
set history filename ~/.gdb_history

# Auto-load safe path
add-auto-load-safe-path /path/to/nexus

Basic Usage

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

# GDB commands
(gdb) break main              # Set breakpoint at main
(gdb) run                     # Run program
(gdb) next                    # Step over
(gdb) step                    # Step into
(gdb) continue                # Continue execution
(gdb) print variable          # Print variable value
(gdb) backtrace               # Show call stack
(gdb) info locals             # Show local variables
(gdb) quit                    # Exit GDB

Advanced GDB

Conditional Breakpoints:

(gdb) break hal_gpio_init if port == 5

Watchpoints:

(gdb) watch variable          # Break when variable changes
(gdb) rwatch variable         # Break when variable is read
(gdb) awatch variable         # Break on read or write

Pretty Printers:

Create .gdbinit in project root:

import sys
sys.path.insert(0, '/path/to/nexus/scripts/gdb')
import nexus_printers
nexus_printers.register_printers()

OpenOCD

OpenOCD provides on-chip debugging for ARM targets.

Installation

Linux:

sudo apt install openocd

macOS:

brew install openocd

Windows: Download from https://openocd.org/

Configuration

Create openocd.cfg for your board:

# STM32F4 Discovery
source [find interface/stlink.cfg]
source [find target/stm32f4x.cfg]

# Reset configuration
reset_config srst_only

# Flash programming
$_TARGETNAME configure -event reset-init {
    # Configure clocks
    mww 0x40023C00 0x00000003  # Enable HSI
}

Usage

Start OpenOCD:

# Using config file
openocd -f openocd.cfg

# Or specify interface and target
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

Connect GDB:

Terminal 1 (OpenOCD):

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

Terminal 2 (GDB):

arm-none-eabi-gdb build-stm32f4/applications/blinky/blinky.elf
(gdb) target remote localhost:3333
(gdb) monitor reset halt
(gdb) load
(gdb) break main
(gdb) continue

Flash Programming:

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

J-Link

SEGGER J-Link is a professional debugging probe.

Installation

Download from https://www.segger.com/downloads/jlink/

Linux:

# Download .deb package
sudo dpkg -i JLink_Linux_*.deb

macOS:

# Download .pkg installer
# Install by double-clicking

Windows: Run installer

Configuration

Create jlink.cfg:

[JLINK]
Device = STM32F407VG
Interface = SWD
Speed = 4000

Usage

J-Link GDB Server:

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

# Connect 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

J-Link Commander:

# Start J-Link Commander
JLinkExe -device STM32F407VG -if SWD -speed 4000

# Commands
J-Link> connect
J-Link> loadfile blinky.elf
J-Link> reset
J-Link> go
J-Link> halt
J-Link> exit

Code Analysis Tools

clang-format

Automatic code formatting tool.

Installation

Linux:

sudo apt install clang-format

macOS:

brew install clang-format

Windows: Included with LLVM

Usage

# Format single file
clang-format -i hal/src/hal_gpio.c

# Format all files
python scripts/tools/format.py

# Check formatting without changes
python scripts/tools/format.py --check

Configuration

Nexus uses .clang-format in project root:

BasedOnStyle: Google
IndentWidth: 4
ColumnLimit: 80
PointerAlignment: Left
AlignConsecutiveAssignments: false
AlignConsecutiveDeclarations: false

clang-tidy

Static analysis tool for C/C++.

Installation

Linux:

sudo apt install clang-tidy

macOS:

brew install llvm

Windows: Included with LLVM

Usage

# Analyze single file
clang-tidy hal/src/hal_gpio.c -- -Ihal/include

# Analyze all files
find hal osal framework -name "*.c" | xargs clang-tidy

Configuration

Nexus uses .clang-tidy in project root:

Checks: >
  -*,
  bugprone-*,
  cert-*,
  clang-analyzer-*,
  cppcoreguidelines-*,
  modernize-*,
  performance-*,
  readability-*

cppcheck

Static analysis tool focused on detecting bugs.

Installation

Linux:

sudo apt install cppcheck

macOS:

brew install cppcheck

Windows: Download from http://cppcheck.sourceforge.net/

Usage

# Analyze project
cppcheck --enable=all --inconclusive --std=c11 \
    -I hal/include -I osal/include \
    hal/ osal/ framework/

# Generate XML report
cppcheck --enable=all --xml --xml-version=2 \
    hal/ osal/ framework/ 2> cppcheck_report.xml

Valgrind

Memory debugging and profiling tool.

Installation

Linux:

sudo apt install valgrind

macOS:

brew install valgrind

Usage

# Memory leak detection
valgrind --leak-check=full --show-leak-kinds=all \
    ./build/applications/blinky/blinky

# Memory error detection
valgrind --tool=memcheck --track-origins=yes \
    ./build/applications/blinky/blinky

# Cache profiling
valgrind --tool=cachegrind ./build/applications/blinky/blinky

AddressSanitizer

Fast memory error detector.

Usage

# Build with AddressSanitizer
cmake -B build -DNEXUS_PLATFORM=native \
    -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
    -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer"
cmake --build build

# Run program
./build/applications/blinky/blinky

Documentation Tools

Doxygen

API documentation generator.

Installation

Linux:

sudo apt install doxygen graphviz

macOS:

brew install doxygen graphviz

Windows: Download from https://www.doxygen.nl/

Usage

# Generate documentation
doxygen Doxyfile

# View documentation
open docs/api/html/index.html

Configuration

Nexus uses Doxyfile in project root. Key settings:

PROJECT_NAME           = "Nexus"
PROJECT_NUMBER         = 0.1.0
OUTPUT_DIRECTORY       = docs/api
INPUT                  = hal osal framework
RECURSIVE              = YES
EXTRACT_ALL            = YES
GENERATE_HTML          = YES
GENERATE_LATEX         = NO

Sphinx

User documentation generator.

Installation

pip install sphinx sphinx_rtd_theme breathe

Usage

# Generate documentation
cd docs/sphinx
sphinx-build -b html . _build/html

# View documentation
open _build/html/index.html

Configuration

Nexus uses docs/sphinx/conf.py. Key settings:

project = 'Nexus'
copyright = '2026, Nexus Team'
author = 'Nexus Team'
version = '0.1.0'
release = '0.1.0'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
    'breathe',
]

html_theme = 'sphinx_rtd_theme'

Platform-Specific Setup

Windows Development

Recommended Setup:

• Windows 10/11

• Visual Studio 2019+ or MSVC Build Tools

• Windows Terminal

• WSL2 for Linux tools

WSL2 Setup:

# Install WSL2
wsl --install

# Install Ubuntu
wsl --install -d Ubuntu

# Inside WSL
sudo apt update
sudo apt install build-essential cmake git

Linux Development

Recommended Distribution: Ubuntu 20.04+ or Debian 11+

Package Installation:

# Development tools
sudo apt install build-essential cmake git

# ARM toolchain
sudo apt install gcc-arm-none-eabi

# Debugging tools
sudo apt install gdb openocd

# Analysis tools
sudo apt install clang-format clang-tidy cppcheck valgrind

# Documentation tools
sudo apt install doxygen graphviz

macOS Development

Recommended Setup:

• macOS 11+ (Big Sur or later)

• Xcode Command Line Tools

• Homebrew package manager

Package Installation:

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

# Development tools
brew install cmake git

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

# Debugging tools
brew install openocd

# Analysis tools
brew install clang-format llvm cppcheck

# Documentation tools
brew install doxygen graphviz

Environment Variables

Recommended environment variables for Nexus development:

Linux/macOS (add to ~/.bashrc or ~/.zshrc):

# Nexus project root
export NEXUS_ROOT=~/projects/nexus

# ARM toolchain
export ARM_TOOLCHAIN_PATH=/usr/bin

# Build configuration
export NEXUS_BUILD_DIR=build
export NEXUS_PLATFORM=native

# Python
export PYTHONPATH=$NEXUS_ROOT/scripts:$PYTHONPATH

Windows (PowerShell profile):

# Nexus project root
$env:NEXUS_ROOT = "C:\Projects\nexus"

# ARM toolchain
$env:ARM_TOOLCHAIN_PATH = "C:\Program Files (x86)\GNU Arm Embedded Toolchain\bin"

# Build configuration
$env:NEXUS_BUILD_DIR = "build"
$env:NEXUS_PLATFORM = "native"

Shell Aliases

Useful shell aliases for Nexus development:

Linux/macOS (add to ~/.bashrc or ~/.zshrc):

# Navigation
alias cdnx='cd $NEXUS_ROOT'

# Build
alias nxbuild='python $NEXUS_ROOT/scripts/building/build.py'
alias nxclean='python $NEXUS_ROOT/scripts/tools/clean.py'

# Test
alias nxtest='python $NEXUS_ROOT/scripts/test/test.py'

# Format
alias nxfmt='python $NEXUS_ROOT/scripts/tools/format.py'

# Documentation
alias nxdocs='python $NEXUS_ROOT/scripts/tools/docs.py'

Windows (PowerShell profile):

# Navigation
function cdnx { Set-Location $env:NEXUS_ROOT }

# Build
function nxbuild { python "$env:NEXUS_ROOT\scripts\building\build.py" $args }
function nxclean { python "$env:NEXUS_ROOT\scripts\tools\clean.py" $args }

# Test
function nxtest { python "$env:NEXUS_ROOT\scripts\test\test.py" $args }

# Format
function nxfmt { python "$env:NEXUS_ROOT\scripts\tools\format.py" $args }

# Documentation
function nxdocs { python "$env:NEXUS_ROOT\scripts\tools\docs.py" $args }

Troubleshooting

Common Issues

IDE doesn’t recognize includes

Solution: Regenerate compile_commands.json:

cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
ln -s build/compile_commands.json .

Debugger can’t find source files

Solution: Use absolute paths in debug configuration or set source path:

(gdb) set substitute-path /build/path /source/path

OpenOCD connection fails

Solution: Check permissions and udev rules:

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

clang-format not found

Solution: Install clang-format and add to PATH:

sudo apt install clang-format
which clang-format

Next Steps

Now that your development environment is set up:

1. Coding Standards - Learn the code style

2. Testing - Write effective tests

3. Debugging Guide - Master debugging techniques

4. Contributing - Start contributing

See Also

• Environment Setup - Basic setup

• Debugging Guide - Debugging techniques

• Build Scripts and Tools - Build scripts

• Contributing - Contribution guide