Skip to content

README.md

Latest commit

 

History

History
124 lines (95 loc) · 4.8 KB

README.md

File metadata and controls

124 lines (95 loc) · 4.8 KB
Raw

Docker development environment

Container for building and running the project. The only host requirements are Docker (with the docker compose plugin) and an X11 server for the GUI. The container provides:

  • Ubuntu 24.04 + GCC 13 with C++20 toolchain
  • Conan 2 installed inside the image
  • All system libraries needed to build the Conan dependencies from source (Qt 6, OpenSSL, ...) and to run the Qt/QML GUI over X11
  • A non-root user whose UID/GID matches yours, so files created in the mounted project stay owned by you
  • A persistent Conan cache (Docker named volume) so the heavy dependencies are compiled only once and reused on every later run

Quick start

cd docker
./build.sh

The script is interactive: it asks for the image/container names and the in-container username (or automatically assigns them), then builds the image and starts the container in the background.

Open a shell in the running container:

cd docker
docker compose exec mars-lander-dev bash

The image runs as your non-root build user, so both a plain docker compose exec and VS Code → Attach to Running Container land as that user.

Building the project inside the container

Once you have a shell in the container, the project is mounted at /workspace. Build and run it with the usual Conan + CMake commands:

# Example for a build with the release profile (for debug builds see below)
conan install . -pr:a docker/conan/profiles/release --build=missing
cmake --preset conan-release
cmake --build --preset conan-release
./build/Release/app          # GUI appears on your host display

The -pr:a release flag applies the release profile to both the host and build contexts, so you do not need a separate default profile. Use -pr:a debug together with the conan-debug preset for a debug build.

The build script

Every option in the build.sh script is available as a flag; anything left unset is asked interactively when a terminal is attached.

-i, --image NAME          image name        (default: mars-lander)
-c, --container NAME      container name    (default: same as image name)
-u, --user NAME           in-container user (default: your host username)
-d, --display DISPLAY     X11 display       (default: current $DISPLAY or :0)
    --no-cache            rebuild the image without the Docker cache
-y, --yes                 non-interactive: accept all defaults
-h, --help                show help

Examples:

./build.sh                          # fully interactive
./build.sh -y                       # non-interactive, accept defaults
./build.sh -i mars-dev -c mars-run  # custom image / container names

Conan

Conan is installed inside the image and the package cache (~/.conan2) is stored in a Docker named volume (conan-cache). Mounting the host cache can be convenient but couples the container to your host and hurts reproducibility.

  • The toolchain and Conan version live in the image, so the environment does not depend on the state of your host's ~/.conan2.
  • The named volume persists the compiled packages, so Qt and other dependencies are built only on the first run and are reused afterwards.

The Conan profiles live in conan/profiles: linux-gcc (the base) plus debug and release, which just set build_type. They can be directly referenced by path (-pr:a docker/conan/profiles/<name>) so that it is not necessary to copy them into ~/.conan2.

X11 / GUI forwarding

The container uses host networking and mounts the X11 socket (/tmp/.X11-unix). build.sh runs xhost +local:docker so the container may talk to your X server. If you start the container by hand, run that yourself:

xhost +local:docker

DISPLAY is forwarded from your environment (override with --display), and QT_XCB_NO_MITSHM=1 avoids shared-memory issues over the X11 socket.

Files

File Purpose
Dockerfile Ubuntu 24.04 image with GCC 13, Conan and all build libraries; runs as your non-root user
docker-compose.yml Service definition: mounts, X11, named cache volume
build.sh Interactive/CLI helper to build the image and start the container
.env.example Reference for the .env values build.sh generates
conan/profiles/ linux-gcc / debug / release Conan profiles

Container Handling

# when the container was already built use
docker stop mars-lander      # stop the running container
docker start mars-lander     # start the container again after boot

# from the docker directory
cd docker
docker compose stop          # stop the container
docker compose down          # stop and remove the container
docker compose down -v       # also remove the Conan cache volume (forces a
                             # full dependency rebuild next time)