This repository is configured to work seamlessly with GitHub Codespaces. It provides a complete development environment with all compilers and tools pre-installed. The environment is built on a custom trainiteu/mp-units Docker image which extends the build tool ecosystem with mp-units-specific requirements.

Docker Image Hierarchy

The development environment is built on a layered Docker image stack:

trainiteu/ubuntu: Ubuntu 25.04 (Plucky Puffin) base with essential development tools
trainiteu/cpp: Adds CMake, Ninja, and Python with pipx for tool management
trainiteu/cpp-conan: Adds Conan 2.x and base compiler profiles
trainiteu/mp-units: mp-units-specific extensions including:
- Extended compiler matrix (GCC 12-15, Clang 16-21)
- Python documentation ecosystem via pipx
- Pre-configured Conan remotes and profiles for all compiler combinations
- Development aliases and optimized build configuration

Quick Start

Option 1: Create Codespace from GitHub.com

Navigate to the mp-units repository on GitHub
Click the green "<> Code" button
Select the "Codespaces" tab
Click "Create codespace on master" (or your desired branch)
Wait for the environment to set up (usually 3-5 minutes)

Option 2: Create Codespace from VS Code

Install the GitHub Codespaces extension in VS Code
Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type "Codespaces: Create New Codespace"
Select the mp-units repository
Choose your preferred branch and machine type

Option 3: Use Dev Container Locally in VS Code

Prerequisites:
- Install Docker Desktop or Docker Engine
- Install VS Code
- Install the Dev Containers extension
Open in container:
- Open the main mp-units directory in VS Code
- VS Code will detect the .devcontainer configuration
- Click "Reopen in Container" when prompted, or
- Open Command Palette (Ctrl+Shift+P) → "Dev Containers: Reopen in Container"
Wait for setup: The container will build automatically (usually 3-5 minutes)

This option provides the same development environment as Codespaces while running locally on your machine. It offers:

Full offline development (after initial setup)
Better performance on powerful local machines
Direct file system access for easier integration with local tools
No usage limits unlike GitHub Codespaces

Development Environment Features

The development environment includes all compilers and tools used for comprehensive testing:

Base OS: Ubuntu 25.04 (Plucky Puffin)
GCC: 12, 13, 14, 15
Clang: 16, 17, 18, 19, 20, 21
Standard Library: libc++-18 for backward compatibility with clang-16
Build Tools: CMake, Ninja, Conan package manager
Code Quality: clang-format, clang-tidy, include-what-you-use
Documentation: MkDocs with Material theme
VS Code Extensions: C++ IntelliSense, CMake Tools, Python support
Pre-configured Conan Profiles: All compiler configurations ready to use
Pre-compiled dependencies: Conan cache is persistent and pre-compiled dependencies for recommended configurations are uploaded on a pre-configured Conan remote

Available Conan Profiles

The following Conan profiles are pre-configured:

gcc12, gcc13, gcc14, gcc15
clang16, clang17, clang18, clang19, clang20, clang21

Multi-Compiler Testing Script

The Codespace includes a comprehensive testing script at .devcontainer/check_all.sh.

# Available script options
./.devcontainer/check_all.sh install   # Install dependencies for all release configurations and provide CMake Presets
./.devcontainer/check_all.sh build     # Build release with all compiler configurations
./.devcontainer/check_all.sh create    # Create release Conan packages with all configurations
./.devcontainer/check_all.sh -d create # Include debug builds

Each iteration tests different combinations of:

C++ standards: 20, 23, 26
Standard library implementations: libstdc++11, libc++
Feature flags: cxx_modules, import_std, std_format, contracts

API Reference Generation

The .devcontainer/api_reference.sh script automates the generation of API documentation:

# Generate API reference documentation
.devcontainer/api_reference.sh

# Generate API reference documentation (setup only, no build)
.devcontainer/api_reference.sh -s

# Use custom directory for dependencies
.devcontainer/api_reference.sh -d /path/to/deps

By default, the script performs both setup and build operations. Use the -s flag to perform setup only (done already during development container initialization). The script runs automatically during Codespace initialization to ensure the API documentation setup is ready.

The -d parameter allows you to specify a custom directory for API documentation dependencies. By default, dependencies are stored in ../api_reference_deps relative to the project root. This directory contains:

jegp.cmake_modules: CMake modules required for documentation generation
draft: C++ standard draft sources for standardese-style formatting
cxxdraft-htmlgen: HTML generation tools and templates

Documentation

# Serve documentation locally
mkdocs serve

The documentation will be available at http://localhost:8000 and will automatically forward in Codespaces.

Tips for Codespaces Usage

Machine Specifications

For mp-units development, GitHub Codespaces offers different machine types with varying performance and costs. The free tier provides 120 core-hours per month for public repositories.

Machine Type	vCPUs	RAM	Free Hours/Month*	Best For
2-core	2	8GB	60 hours	Single-profile development, light testing
4-core	4	16GB	30 hours	`check_all.sh` usage, parallel builds
8-core	8	32GB	15 hours	Intensive multi-profile development
16-core	16	64GB	7.5 hours	Large-scale development, heavy parallel workloads
32-core	32	128GB	3.75 hours	Maximum performance for complex builds

* Based on 120 free core-hours per month for GitHub Free accounts on public repositories

For current machine specifications and pricing, see:

Usage Recommendations:

2-core: Suitable for documentation, small changes, and single-profile testing
4-core: Recommended for most mp-units development — good balance of performance and free usage
8-core+: Best for intensive development sessions or when you need maximum build speed

Development Workflow

Recommended Development Process

Start with single profile: Test your changes with one compiler first

conan create . -pr clang21 -c user.mp-units.build:all=True -b missing

Test compatibility: Check the oldest compilers that may have different C++20 support

conan create . -pr gcc12 -c user.mp-units.build:all=True -b missing
conan create . -pr clang16 -c user.mp-units.build:all=True -b missing

Code quality: Run pre-commit checks (automatically included in check_all.sh)
```
pre-commit run --all-files
```
Full validation: Run the complete test suite across all configurations
```
.devcontainer/check_all.sh create
```

Getting Help

Check the mp-units documentation for project-specific information
Refer to the GitHub Codespaces documentation for platform help
Use the discussion forums or issues in the repository for development questions