Embedded Linux Remote Template

A professional, automated framework for cross-compiling and remote debugging on Embedded Linux devices using VS Code, CMake, and GDB.

📖 Overview

This repository provides a robust "One-Click Debugging" workflow for Embedded Linux development. It solves the inefficiency of manual file transfers and printf debugging by automating the entire pipeline:

1. Cross-Compilation (Host side).
2. Deployment (SCP to Target).
3. Process Management (Safe port handling on Target).
4. GDB Attachment (Live debugging via VS Code).

This template is board-agnostic and can be adapted for any platform (Raspberry Pi, BeagleBone, i.MX, STM32MP1, Nuvoton, etc.) running gdbserver.

📂 Project Structure

.
├── CMakeLists.txt       # Main build configuration (Platform independent)
├── build/               # Out-of-source build artifacts
├── src/
│   └── main.cpp         # Application source code
├── toolchain/
│   └── generic.cmake    # Toolchain definition (Compiler paths & flags)
└── .vscode/             # VS Code Automation & Configuration
    ├── settings.json    # Project-wide variables (IPs, Paths, Users)
    ├── tasks.json       # Automation pipeline (Build -> Deploy -> Run)
    └── launch.json      # GDB Client configuration

🛠 Prerequisites

Host Machine (Developer PC)

• OS: Linux (Ubuntu/Debian) or Windows (WSL2).
• Software:
  • VS Code + C/C++ Extension + CMake Tools.
  • gdb-multiarch (Universal GDB Client).
  • ssh, scp.
• Target Device (Embedded Board)
  • Linux Kernel.
  • gdbserver installed. (or download from https://github.com/stayliv3/gdb-static-cross/tree/master/prebuilt)
  • SSH Access enabled.

🚀 Setup & Usage Guide

Step 1: Clone and Configure

Clone this repository and update the environment variables in .vscode/settings.json to match your hardware:

// .vscode/settings.json
{
    // --- Target Board Configuration ---
    "embed.targetIP": "192.168.1.100",
    "embed.targetUser": "root",
    "embed.targetPath": "/usr/local/my_app",
    "embed.debugPort": "2345",

    // --- Host Configuration ---
    "embed.hostBuildPath": "${workspaceFolder}/build/my_app"
}

Step 2: SSH Key (Passwordless Access)

To allow automation, the Host must access the Target without a password prompt.

# On Host Terminal
ssh-copy-id root@192.168.1.100

Step 3: Toolchain Setup (toolchain/generic.cmake)

Create this file to define your cross-compiler. Do not hardcode paths in CMakeLists.txt.

Step 4: Run one-time for setup

# Change your toolchain path
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=./toolchain/generic.cmake -DCMAKE_BUILD_TYPE=Debug

Step 5: Start Debugging

1. Open src/main.cpp
2. Set a Breakpoint (F9).
3. Press F5.