mirror of
https://github.com/boostorg/container.git
synced 2026-01-25 08:42:34 +01:00
Add comprehensive CLAUDE.MD development guide
Created a detailed guide for working with the Boost.Container repository including: - Project overview and structure - Build system instructions (B2 and CMake) - Testing procedures and CI information - Development workflow best practices - Common tasks and troubleshooting tips
This commit is contained in:
Claude
353
CLAUDE.MD
Normal file
353
CLAUDE.MD
Normal file
@@ -0,0 +1,353 @@
|
||||
# CLAUDE.MD - Boost.Container Development Guide
|
||||
|
||||
## Project Overview
|
||||
|
||||
Boost.Container is part of the [Boost C++ Libraries](http://github.com/boostorg) collection. It implements several well-known containers, including STL containers, with the aim of offering advanced features not present in standard containers, providing the latest standard draft features for compilers that don't comply with the latest C++ standard, and offering useful non-STL containers.
|
||||
|
||||
## Key Properties
|
||||
|
||||
- **Language**: C++03 and later
|
||||
- **Build Type**: Mostly header-only, library compilation required for few features
|
||||
- **Exception Support**: Supports compiler modes without exceptions (e.g., `-fno-exceptions`)
|
||||
- **License**: [Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt)
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
├── bench/ # Benchmarking code
|
||||
├── build/ # Build system files (Jamfiles)
|
||||
├── doc/ # Documentation (QuickBook/Boostbook)
|
||||
├── example/ # Example usage code
|
||||
├── include/ # Header files (main library code)
|
||||
├── meta/ # Library metadata
|
||||
├── src/ # Source files for compiled components
|
||||
├── test/ # Unit tests
|
||||
├── CMakeLists.txt # CMake build configuration
|
||||
└── build.jam # B2/Bjam build configuration
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Boost.Container depends on the following Boost libraries:
|
||||
- Boost.Assert
|
||||
- Boost.Config
|
||||
- Boost.Intrusive
|
||||
- Boost.Move
|
||||
|
||||
## Build Systems
|
||||
|
||||
This project supports two build systems:
|
||||
|
||||
### 1. B2 (Boost.Build) - Preferred for Boost Development
|
||||
|
||||
B2 is the traditional Boost build system and is required when working within the Boost superproject.
|
||||
|
||||
**Setup within Boost:**
|
||||
```bash
|
||||
# Clone Boost repository
|
||||
git clone -b develop https://github.com/boostorg/boost.git boost-root
|
||||
cd boost-root
|
||||
|
||||
# Replace libs/container with your development version
|
||||
rm -rf libs/container
|
||||
# Link or copy your container repo to libs/container
|
||||
|
||||
# Install dependencies
|
||||
git submodule update --init tools/boostdep
|
||||
python tools/boostdep/depinst/depinst.py container
|
||||
|
||||
# Bootstrap B2
|
||||
./bootstrap.sh
|
||||
|
||||
# Generate headers
|
||||
./b2 headers
|
||||
```
|
||||
|
||||
**Build the library:**
|
||||
```bash
|
||||
# Build just the container library
|
||||
./b2 libs/container/build
|
||||
|
||||
# Build with specific options
|
||||
./b2 libs/container/build variant=debug,release cxxstd=17
|
||||
```
|
||||
|
||||
**Run tests:**
|
||||
```bash
|
||||
# Run all container tests
|
||||
./b2 libs/container/test
|
||||
|
||||
# Run with specific C++ standard
|
||||
./b2 libs/container/test cxxstd=17
|
||||
|
||||
# Run with multiple standards
|
||||
./b2 libs/container/test cxxstd=11,14,17,20
|
||||
|
||||
# Run with sanitizers
|
||||
./b2 libs/container/test undefined-sanitizer=norecover
|
||||
./b2 libs/container/test address-sanitizer=norecover
|
||||
|
||||
# Parallel build
|
||||
./b2 -j8 libs/container/test
|
||||
```
|
||||
|
||||
### 2. CMake - Alternative Build System
|
||||
|
||||
CMake support is available for modern build workflows.
|
||||
|
||||
**Build options:**
|
||||
```bash
|
||||
# Header-only mode
|
||||
cmake -DBOOST_CONTAINER_HEADER_ONLY=ON -S . -B build
|
||||
cmake --build build
|
||||
|
||||
# Compiled library mode (default)
|
||||
cmake -S . -B build
|
||||
cmake --build build
|
||||
|
||||
# With tests
|
||||
cmake -DBUILD_TESTING=ON -S . -B build
|
||||
cmake --build build
|
||||
ctest --test-dir build
|
||||
```
|
||||
|
||||
**Important CMake notes:**
|
||||
- The library can be built in header-only mode by setting `BOOST_CONTAINER_HEADER_ONLY=ON`
|
||||
- In non-header-only mode, source files from `src/` are compiled
|
||||
- Dependencies on other Boost libraries are handled via CMake targets
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Working on Issues
|
||||
|
||||
1. **Check out the appropriate branch:**
|
||||
```bash
|
||||
git checkout develop # For new features
|
||||
git checkout master # For critical bug fixes
|
||||
```
|
||||
|
||||
2. **Create a feature branch:**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
3. **Make changes and test:**
|
||||
```bash
|
||||
# Run tests frequently
|
||||
cd boost-root
|
||||
./b2 libs/container/test cxxstd=11,14,17,20
|
||||
```
|
||||
|
||||
4. **Commit and push:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Brief description of changes"
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
The test suite is extensive and covers:
|
||||
- Container operations (allocator tests, copy/move, iterators)
|
||||
- C++ standard compliance across multiple versions (C++03, 11, 14, 17, 20, 23)
|
||||
- Multiple compilers (GCC 4.8-15, Clang 3.6-20, MSVC)
|
||||
- Multiple platforms (Linux, Windows, macOS, BSD, Cygwin)
|
||||
- Sanitizers (UBSAN, ASAN)
|
||||
- 32-bit and 64-bit architectures
|
||||
|
||||
**Key test files:**
|
||||
- `test/deque_test.cpp` - Tests for deque container
|
||||
- `test/vector_test.cpp` - Tests for vector container
|
||||
- `test/string_test.cpp` - Tests for string implementations
|
||||
- `test/allocator_*_test.cpp` - Allocator-related tests
|
||||
- `test/pmr_*_test.cpp` - Polymorphic memory resource tests
|
||||
|
||||
### Running Specific Tests
|
||||
|
||||
```bash
|
||||
# Run a specific test target (from boost-root)
|
||||
./b2 libs/container/test//vector_test
|
||||
|
||||
# Run with verbose output
|
||||
./b2 libs/container/test -d2
|
||||
|
||||
# Run only failed tests
|
||||
./b2 libs/container/test --rerun-failed
|
||||
```
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
The project uses GitHub Actions CI with comprehensive testing across:
|
||||
|
||||
**Compilers tested:**
|
||||
- GCC: 4.8 through 15
|
||||
- Clang: 3.6 through 20 (with both libstdc++ and libc++)
|
||||
- MSVC: 14.3 (Visual Studio 2022)
|
||||
- Platform-specific compilers on BSDs
|
||||
|
||||
**C++ Standards tested:**
|
||||
- C++03, C++11, C++14, C++17, C++20, C++23, C++26 (draft)
|
||||
|
||||
**CI Workflow:** `.github/workflows/ci.yml`
|
||||
|
||||
The CI runs:
|
||||
1. POSIX systems (Linux, macOS)
|
||||
2. Windows (MSVC, Clang-cl, MinGW)
|
||||
3. Cygwin
|
||||
4. BSD variants (FreeBSD, OpenBSD, NetBSD)
|
||||
5. Documentation builds
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### Adding a New Container
|
||||
|
||||
1. Create header file in `include/boost/container/`
|
||||
2. Add corresponding test file in `test/`
|
||||
3. Update `test/Jamfile.v2` to include new test
|
||||
4. Add documentation in `doc/`
|
||||
5. Run full test suite
|
||||
|
||||
### Fixing a Bug
|
||||
|
||||
1. Add a test case that reproduces the bug in the appropriate test file
|
||||
2. Verify the test fails
|
||||
3. Implement the fix
|
||||
4. Verify the test passes
|
||||
5. Run the full test suite to ensure no regressions
|
||||
|
||||
### Updating for New C++ Standard Features
|
||||
|
||||
1. Check `include/boost/container/detail/config_begin.hpp` for feature detection macros
|
||||
2. Implement new features conditionally based on C++ standard level
|
||||
3. Add tests for the new feature under appropriate C++ standard flags
|
||||
4. Update documentation
|
||||
|
||||
## Source File Organization
|
||||
|
||||
### Compiled Components (`src/`)
|
||||
|
||||
These files are only compiled when not in header-only mode:
|
||||
- `alloc_lib.c` - Allocation library functions
|
||||
- `dlmalloc*.c/cpp` - Doug Lea's malloc implementation
|
||||
- `*_resource.cpp` - Polymorphic memory resource implementations
|
||||
- `global_resource.cpp`
|
||||
- `monotonic_buffer_resource.cpp`
|
||||
- `pool_resource.cpp`
|
||||
- `synchronized_pool_resource.cpp`
|
||||
- `unsynchronized_pool_resource.cpp`
|
||||
|
||||
### Header Organization
|
||||
|
||||
Headers are in `include/boost/container/`:
|
||||
- Main containers: `vector.hpp`, `deque.hpp`, `string.hpp`, etc.
|
||||
- PMR support: `pmr/*.hpp`
|
||||
- Implementation details: `detail/*.hpp`
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation is written in QuickBook format (`.qbk` files) located in `doc/`.
|
||||
|
||||
**Build documentation:**
|
||||
```bash
|
||||
cd doc
|
||||
b2
|
||||
# Output will be in boost-root/doc/html/container/
|
||||
```
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- Follow Boost coding guidelines
|
||||
- Maintain C++03 compatibility for core features
|
||||
- Use Boost libraries (Config, Move, Intrusive, etc.) for portability
|
||||
- Add appropriate feature detection macros
|
||||
- Write comprehensive tests for all new features
|
||||
- Document public APIs in QuickBook format
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### B2 Not Finding Dependencies
|
||||
|
||||
```bash
|
||||
# Re-run dependency installation
|
||||
python tools/boostdep/depinst/depinst.py container
|
||||
|
||||
# Regenerate headers
|
||||
./b2 headers
|
||||
```
|
||||
|
||||
### Test Failures
|
||||
|
||||
```bash
|
||||
# Run with verbose output to see error details
|
||||
./b2 libs/container/test -d2
|
||||
|
||||
# Test with specific toolset
|
||||
./b2 libs/container/test toolset=gcc cxxstd=17
|
||||
|
||||
# Run single test with full output
|
||||
./b2 libs/container/test//vector_test -d2
|
||||
```
|
||||
|
||||
### CMake Configuration Issues
|
||||
|
||||
```bash
|
||||
# Clean and reconfigure
|
||||
rm -rf build
|
||||
cmake -S . -B build -DBUILD_TESTING=ON
|
||||
cmake --build build -v
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **Documentation**: http://www.boost.org/doc/libs/develop/doc/html/container.html
|
||||
- **GitHub Issues**: https://github.com/boostorg/container/issues
|
||||
- **Boost Mailing List**: http://www.boost.org/community/groups.html#main (use `[container]` tag)
|
||||
- **Stack Overflow**: Tag questions with `c++`, `boost`, `boost-container`
|
||||
- **Boost Dependencies Report**: https://pdimov.github.io/boostdep-report/develop/container.html
|
||||
|
||||
## Development Best Practices
|
||||
|
||||
1. **Always test with multiple C++ standards** - The library supports C++03 through C++26
|
||||
2. **Test with sanitizers** - Run UBSAN and ASAN builds before submitting PRs
|
||||
3. **Keep commits focused** - One logical change per commit
|
||||
4. **Write descriptive commit messages** - Explain why, not just what
|
||||
5. **Update tests first** - When fixing bugs, add failing test, then fix
|
||||
6. **Check CI results** - Ensure all platforms pass before merging
|
||||
7. **Update documentation** - Keep docs in sync with code changes
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Setup (from Boost root)
|
||||
./bootstrap.sh
|
||||
./b2 headers
|
||||
|
||||
# Build library
|
||||
./b2 libs/container/build
|
||||
|
||||
# Run all tests
|
||||
./b2 libs/container/test
|
||||
|
||||
# Run tests with common standards
|
||||
./b2 libs/container/test cxxstd=11,14,17,20
|
||||
|
||||
# Run with sanitizer
|
||||
./b2 libs/container/test undefined-sanitizer=norecover
|
||||
|
||||
# Run specific test
|
||||
./b2 libs/container/test//vector_test
|
||||
|
||||
# Build documentation
|
||||
cd doc && b2
|
||||
```
|
||||
|
||||
## Working with Claude
|
||||
|
||||
When working on this repository, Claude should:
|
||||
1. Always run tests after making changes
|
||||
2. Test with multiple C++ standards when relevant
|
||||
3. Check for C++03 compatibility unless adding standard-specific features
|
||||
4. Follow existing code patterns and naming conventions
|
||||
5. Add appropriate test coverage for new features or bug fixes
|
||||
6. Consider performance implications of container operations
|
||||
7. Verify changes don't break header-only mode (if applicable)
|
||||
Reference in New Issue
Block a user