|
| 1 | +# GitHub Codespaces Integration for mp-units |
| 2 | + |
| 3 | +This repository is configured to work seamlessly with GitHub Codespaces, providing a |
| 4 | +complete development environment with all compilers and tools pre-installed. The environment |
| 5 | +is built on [custom `trainiteu/mp-units` Docker image](https://github.com/train-it-eu/docker-images/blob/main/mp-units/Dockerfile) |
| 6 | +which extends the build tool ecosystem with **mp-units**-specific requirements. |
| 7 | + |
| 8 | +## Docker Image Hierarchy |
| 9 | + |
| 10 | +The development environment is built on a layered Docker image stack: |
| 11 | + |
| 12 | +1. **[`trainiteu/ubuntu`](https://github.com/train-it-eu/docker-images/blob/main/ubuntu/Dockerfile)**: Ubuntu 25.04 (Plucky Puffin) base with essential development tools |
| 13 | +2. **[`trainiteu/cpp`](https://github.com/train-it-eu/docker-images/blob/main/cpp/Dockerfile)**: Adds CMake, Ninja, Python with pipx for tool management |
| 14 | +3. **[`trainiteu/cpp-conan`](https://github.com/train-it-eu/docker-images/blob/main/cpp-conan/Dockerfile)**: Adds Conan 2.x and base compiler profiles |
| 15 | +4. **[`trainiteu/mp-units`](https://github.com/train-it-eu/docker-images/blob/main/mp-units/Dockerfile)**: **mp-units-specific extensions** including: |
| 16 | + - Extended compiler matrix (GCC 12-15, Clang 16-20) |
| 17 | + - Python documentation ecosystem via pipx |
| 18 | + - Pre-configured Conan remotes and profiles for all compiler combinations |
| 19 | + - Development aliases and optimized build configuration |
| 20 | + |
| 21 | +## Quick Start |
| 22 | + |
| 23 | +### Option 1: Create Codespace from GitHub.com |
| 24 | + |
| 25 | +1. Navigate to the [mp-units repository](https://github.com/mpusz/units) on GitHub |
| 26 | +2. Click the green **"<> Code"** button |
| 27 | +3. Select the **"Codespaces"** tab |
| 28 | +4. Click **"Create codespace on master"** (or your desired branch) |
| 29 | +5. Wait for the environment to set up (usually 3-5 minutes) |
| 30 | + |
| 31 | +### Option 2: Create Codespace from VS Code |
| 32 | + |
| 33 | +1. Install the [GitHub Codespaces extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) |
| 34 | + in VS Code |
| 35 | +2. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) |
| 36 | +3. Type "Codespaces: Create New Codespace" |
| 37 | +4. Select the **mp-units** repository |
| 38 | +5. Choose your preferred branch and machine type |
| 39 | + |
| 40 | +### Option 3: Use Dev Container Locally in VS Code |
| 41 | + |
| 42 | +1. **Prerequisites**: |
| 43 | + - Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) or Docker Engine |
| 44 | + - Install [VS Code](https://code.visualstudio.com/) |
| 45 | + - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) |
| 46 | + |
| 47 | +2. **Open in container**: |
| 48 | + - Open the main **mp-units** directory in VS Code |
| 49 | + - VS Code will detect the `.devcontainer` configuration |
| 50 | + - Click **"Reopen in Container"** when prompted, or |
| 51 | + - Open Command Palette (`Ctrl+Shift+P`) → **"Dev Containers: Reopen in Container"** |
| 52 | + |
| 53 | +3. **Wait for setup**: The container will build automatically (usually 3-5 minutes) |
| 54 | + |
| 55 | +This option provides the same development environment as Codespaces but runs locally on your machine, offering: |
| 56 | +- **Full offline development** (after initial setup) |
| 57 | +- **Better performance** on powerful local machines |
| 58 | +- **Direct file system access** for easier integration with local tools |
| 59 | +- **No usage limits** unlike GitHub Codespaces |
| 60 | + |
| 61 | +## Development Environment Features |
| 62 | + |
| 63 | +The development environment includes all compilers and tools used for comprehensive testing: |
| 64 | + |
| 65 | +- **Base OS**: Ubuntu 25.04 (Plucky Puffin) |
| 66 | +- **GCC**: 12, 13, 14, 15 |
| 67 | +- **Clang**: 16, 17, 18, 19, 20 |
| 68 | +- **Standard Library**: libc++-18 for maximum compatibility |
| 69 | +- **Build Tools**: CMake, Ninja, Conan package manager |
| 70 | +- **Code Quality**: clang-format, clang-tidy, include-what-you-use |
| 71 | +- **Documentation**: MkDocs with Material theme |
| 72 | +- **VS Code Extensions**: C++ IntelliSense, CMake Tools, Python support |
| 73 | +- **Pre-configured Conan Profiles**: All compiler configurations ready to use |
| 74 | +- **Pre-compiled dependencies**: Conan cache is persistent and pre-compiled dependencies |
| 75 | + for recommended configurations are uploaded on a pre-configured Conan remote |
| 76 | + |
| 77 | +### Available Conan Profiles |
| 78 | + |
| 79 | +The following Conan profiles are pre-configured: |
| 80 | + |
| 81 | +- `gcc12`, `gcc13`, `gcc14`, `gcc15` |
| 82 | +- `clang16`, `clang17`, `clang18`, `clang19`, `clang20` |
| 83 | + |
| 84 | +### Multi-Compiler Testing Script |
| 85 | + |
| 86 | +The Codespace includes a comprehensive testing script at `.devcontainer/check_all.sh`: |
| 87 | + |
| 88 | +```bash |
| 89 | +# Available script options |
| 90 | +./.devcontainer/check_all.sh install # Install dependencies for all configurations and provide CMake Presets |
| 91 | +./.devcontainer/check_all.sh build # Build with all compiler configurations |
| 92 | +./.devcontainer/check_all.sh create # Create Conan packages with all configurations |
| 93 | +./.devcontainer/check_all.sh -d create # Include debug builds |
| 94 | +``` |
| 95 | + |
| 96 | +Each iteration tests different combinations of: |
| 97 | +- C++ standards: 20, 23, 26 |
| 98 | +- Standard library implementations: libstdc++11, libc++ |
| 99 | +- Feature flags: cxx_modules, import_std, std_format, contracts |
| 100 | + |
| 101 | +#### API Reference Generation |
| 102 | + |
| 103 | +The `.devcontainer/api_reference.sh` script automates the generation of API documentation: |
| 104 | + |
| 105 | +```bash |
| 106 | +# Generate API reference documentation |
| 107 | +.devcontainer/api_reference.sh |
| 108 | + |
| 109 | +# Generate API reference documentation (setup only, no build) |
| 110 | +.devcontainer/api_reference.sh -s |
| 111 | + |
| 112 | +# Use custom directory for dependencies |
| 113 | +.devcontainer/api_reference.sh -d /path/to/deps |
| 114 | +``` |
| 115 | + |
| 116 | +By default, the script performs both setup and build operations. Use the `-s` flag |
| 117 | +to perform setup only (during development container initialization). The script runs |
| 118 | +automatically during Codespace initialization to ensure the API documentation setup |
| 119 | +is ready. |
| 120 | + |
| 121 | +The `-d` parameter allows you to specify a custom directory for API documentation |
| 122 | +dependencies. By default, dependencies are stored in `../api_reference_deps` relative |
| 123 | +to the project root. This directory contains: |
| 124 | + |
| 125 | +- **jegp.cmake_modules**: CMake modules required for documentation generation |
| 126 | +- **draft**: C++ standard draft sources for standardese-style formatting |
| 127 | +- **cxxdraft-htmlgen**: HTML generation tools and templates |
| 128 | + |
| 129 | +### Documentation |
| 130 | + |
| 131 | +```bash |
| 132 | +# Serve documentation locally |
| 133 | +mkdocs serve |
| 134 | +``` |
| 135 | + |
| 136 | +The documentation will be available at `http://localhost:8000` and will |
| 137 | +automatically forward in Codespaces. |
| 138 | + |
| 139 | + |
| 140 | +## Tips for Codespaces Usage |
| 141 | + |
| 142 | +### Machine Specifications |
| 143 | + |
| 144 | +For **mp-units** development, GitHub Codespaces offers different machine types with varying |
| 145 | +performance and costs. The free tier provides **120 core-hours per month** for public repositories. |
| 146 | + |
| 147 | +| Machine Type | vCPUs | RAM | Free Hours/Month* | Best For | |
| 148 | +|--------------|-------|-------|-------------------|---------------------------------------------------| |
| 149 | +| **2-core** | 2 | 8GB | 60 hours | Single-profile development, light testing | |
| 150 | +| **4-core** | 4 | 16GB | 30 hours | `check_all.sh` usage, parallel builds | |
| 151 | +| **8-core** | 8 | 32GB | 15 hours | Intensive multi-profile development | |
| 152 | +| **16-core** | 16 | 64GB | 7.5 hours | Large-scale development, heavy parallel workloads | |
| 153 | +| **32-core** | 32 | 128GB | 3.75 hours | Maximum performance for complex builds | |
| 154 | + |
| 155 | +\* *Based on 120 free core-hours per month for GitHub Free accounts on public repositories* |
| 156 | + |
| 157 | +For current machine specifications and pricing, see: |
| 158 | +- [GitHub Codespaces billing](https://docs.github.com/en/billing/concepts/product-billing/github-codespaces) |
| 159 | +- [GitHub Pricing Calculator](https://github.com/pricing/calculator?feature=codespaces) |
| 160 | + |
| 161 | +**Usage Recommendations:** |
| 162 | +- **2-core**: Suitable for documentation, small changes, single compiler testing |
| 163 | +- **4-core**: **Recommended** for most mp-units development - good balance of performance and free usage |
| 164 | +- **8-core+**: Best for intensive development sessions or when you need maximum build speed |
| 165 | + |
| 166 | + |
| 167 | +### Development Workflow |
| 168 | + |
| 169 | +#### Recommended Development Process |
| 170 | + |
| 171 | +1. **Start with single profile**: Test your changes with one compiler first |
| 172 | + |
| 173 | + ```bash |
| 174 | + conan create . -pr clang20 -c user.mp-units.build:all=True -b missing |
| 175 | + ``` |
| 176 | + |
| 177 | +2. **Test compatibility**: Check the oldest compilers that may have different C++20 support |
| 178 | + |
| 179 | + ```bash |
| 180 | + conan create . -pr gcc12 -c user.mp-units.build:all=True -b missing |
| 181 | + conan create . -pr clang16 -c user.mp-units.build:all=True -b missing |
| 182 | + ``` |
| 183 | + |
| 184 | +3. **Code quality**: Run pre-commit checks (automatically included in check_all.sh) |
| 185 | + |
| 186 | + ```bash |
| 187 | + pre-commit run --all-files |
| 188 | + ``` |
| 189 | + |
| 190 | +4. **Full validation**: Run the complete test suite across all configurations |
| 191 | + |
| 192 | + ```bash |
| 193 | + .devcontainer/check_all.sh create |
| 194 | + ``` |
| 195 | + |
| 196 | + |
| 197 | +## Getting Help |
| 198 | + |
| 199 | +- Check the [mp-units documentation](https://mpusz.github.io/mp-units/) for project-specific information |
| 200 | +- Refer to the [GitHub Codespaces documentation](https://docs.github.com/en/codespaces) for platform help |
| 201 | +- Use the [discussion forums](https://github.com/mpusz/mp-units/discussions) or |
| 202 | + [issues](https://github.com/mpusz/mp-units/issues) in the repository for development questions |
0 commit comments