stlab::copy_on_write

Copy-on-write wrapper for any type.

Overview

Online Documentation: The latest documentation is automatically built and deployed to GitHub Pages on every push to the main branch.

Version Management: The project version is maintained in a single location in the project() command at the top of CMakeLists.txt. When creating a new release:

1. Update the version in project(stlab-copy-on-write VERSION X.Y.Z)
2. The version will automatically propagate to:
   • CMake package configuration
   • Doxygen documentation
   • GitHub release

stlab::copy_on_write<T> is a smart pointer that implements copy-on-write semantics. It allows multiple instances to share the same underlying data until one of them needs to modify it, at which point a copy is made. This can provide significant performance benefits when dealing with expensive-to-copy objects that are frequently copied but rarely modified.

Features

• Thread-safe: Uses atomic reference counting for safe concurrent access
• Header-only: No compilation required, just include the header
• C++17: Leverages modern C++ features for clean, efficient implementation

Examples

The project includes executable examples that demonstrate the library's functionality:

• example/basic_usage.cpp: Comprehensive demonstration of copy-on-write semantics, identity checking, and swap operations

Examples are automatically built and run as part of the test suite to ensure they remain up-to-date and functional. They are also included in the generated documentation.

Building and Testing

This library uses CMake with CPM for dependency management:

# Configure and build
cmake --preset=test
cmake --build --preset=test

# Run tests
ctest --preset=test

Including in Your Project

To include this library in your project using CPM (replace X.Y.Z with the release version)

CPMAddPackage("gh:stlab/stlab-copy-on-write@X.Y.Z")

target_link_libraries(your_target PRIVATE stlab::copy-on-write)

The library's headers will be available under the stlab/ directory:

#include <stlab/copy_on_write.hpp>

Building Documentation

Documentation is generated using Doxygen with the modern doxygen-awesome-css theme:

# Configure and build documentation
cmake --preset=docs
cmake --build --preset=docs

# View documentation (opens in browser)
open build/docs/html/index.html

Requirements for documentation:

• Doxygen 1.9.1 or later

To update the Doxyfile.in with a newer version of Doxygen use the following command:

doxygen -u docs/Doxyfile.in

Continuous Integration

This project uses GitHub Actions for continuous integration, automatically:

• Testing: Builds and tests on Ubuntu (GCC/Clang), macOS (Clang), and Windows (MSVC)
• Documentation: Builds and deploys documentation to GitHub Pages on main branch pushes

All pull requests must pass CI checks before merging.

Requirements

• C++17 compatible compiler
• CMake 3.20 or later (for building tests)

Dependencies

This project uses the following external dependencies:

Dependency	Repository	File Location	Update Instructions
CMake	Kitware/CMake	CMakeLists.txt	Update VERSION in cmake_minimum_required()
CPM.cmake	cpm-cmake/CPM.cmake	CMakeLists.txt	Update version in download URL and SHA256 hash
doctest	doctest/doctest	CMakeLists.txt	Update GIT_TAG in CPMAddPackage call
Doxygen	doxygen/doxygen	Optional for docs	Install via package manager or from source
doxygen-awesome-css	jothepro/doxygen-awesome-css	CMakeLists.txt	Update GIT_TAG in CPMAddPackage call

Updating Dependencies

CMake

To install or update CMake:

Option 1: Official Installer

1. Visit the CMake download page
2. Download the installer for your platform
3. Follow the installation instructions

Option 2: Package Manager

• macOS (Homebrew): brew install cmake
• Ubuntu/Debian: sudo apt update && sudo apt install cmake
• Windows: Installed with Visual Studio

Verify Installation: cmake --version

CPM.cmake

To update CPM.cmake:

1. Check the download version here.
2. Visit the CPM.cmake releases page.
3. Follow the CPM instructions to update.

CPM Caching: This project enables CPM's caching feature to avoid re-downloading dependencies. The cache is stored in .cache/cpm and is automatically ignored by git. To customize the cache location, set the CPM_SOURCE_CACHE environment variable or CMake variable.

doctest

This dependency is automatically downloaded via CPM when building tests. The dependency is managed by cpp-library.

Doxygen

To install or update Doxygen:

Option 1: Package Manager

• macOS (Homebrew): brew install doxygen
• Ubuntu/Debian: sudo apt update && sudo apt install doxygen
• Windows: winget install doxygen

Option 2: Official Installer

1. Visit the Doxygen download page
2. Download the installer for your platform
3. Follow the installation instructions

Verify Installation: doxygen --version

doxygen-awesome-css

This dependency is automatically downloaded via CPM when building documentation. To update the theme version, update the GIT_TAG value in the CPMAddPackage call in CMakeLists.txt.

License

Distributed under the Boost Software License, Version 1.0. See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt