mirror of
https://github.com/euzu/tuliprox.git
synced 2026-09-16 14:12:14 +02:00
Marco FranssenandGitHub
3958ff5f12
* Fix all markdownlint errors on README.md * Add markdownlint to ci and makefile * Fix all markdownlint errors on CHANGELOG.md * Fix all markdownlint errors on CONTRIBUTING.md * Fix all markdownlint errors on TODO.md * Fix all markdownlint errors on docker/README.md * Fix all markdownlint errors on docker/debug/HOWTO.md * Fix all markdownlint errors on .github/ISSUE_TEMPLATE/bug_report.md * Remove TODO.md
108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# 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.
|