Skip to content

Commit 986be7e

Browse files
rothmichaelsrothmichaels
committed
CLAUDE.md DON'T MERGE
Squashed commit of the following: commit d0f5fc3 Author: Roth Michaels <roth@rothmichaels.us> Date: Thu Sep 18 16:29:08 2025 -0600 Add testing command to CLAUDE.md commit 57c7dd3 Author: Roth Michaels <roth@rothmichaels.us> Date: Thu Sep 18 16:08:33 2025 -0600 Add CLAUDE.md Provide a first-draft of a CLAUDE.md file generated by the `/init` command and then updated with iterations about conan profiles. Added ".claude" to _.gitignore_.
1 parent c78f31f commit 986be7e

File tree

2 files changed

+190
-0
lines changed

2 files changed

+190
-0
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,6 @@ docs/api_reference/gen
5353

5454
# macOS files
5555
.DS_Store
56+
57+
# Claude code
58+
.claude

‎CLAUDE.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
mp-units is a Modern C++ quantities and units library that provides compile-time dimensional analysis and unit/quantity manipulation. The library uses C++20 features (concepts, classes as NTTPs) for type safety and zero-runtime cost abstractions.
8+
9+
## Build System and Configuration
10+
11+
### Conan-Based Build System
12+
- **Primary dependency manager**: Conan 2.0+ (not vcpkg or other package managers)
13+
- **Build tool**: CMake 3.25+ with Conan integration
14+
- **Configuration**: Use `conanfile.py` for dependency and build management
15+
16+
### Important: Always Ask About Conan Profile
17+
**Before running any Conan commands, always ask the user which Conan profile to use.** Users may have:
18+
- `default` (most common)
19+
- Custom profiles like `gcc`, `clang`, `gcc13`, etc.
20+
- No profiles configured (needs setup first)
21+
22+
Ask: "Which Conan profile would you like to use? (e.g., 'default', or run `conan profile list` to see available profiles)"
23+
24+
### Common Build Commands
25+
26+
#### Standard Development Build
27+
```bash
28+
# Single compiler build with all features (recommended for development)
29+
conan build . -pr <your_profile> -c user.mp-units.build:all=True -b missing
30+
31+
# With specific C++ standard (adjust profile and cppstd for your system)
32+
conan build . -pr <your_profile> -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing
33+
34+
# Using default profile (if configured)
35+
conan build . -c user.mp-units.build:all=True -b missing
36+
```
37+
38+
#### Multi-Compiler Testing (Codespace Environment)
39+
```bash
40+
# Test all compiler configurations (comprehensive - creates packages)
41+
.devcontainer/check_all.sh create
42+
43+
# Build only (without package creation)
44+
.devcontainer/check_all.sh build
45+
46+
# With debug builds included
47+
.devcontainer/check_all.sh -d build
48+
49+
# Install dependencies only
50+
.devcontainer/check_all.sh install
51+
```
52+
53+
#### CMake Integration (when using mp-units as dependency)
54+
```bash
55+
# Install mp-units via Conan first
56+
conan install . -pr <profile> -s compiler.cppstd=20
57+
58+
# In your CMakeLists.txt:
59+
# find_package(mp-units REQUIRED)
60+
# target_link_libraries(<your_target> mp-units::mp-units)
61+
```
62+
63+
### Testing
64+
- **Test framework**: Catch2 3.10.0 (automatically included with `user.mp-units.build:all=True`)
65+
- **Run tests**: Tests run automatically during `conan build . -c user.mp-units.build:all=True`
66+
- **Verification**: Interface header sets are verified automatically (unless using `import std;`)
67+
68+
#### Manual Testing Commands
69+
After configuring the build with Conan, you can run specific test targets:
70+
71+
```bash
72+
# Verify all interface header sets (ensures headers are correctly structured)
73+
cmake --build --preset conan-release --target all_verify_interface_header_sets
74+
75+
# Run all unit tests
76+
cmake --build --preset conan-release --target test
77+
```
78+
79+
These commands are useful for:
80+
- **Interface verification**: Ensures header files are compatible and properly structured
81+
- **Test execution**: Runs the complete test suite using the configured build preset
82+
- **Build validation**: Confirms code quality and compatibility after making changes
83+
84+
### Code Quality Tools
85+
- **Formatter**: clang-format (with `.clang-format` config)
86+
- **Linter**: clang-tidy (enable with `-c user.mp-units.analyze:clang-tidy=True`)
87+
- **Pre-commit hooks**: `pre-commit run --all-files` (includes clang-format, cmake-format, black, flake8)
88+
- **Static analysis**: `conan build . -c user.mp-units.analyze:clang-tidy=True`
89+
- **Documentation**: `mkdocs serve` (live preview) or `mkdocs build` (static generation)
90+
91+
## Architecture Overview
92+
93+
### Modular Design
94+
The library is organized into distinct modules:
95+
96+
#### Core Module (`src/core/`)
97+
- **Location**: `src/core/include/mp-units/`
98+
- **Purpose**: Fundamental quantity and unit types, dimensional analysis
99+
- **Key components**: Concepts, basic quantity/unit definitions, type traits
100+
- **Module file**: `src/core/mp-units-core.cpp` (for C++ modules build)
101+
102+
#### Systems Module (`src/systems/`)
103+
- **Location**: `src/systems/include/mp-units/systems/`
104+
- **Purpose**: Physical unit systems (SI, International, ISQ, etc.)
105+
- **Key systems**:
106+
- `si/` - International System of Units
107+
- `isq/` - International System of Quantities
108+
- `international/` - International units (miles, gallons, etc.)
109+
- **Module file**: `src/systems/mp-units-systems.cpp`
110+
111+
#### Project Wrapper (`src/mp-units.cpp`)
112+
- Combines core and systems modules
113+
- Main entry point for C++ modules builds
114+
- Dependencies: `mp-units::core` + `mp-units::systems`
115+
116+
### Key Configuration Options
117+
118+
#### API Configuration (set via CMake cache variables)
119+
- `MP_UNITS_API_STD_FORMAT`: Enable std::format support (auto-detected)
120+
- `MP_UNITS_API_NO_CRTP`: Use explicit `this` instead of CRTP (requires C++23)
121+
- `MP_UNITS_API_CONTRACTS`: Contract checking (`NONE`, `GSL-LITE`, `MS-GSL`)
122+
- `MP_UNITS_API_FREESTANDING`: Freestanding build (no hosted features)
123+
- `MP_UNITS_API_NATURAL_UNITS`: Natural units support (default: ON)
124+
125+
#### Build Features
126+
- `MP_UNITS_BUILD_CXX_MODULES`: Build as C++20 modules (requires CMake 3.29+)
127+
- `CMAKE_CXX_MODULE_STD`: Enable `import std;` (experimental, requires CMake 3.30+)
128+
129+
## Development Guidelines
130+
131+
### Compiler Support Matrix
132+
- **Minimum support**: GCC 12, Clang 16, Apple Clang 15, MSVC 194 (C++20)
133+
- **std::format support**: GCC 13+, Clang 17+, Apple Clang 16+, MSVC 194
134+
- **C++ modules**: Clang 17+, GCC (limited), MSVC (limited)
135+
- **Explicit this (no-CRTP)**: GCC 14+, Clang 18+ (C++23)
136+
- **Testing matrix**: GCC 12-15, Clang 16-20 (Clang 19 excluded due to compiler bug)
137+
138+
### Naming Conventions and Code Style
139+
- **Types, functions, variables**: `standard_case` (e.g., `quantity`, `unit_symbol`)
140+
- **Template parameters**: `PascalCase` (e.g., `QuantitySpec`, `UnitOf`)
141+
- **Namespaces**: `standard_case` (e.g., `mp_units::si::unit_symbols`)
142+
- **Constants**: `standard_case` (e.g., `speed_of_light`, `elementary_charge`)
143+
- **Use pre-commit hooks**: Automatically formats code with clang-format
144+
145+
### Testing Different Configurations
146+
The library supports multiple build configurations. Test important changes across:
147+
- Different contract modes (`NONE`, `GSL-LITE`, `MS-GSL`)
148+
- With/without std::format support
149+
- Freestanding vs hosted builds
150+
- Traditional headers vs C++ modules
151+
- Multiple compiler versions (use `.devcontainer/check_all.sh`)
152+
153+
### Code Organization Patterns
154+
- **Header-only by default**: Most functionality in header files under `include/`
155+
- **Module interface units**: `.cpp` files provide C++ module interfaces
156+
- **System-specific headers**: Each unit system has its own subdirectory
157+
- **Example code**: `example/` directory contains usage demonstrations
158+
159+
### Dependencies and Contracts
160+
- **Contract libraries**:
161+
- `gsl-lite` (default) - Lightweight GSL implementation
162+
- `ms-gsl` - Microsoft's GSL implementation
163+
- `none` - No contract checking (required for freestanding)
164+
- **Formatting**:
165+
- `std::format` (preferred when available)
166+
- `fmt` library (fallback when std::format unavailable)
167+
- **Test framework**: Catch2 3.10.0 (only when `user.mp-units.build:all=True`)
168+
- **Freestanding mode**: No hosted dependencies, contracts must be `none`
169+
170+
### Documentation
171+
- **User documentation**: Available at https://mpusz.github.io/mp-units
172+
- **API reference**: Generate with `.devcontainer/api_reference.sh`
173+
- **Examples**: See `example/` directory for usage patterns
174+
- **Contributing**: See CONTRIBUTING.md for development setup
175+
176+
### Contribution Workflow
177+
- **Issue selection**: Look for `good first issue`, `help wanted`, or `high priority` labels
178+
- **Pre-commit hooks**: Always run `pre-commit run --all-files` before committing
179+
- **Multi-compiler testing**: Use `.devcontainer/check_all.sh create` to test all configurations
180+
- **Documentation**: Update docs with `mkdocs serve` for live preview
181+
- **Backward compatibility**: Ensure changes work across all supported compiler configurations
182+
183+
### GitHub Codespaces (Recommended)
184+
- **Quick start**: Use "Open in GitHub Codespaces" badge from the repository
185+
- **Pre-configured environment**: Includes all compilers, tools, and dependencies
186+
- **Full toolchain**: GCC 12-15, Clang 16-20, documentation tools, quality checks
187+
- **Ready to use**: No local setup required, everything works out of the box

0 commit comments

Comments
 (0)