Running CLion Builds and Debugging in a Remote Docker Toolchain via CMake Profiles

Problem: Your laptop can't compile the exact environment your CI or production uses

The most common pain point when using CLion for C/C++ projects is that the compiler, libraries, or kernel headers on your development machine differ from those on the target system. A build that succeeds locally may fail in CI, on a Docker container, or on a remote host, leaving you with "works on my machine" bugs that are hard to reproduce.

The solution is to treat the toolchain as part of the project definition rather than a personal machine state. CLion separates the concept of a toolchain (the compiler, debugger, and sysroot) from a CMake profile (the build type and generation options). By defining a Docker-based toolchain and binding it to a CMake profile, the IDE drives compilation exactly where the code will run.

How CLion Handles Remote Toolchains

CLion’s Toolchains page lets you describe a compiler, its path, and the debugger to use. For Docker, you create a toolchain that points to a container image containing the required packages (e.g., build-essential, cmake, gdb), mounts the project directory into the container, and sets the remote sysroot.

A CMake profile then ties a specific toolchain to a build type (Debug, Release) and generation options. When you reload the project, CLion regenerates the CMake cache using the remote compiler and debugger, so the entire build and debug cycle happens inside the container.

Concrete Example: Docker Toolchain + CMake Profile

1. Prepare a Docker image. Create a Dockerfile that installs the necessary tools and copies debug symbols if needed:

   # Dockerfile
   FROM ubuntu:22.04
   RUN apt-get update && apt-get install -y \
       build-essential cmake gdb lldb-10
   # Optional: install pretty-printers for libstdc++
   

2. Build and tag the image. Run the Docker build on the host where CLion will launch the container:

   docker build -t my-project-toolchain:latest .

   Run this as a user with permission to manage Docker images (e.g., a member of the docker group).
3. Define the toolchain in CLion. Open Settings/Preferences | Build, Execution, Deployment | Toolchains. Click + → Docker Toolchain. Fill in:
   • Image name: my-project-toolchain:latest
   • Mount path: /project (the directory that will be shared with the container)
   • Remote sysroot: /usr (or the path where headers and libraries live inside the container)
   Verify that CLion detects the compiler version and the GDB path inside the container. If the detection fails, check that the container can run which gcc and which gdb.
4. Create a CMake profile. In Settings/Preferences | Build, Execution, Deployment | CMake, click + to add a new profile. Set:
   • Toolchain: the Docker toolchain you just created
   • Build type: Debug (or Release)
   • Generation parameters: e.g., -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
5. Reload and verify. Close and reopen the project or click Reload CMake Project. Open CMakeCache.txt (found in .cmake) and confirm that CMAKE_C_COMPILER points to /usr/bin/gcc inside the container (the path will be something like /tmp/.../gcc after the mount).
6. Run a debug session. Start a debug configuration, set a breakpoint inside an STL container method, and step through. If the variables display nicely (e.g., std::vector<int> shows its elements), the debugger and pretty‑printers are working.

Verification Steps and Risks

• Confirm toolchain detection: In Settings | Toolchains, the compiler and debugger versions should be shown. If they are missing, the container may not have the required packages or the mount is incorrect.
• Check CMakeCache.txt: Ensure the compiler path resolves to the container’s filesystem. A mismatch indicates the profile isn’t bound correctly.
• Debug fidelity test: Step into a function from the C++ Standard Library. Expanded pretty‑printed values confirm that the remote debugger and libstdc++ pretty‑printers are loaded.
• Incremental build test: Edit a header file, trigger a rebuild, and watch the output. The build should happen inside the container; if it falls back to the host compiler, the profile isn’t active.

Trade‑offs and Limitations

While the Docker‑based approach gives you reproducible builds and debugging, it introduces latency. Indexing, code analysis, and refactoring become slower because CLion must watch files inside the mounted container. Network mounts (e.g., NFS) can further degrade file‑watching performance, causing missed changes or delayed incremental builds.

Another consideration is image maintenance. Updating dependencies (e.g., a new version of gcc) requires rebuilding the Docker image, which may disrupt the development rhythm. Additionally, WSL or remote host environments may differ in case sensitivity, line‑ending handling, or permission models, leading to subtle mismatches between the container and the host.

CLion offers several remote mechanisms (WSL, Docker, Gateway, legacy toolchains). They are not interchangeable; mixing a Docker toolchain with a WSL remote host can cause split build behavior and confusing IDE state. Always pick a single remote model per project to keep the workflow consistent.

Actionable Closing

Start small: keep your local editing experience unchanged, but move only the build and test steps into a Docker container or WSL session. Commit a Dockerfile and a CMakePresets.json file to version control so the environment is reproducible for every teammate. Keep a lightweight local CMake profile for fast syntax checks, and measure cold‑build and debugger‑attach times before rolling the solution out to the whole team.

By treating the toolchain as part of the project definition, you gain debugging fidelity that matches the target environment, reduce "works on my machine" surprises, and maintain a clear, version‑controlled path from source to binary.