CCTZ fills the gap the C++ standard library left open: a time zone with real rules

Two cooperating libraries, one job

CCTZ is not a single library but two that cooperate with the C++11 chrono library to give programmers the tools for dates, times and time zones.

The Civil-Time Library is header-only and handles human scale time. Dates are represented by the cctz::civil_day class, and the header lives in include/cctz/civil_time.h. The Time-Zone Library does the actual conversion between absolute time and civil time, using the IANA time zone database installed on the system, and is declared in include/cctz/time_zone.h. A time zone is represented by an instance of the class cctz::time_zone.

The split matters in practice. If you only need civil arithmetic, the header-only half has no library to link against. If you need to convert a UTC instant into local time, or to interpret a wall clock reading in a named zone, you need the time zone half and the zoneinfo data behind it.

The description of the project is precise about scope: a library for translating between absolute and civil times using the rules of a time zone. That is a narrower promise than a general purpose date and time library, and it is one the codebase appears to keep.

The README also states plainly that this is not an official Google product, which is worth knowing before you look for support commitments.

Why absolute time, civil time and time zone are separate concepts

The conceptual part of the documentation is the part that earns the library its place, so it is worth restating the three ideas it separates.

Absolute time uniquely represents an instant. It has no calendar, no date and no time of day, typically a count of ticks since an epoch. It is independent of every time zone and is unaffected by daylight saving time. In modern C++ it is a std::chrono::time_point, and the older time_t still works.

Civil time is the human scale representation, six fields, year through second, following the proleptic Gregorian calendar. It is also independent of time zones. The point the documentation makes here is that std::tm holds those six fields but carries no behaviour that enforces civil time rules, so it cannot police calendar arithmetic for you.

Time zones are the geopolitical layer where the rules live: offsets from UTC, daylight saving adjustments, short abbreviations, and a history of rules that changed at the discretion of local governments. Because of that history, time zone rules are compiled into data snapshots used at runtime for conversions. The documentation notes that there is no C++ standard library support for arbitrary time zones, which is the gap CCTZ fills.

The library is therefore an addition to chrono, not a replacement. Absolute time keeps working exactly as it does today; what CCTZ supplies is the bridge between the two domains and the data to make that bridge correct.

Building with CMake and linking the imported target

Bazel is the primary build system, with Google Test as the test framework, and the documentation says so before offering anything else. A simple Makefile and a CMakeLists.txt exist for people who cannot use Bazel, and the CMake path requires CMake 3.16 or newer.

The CMake sequence builds a release library and runs the tests, and the same block ends with an install target so the library can be placed on the system:

        mkdir mybuild
        cd mybuild
        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_POSITION_INDEPENDENT_CODE=ON ..
        cmake --build . --config Release
        ctest
        cmake --build . --config Release --target install

Two flags carry the intent. The release build type and the position independent code flag are what you want if the library will end up inside a shared library, and the documentation notes that the tests can be skipped by passing BUILD_TESTING=OFF.

Consuming it from another CMake project is three lines, and the target name tells you this package installs a proper exported target rather than a bare list of headers:

    find_package(cctz REQUIRED)
    add_executable(mytarget file.cc)
    target_link_libraries(mytarget cctz::cctz)

The documentation adds a practical note at the end: when using CCTZ in your own project, you might find it easiest to compile the sources using your existing build system. The CMake route is the convenient one, not the mandatory one.

The Makefile fallback and what it exposes about the build

The Makefile exists for a specific audience, stated in its own header comment: people who cannot use Bazel and cannot compile the sources in their own build system. It is not a first class build definition, and reading it still tells you useful things about how the library expects to be consumed.

The knobs at the top are minimal and settable from the environment:

CXX ?= g++
CXXFLAGS ?= -O3
STD ?= c++11
LDFLAGS ?= -O3
PREFIX ?= /usr/local
DESTDIR ?=

The default standard is c++11, which is the floor the library targets, and the default install prefix is /usr/local with a DESTDIR override for packaging. The compiler and flags are conventional make variables with the question mark assignment form, so they can be overridden without editing the file.

