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](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
  - **CodeLLDB** (for LLDB support): [Marketplace Link](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
  - **Docker**: [Marketplace Link](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)
- Docker and Docker Compose installed.
- Rust toolchain (for local symbol resolution).

## Setup

1.  Copy the debug configuration files to your project's root directory:
    ```bash
    # 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:**
```yaml
services:
  tuliprox:
    # ... other settings
    environment:
      - DEBUG_SERVER=gdb
      - RUST_TARGET=x86_64-unknown-linux-musl
```

**Example for using LLDB:**
```yaml
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.