Boost.Hana metaprogramming is a compile-time cost you schedule up front

One syntax for values and types, and that is the whole pitch

Boost.Hana calls itself a standard library for metaprogramming, and its argument is that C++ should not need two languages. The library gives you sequences that hold heterogeneous objects, algorithms that operate on them, and the same set of operations on types themselves, all spelled the same way.

The overview example makes the claim concrete. A tuple holds a Fish, a Cat and a Dog, and hana::transform maps a lambda over it to produce names, then hana::reverse returns a tuple of strings in the opposite order. Crucially, the length of the original sequence is still a constant expression even though the sequence itself cannot be, because it holds std::string:

auto animals = hana::make_tuple(Fish{"Nemo"}, Cat{"Garfield"}, Dog{"Snoopy"});
auto names = hana::transform(animals, [](auto a) { return a.name; });
static_assert(hana::length(animals) == 3u, "");

That separation between what is known at compile time and what is only known at runtime is the practical reason to reach for Hana rather than a hand written template recursion.

Type computation with runtime-looking syntax, and is_valid replaces SFINAE

The second half of the example manipulates types rather than values. hana::type_c wraps a type so it can live inside a sequence, hana::filter keeps the pointer types, and the result is compared against an expected tuple entirely inside a static_assert. Nothing runs at runtime; the compiler is doing the work and the assertion either compiles or fails the build.

Element access uses an integer literal in the hana::literals namespace, so animal_ptrs[0_c] picks the first element and the index is itself a compile-time object. Loop unrolling is a method call on a constant, hana::int_c<10>.times([]{ ... }), which the README compares to writing the same statement out ten times.

The feature with the widest reach outside Hana is is_valid. It asks whether an arbitrary expression compiles, which is the job the README says usually requires complex SFINAE-based tricks:

auto has_name = hana::is_valid([](auto&& x) -> decltype((void)x.name) { });
static_assert(has_name(animals[0_c]), "");
static_assert(!has_name(1), "");

Detection idioms like this come up in any generic code that has to branch on what a type supports, and having one is worth the include on its own.

Header-only, but the build system is CMake and the tests are heavy

Using Hana means adding include/ to your include path; there is nothing to link. Working on the library itself is a different matter, and the README devotes most of its length to that, which is a hint about who the document is for.

The contributor setup needs CMake and a build directory:

mkdir build
cmake -S . -B build
cmake --build build --target check

A custom compiler can be selected when the system one is too old, and a custom Boost location with BOOST_ROOT. Hana looks for Boost headers if they are present and disables the few tests that need them otherwise, so Boost is optional for building the library.

The warning that matters for contributors and for anyone mirroring the CI: compiling the unit tests is described as time and RAM consuming, especially the tests for external adapters, because the tests are thorough and heterogeneous sequences from other libraries have poor compile-time performance. Optional targets, such as documentation generation with Doxygen, are enabled only when the software is present, and CMake prints which ones were skipped.

New source files become targets named after their path

The test and example layout is unusual enough to be worth knowing before you start. Adding a source file at path/to/file.cpp and re-running the CMake generation step creates a target called path.to.file, dots replacing slashes, and a CTest test of the same name. Building and running it takes two commands:

cmake --build build --target path.to.file
ctest --test-dir build -R path.to.file

This is why the example/ directory contains a flat list of files named after the algorithm they demonstrate, such as adjust_if.cpp, all_of.cpp, any_of.cpp, ap.cpp, cartesian_product.cpp and comparing.cpp. The file list is effectively an index of the library's API surface, which makes it a fast way to learn what exists before diving into the reference documentation.

There are also subdirectories for a basic_tuple and core, plus a cmake_integration example, which suggests the build integration story is treated as a first class concern.

Documentation lives elsewhere, including an offline copy

The README explicitly declines to be user documentation. Installation, a tutorial explaining what Hana is and how to use it, and the full reference with examples are hosted at boostorg.github.io/hana, and the README says the rest of the file is mostly for people working on the library.

For offline use, the documentation is a branch, and you can clone just that branch shallowly into a subdirectory:

git clone http://github.com/boostorg/hana --branch=gh-pages --depth=1 doc/html

The doc/html directory is automatically git-ignored, so refreshing the documentation does not pollute your index. That arrangement is unusual and convenient, and it also means the doc/ directory in your working tree is not the source of the website.

The other notable directories are benchmark/, described as compile-time and runtime benchmarks written mostly as eRuby templates that generate C++ files before compiling them and collecting statistics, and meta/, which holds the data the library uses about its own API.

Version history, the Boost license, and who absorbs the compile time

Hana lives inside the Boost organisation and is distributed under the Boost Software License 1.0, which is permissive and requires only that the license text travels with source and binary redistributions. If you already ship Boost, adding Hana raises no new licensing question.

The versioning is where a reader should slow down. The most recent tagged releases in this repository are version 1.7.0 from 2020-09-03 and version 1.6.1 from 2020-08-26, with version 1.5.0 marked as synced with Boost 1.68.0 back in 2018. The repository is not archived and master was last pushed on 2026-08-12, so the branch is being changed without new standalone tags.

That gap is normal for a library that ships as part of Boost releases rather than on its own cadence, but it means a version number tells you less than it looks like it does. In practice you should decide which Boost release you are pinning and take Hana from there, rather than tracking the master branch, because compile-time behaviour is exactly the kind of thing that changes in ways a static_assert will catch and a runtime test will not.

Editorial conclusion

Hana earns its place in a header library or a build that already leans on templates, where heterogeneous sequences and expression validity checks are hard to express otherwise. It is a poor fit for a small application that only needs a tuple, and the upstream releases stop at version 1.7.0 from 2020-09-03 even though the master branch was pushed on 2026-08-12, so pin your Boost release deliberately. Before adopting it, compile one translation unit that includes boost/hana.hpp with your real types and time it, then read the documentation at boostorg.github.io/hana rather than the README, which is aimed at contributors.

Frequently asked questions

Official sources

1. boostorg/hana on GitHub
2. License: BSL-1.0
3. Project website
4. README
5. Releases