The header comment also gives the suggested usage for a local build and for a versioned shared library on Linux, the latter setting SHARED_LDFLAGS with a soname of libcctz.so.2 and a CCTZ_SHARED_LIB of libcctz.so.2.0. The library name in the Makefile is built from a CCTZ variable, with the static archive named accordingly.

The sources themselves live in src/ with the public headers under include/cctz/, and the build picks up both through VPATH. If you are integrating into an existing build, compiling the sources directly, as the documentation suggests, is the low friction route.

Windows still needs zoneinfo files you supply yourself

The platform support story is short and has one clear gap. The libraries are described as known to work on Linux, Mac OS X and Android.

Windows is the exception. The documentation says they will also work on Windows if you install the zoneinfo files. That is the whole requirement, and it is a real operational burden: the IANA database is not installed by default on Windows, so a deployment that assumes local time zone rules must arrange for those files to be present and current on every machine that runs the binary.

The project is explicit that it is interested in an implementation of the cctz::TimeZoneIf interface that calls the Windows time APIs instead, and invites contributions for it. The interface is the extension point, which means the boundary is designed rather than accidental: the time zone lookup is behind an interface that a platform specific implementation could satisfy.

No such implementation ships in the versions described here. So on Windows you are choosing between vendoring zoneinfo files, which means owning their update cycle, or writing your own TimeZoneIf implementation against the native APIs, which is the contribution the maintainers are asking for.

This is the single most important fact for a Windows only product, and it is stated plainly rather than buried.

The examples directory is the fastest way to learn the API

The repository ships a set of example programs, and they are the practical answer to how to start using the library.

The examples/ directory contains hello.cc, classic.cc, epoch_shift.cc and example1.cc through example4.cc, with its own CMakeLists.txt so the examples build as part of the project. The documentation tells new users to look at the examples, alongside the two headers for civil time and time zone, as the next step after building.

The names suggest a deliberate progression. The README section that is included in the visible documentation is titled Hello February 2016, which points at a first program that produces a specific, checkable output rather than a generic tutorial. epoch_shift.cc implies a discussion of absolute time origins, and classic.cc suggests the traditional interface. Since the contents of each file are not shown here, treat the names as an indication of coverage rather than a specification.

The documentation also points to a mailing list for questions and change announcements, and the repository root contains a BUILD file, a MODULE.bazel file, a CMakeLists.txt, a cmake/ directory, testdata/ and a CONTRIBUTING.md. The testdata/ directory matters for anyone caring about correctness, since it presumably holds the zone data used by the test suite.

Apache 2.0 terms and a slow release cadence

The licence is Apache 2.0, with the text in LICENSE.txt. That is a permissive licence with an explicit patent grant and a requirement to preserve notices, and it carries no obligation on the source of your own project beyond including the licence text. There is no copyleft requirement, so linking CCTZ into a closed source product is not a licensing problem.

The project disclaims official Google product status in its opening line, which is a practical signal about where support comes from: issues, the mailing list and the contributor community rather than a vendor.

The release history is spaced out. The published versions are v2.5 from 2025-06-16, v2.4 from 2024-02-15 and v2.3 from 2019-04-03. The gap between v2.3 and v2.4 is close to five years, and the gap from v2.5 to the last push on 2026-10-14 is about sixteen months. The repository is not archived, and the last push was on 2026-10-14, so work continues even though a new version tag is not in sight.

For a dependency, that pattern means you should expect to sit on a release for a long time. Plan your upgrade around the source tree rather than around release announcements, and check whether the fixes you need are in the tree between tags.

Editorial conclusion

Adopt CCTZ if your C++ code has to convert between instants and human readable dates in named time zones and you want the IANA database to be the source of truth. Do not adopt it for a Windows only product unless you are prepared to ship zoneinfo files yourself, because the project documents no implementation that calls the native Windows time APIs. Before integrating, run bazel test :all or the CMake test sequence on your own platform, confirm that the zoneinfo files present on your build and runtime machines match the rules your product depends on, and read include/cctz/time_zone.h for the exact lookup behaviour you are relying on.

Frequently asked questions

Official sources

1. google/cctz on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases