TInCuP - Tag Invoke + Customization Points

TInCuP helps you add clean, extensible “hooks” to your C++ library. Describe what you want in a simple spec, generate correct code, and get readable compiler messages when something goes wrong.

Why Should I Care About Customization Points (and TInCuP?)

Have you ever been in a situation like the following?

• You are developing ImpressiveLib, a very impressive library.
• You would like ImpressiveLib to be generic and work with a variety of third party types.
• For example, it should optionally use AwesomeType, which is defined in CoolLib, an open source library that you don't own.
• You don't want to write ImpressiveLib's source code to use #include <coollib>.
• You are tempted to modify CoolLib in some way such as injecting ImpressiveLib types into it (DON'T!).
• This is where customization points can help!

See TInCuP in action in Real Vector Framework

The Problem with Existing Approaches

C++ customization mechanisms have fundamental limitations that the standardization committee has recognized in WG21 papers P1895R0 and P2279R0:

• Namespace Pollution: Traditional ADL customization requires globally reserving function names
• Composition Issues: Multiple libraries can't safely use the same customization point names
• Boilerplate Complexity: The tag_invoke pattern, while solving namespace issues, requires significant repetitive code

TInCuP's Solution

TInCuP bridges the gap between tag_invoke's theoretical benefits and practical usability:

✅ Eliminates Boilerplate - Automated code generation from simple JSON specifications
✅ Enforces Consistency - Pattern verification ensures uniform implementations
✅ Developer Experience - Comprehensive IDE integrations make invisible interfaces visible
✅ Static Dispatch Integration - Compile-time optimization for runtime configuration choices
✅ Future-Proof - Standardized patterns enable automated refactoring as the language evolves

Bridge Technology: TInCuP makes tag_invoke practical today while C++ evolves toward better built-in solutions.

Features

• Header-Only C++20 Library: A single header <tincup/tincup.hpp> provides all necessary components.
• Static Dispatch Integration: Built-in compile-time dispatch utilities (BoolDispatch, StringDispatch) that convert runtime configuration into zero-overhead template specializations.
• Enhanced Error Diagnostics: Comprehensive misuse detection system catching 5 major categories of CPO mistakes with helpful, educational error messages (even more sophisticated with C++23). Performance opt-outs available.
• CMake and Meson Support: First-class integration with both build systems for easy inclusion in any project.
• Powerful Code Generator: A Python-based command-line tool, cpo-generator, to automatically generate CPO boilerplate from simple JSON definitions, including static dispatch-enabled CPOs.
• IDE/Editor Integration: Full support for Vim, VSCode, and CLion with plugins, templates, and external tools.
• Modern & Friendly: Designed with modern C++ and Python practices to be user-friendly and easy to extend.

Try Before Installing

Want to experiment with TInCuP before installing? Use our Compiler Explorer examples:

• Basic Printing
• Bool Dispatch

Enhanced Error Diagnostics:

Error \ Compiler	x86-64 clang-20.1.0	x86-64 gcc 14.1
Forgetting to Dereference a Pointer	CLICK	CLICK
Passing a const When Mutable Expected	CLICK	CLICK
Incorrect Argument Order	CLICK	CLICK
Incorrect Arity	CLICK	CLICK

Compiler flags used: -std=c++20 -Wno-c++26-extensions -O2 -DTINCUP_DIAGNOSTIC_LEVEL=3 -DCOMPILER_EXPLORER

Installation

• Python tools (latest): pip install TInCuP (installs the cpo-generator CLI)
• Python tools (this release): pip install TInCuP==1.0.4
• From source (development): pip install -e .

Troubleshooting CLI on macOS/Linux:

• If cpo-generator is not found after install, ensure your user scripts directory is on PATH:
  • export PATH="$(python3 -m site --user-base)/bin:$PATH"
  • Add the line above to your shell profile (e.g., ~/.zshrc or ~/.bashrc).
• Alternatively, use pipx to manage CLI tools: pipx install TInCuP or pipx install TInCuP==1.0.4
• The module form always works: python3 -m cpo_tools.cpo_generator --help.

Quick Start & Documentation

New to the project? See our Getting Started Guide.

For full documentation, including guides on the C++ library, code generator, build system integration, and more, please see the TInCuP Documentation.

Want to see examples? Check out:

• Generated CPO Examples - Auto-generated examples showing different CPO patterns
• Working Examples - Complete, buildable projects demonstrating real-world usage

Get, Feedback, Contribute

• Obtain:
  • PyPI (latest): pip install TInCuP
  • PyPI (this release): pip install TInCuP==1.0.4
  • Source: git clone https://github.com/sandialabs/TInCuP.git && cd TInCuP && pip install -e .
• Feedback (bugs/enhancements): Open an issue: https://github.com/sandialabs/TInCuP/issues
• Security reports: see SECURITY.md
• Contribute: Read CONTRIBUTING.md and follow our Code of Conduct

Supported Compilers

TInCuP is tested on CI with strict C++20 compliance:

• GCC: 12+ (tested on Ubuntu, comprehensive C++20 support)
• Clang: 15+ (tested on Ubuntu/macOS, excellent C++20 support)
• MSVC: 2019 16.11+ / 2022+ (tested on Windows, /std:c++20 /permissive-)

References

• N4381 Customization Point Design in C++11 and Beyond
• Suggested Design for Customization Points
• P1895R0 tag_invoke: A general pattern for supporting customisable functions
• P2279R0 We need a language mechanism for customization points

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.