Development Workflow

Complete guide to building, testing, and debugging applications with the Sol3 SDK.

Prerequisites

Complete the Getting Started guide before proceeding. All commands should be run from within the devcontainer.

Building Applications

The Sol3 SDK uses CMake presets to configure builds for different target architectures. The build system uses vcpkg for third-party dependency management. CMake tracks dependencies and rebuilds only what’s necessary, so incremental builds should be fast.

Build for x64 (Development)

Build for your development machine (x64 architecture) for fast iteration and debugging:

# Configure build
cmake --preset x64

# Build all targets
cmake --build --preset x64

# Build specific target
cmake --build --preset x64 --target example_app

The resulting binaries will be located in out/build/x64/bin.

Cross-Compile for ARM64 (Sol3)

Build for the Sol3 platform (ARM64 architecture):

# Configure cross-compilation
cmake --preset arm64

# Build all targets
cmake --build --preset arm64

# Verify ARM64 build
file out/build/arm64/bin/example_app
# Output: ELF 64-bit LSB pie executable, ARM aarch64, ...

The resulting binaries will be located in out/build/arm64/bin.

Running Applications

Applications must run with the correct sysroot activated. The sysroot contains all runtime dependencies (system libraries, vcpkg packages) for the target architecture.

See also

Understanding sysroots - See Sysroots for details on what sysroots are, how they work, and how they integrate with the build system.

The SDK provides the sol3_activate_sysroot script to configure the runtime environment automatically.

Run Single Command

Execute a command with the sysroot activated:

# Run application
sol3_activate_sysroot x64 ./out/build/x64/bin/example_app

# Run tests
sol3_activate_sysroot x64 ctest --preset x64

Interactive Shell Mode

Enter an interactive shell with the sysroot activated:

# Activate sysroot
sol3_activate_sysroot x64

# Note, the prompt changes to show active sysroot
(/opt/sysroots/x64) $ ./out/build/x64/bin/example_app
(/opt/sysroots/x64) $ ctest --preset x64
(/opt/sysroots/x64) $ exit

Tip

Interactive mode is useful for running multiple commands without repeatedly invoking sol3_activate_sysroot.

Testing

Run Tests

# x64 tests
sol3_activate_sysroot x64 ctest --preset x64

# ARM64 tests (if running on ARM64 hardware)
sol3_activate_sysroot arm64 ctest --preset arm64

Debugging

Important

Debugging currently only works for x64 builds. ARM64 debugging requires cross-debugging setup not covered in this guide.

Debug Builds

The default x64 and arm64 presets are configured for “Release with Debug Symbols”, but still include compiler optimizations which may make debugging difficult. For a better debugging experience, use the x64-debug preset:

# Configure debug build
cmake --preset x64-debug

# Build all targets
cmake --build --preset x64-debug

Debug builds include:

  • Full debug symbols (-g)

  • Disabled optimizations (-O0)

GDB Debugging

# Launch with GDB
sol3_activate_sysroot x64 gdb ./out/build/x64-debug/bin/example_app