tuliprox/docker/debug/HOWTO.md

Remote Debugging tuliprox in VSCode with Docker

This guide explains how to set up remote debugging for the tuliprox project in VSCode, using either GDB or LLDB inside a Docker container.

Prerequisites

• VSCode with the following extensions:
  • C/C++ from Microsoft (for GDB support): Marketplace Link
  • CodeLLDB (for LLDB support): Marketplace Link
  • Docker: Marketplace Link
• Docker and Docker Compose installed.
• Rust toolchain (for local symbol resolution).

Setup

1. Copy the debug configuration files to your project's root directory:

   # Copy VSCode tasks and launch configurations
   cp -r docker/debug/.vscode .
   
   # Copy the Docker Compose override file for debugging
   cp docker/debug/docker-compose.debug-override.yml .
   

Configuration

1. Choose Your Debugger (docker-compose.debug-override.yml)

The docker-compose.debug-override.yml file is the central point for configuring your debug session. You must choose which debugger to use by setting the DEBUG_SERVER environment variable.

• Open docker-compose.debug-override.yml.
• Under the environment section for the tuliprox service, set DEBUG_SERVER to either gdb or lldb.

Example for using GDB:

services:
  tuliprox:
    # ... other settings
    environment:
      - DEBUG_SERVER=gdb
      - RUST_TARGET=x86_64-unknown-linux-musl

Example for using LLDB:

services:
  tuliprox:
    # ... other settings
    environment:
      - DEBUG_SERVER=lldb
      - RUST_TARGET=x86_64-unknown-linux-musl

This file also:

• Exposes the debug port (default: 10586).
• Sets up privileged mode, which is required for some debuggers.
• Mounts cargo cache volumes for faster subsequent builds.

2. VSCode Launch Configurations (.vscode/launch.json)

This file contains pre-configured launch profiles for LLDB (preferred debugger in VSCode). You don't need to edit this file, just select the correct profile in VSCode.

3. VSCode Tasks (.vscode/tasks.json)

• docker-compose-up-debug: Builds and starts the container with your debug configuration.
• docker-compose-down: Stops and removes the container.

Debugging Workflow

1. Configure Debugger: Open docker-compose.debug-override.yml and set the DEBUG_SERVER variable to either gdb or lldb.
2. Open Project: Open the project in VSCode.
3. Set Breakpoints: Place breakpoints in your Rust code.
4. Start Debugging:
   • Go to the "Run and Debug" panel (Ctrl+Shift+D).
   • Select the launch configuration that matches your choice in step 1 (e.g., "Docker: GDB Remote Attach").
   • Press F5 to start the preLaunchTask, which will build and run your Docker container, and then attach the debugger.

Troubleshooting

1. Debugger Fails to Connect or Disconnects Immediately

• Check DEBUG_SERVER variable: Ensure the DEBUG_SERVER variable in docker-compose.debug-override.yml matches the launch configuration you selected in VSCode.
• Check Ports: Verify that the debug port (default 10586) is not being used by another application on your host machine.
• Check Container Logs: Look at the Docker container logs. You should see output from debug-entrypoint.sh indicating that the debug server (GDB or LLDB) has started and is listening.

2. Breakpoints Are Not Being Hit

• Verify Build Target: Ensure the RUST_TARGET in your docker-compose.debug-override.yml matches the target you are building for.
• Check Source Mapping:
  • For GDB (cppdbg), verify the sourceFileMap in .vscode/launch.json. The remote path (/usr/src/tuliprox) should map to your local project directory (${workspaceFolder}).
  • For LLDB, verify the sourceMap setting.
• Debug Build: Make sure you are running a debug build, not a release build, as release builds may optimize out debug symbols. The provided scripts default to a debug build.

4. Performance Issues

• The debug build is significantly slower and uses more memory than a release build. This is normal.
• Consider allocating more resources (CPU/RAM) to Docker if your application is complex.