h5cpp.1

.TH H5CPP 1 2026-06-12 GNU h5cpp programming manual
.SH NAME
h5cpp \- compiles HDF5 compound datatype descriptors from C++ AST
.SH SYNOPSIS
.B h5cpp translation_unit.cpp --$(CXXFLAGS) -Doutput.hpp

.SH "DESCRIPTION"
H5CPP-compiler automates the tedious and error prone process of handwriting HDF5
compound type data descriptors providing similar level of data
serialization/persistence experience of popular interpreted languages
but compile time.
This non-intrusive source code transformation tool is a companion to h5cpp
template library it builds the AST of a specified translation unit,
identifies arbitrary deep POD struct variables referenced/used by the
template library operators:
.EX
    h5::create | h5::read | h5::write | h5::append
    h5::acreate | h5::aread | h5::awrite
.EE
and generates the necessary HDF5 compound datatype descriptors. In the second
phase, invoking system compiler (gcc,clang,msvc, ...)  on the now complete
translation unit produces the binary object file.

The h5cpp compiler assisted reflection and its companion header library
was developed for low latency event stream recording arising in high
frequency trading applications, Real Time Bidding and general machine
learning.

Primary competing idea to compiler assisted reflection is the recently
developed purely template based introspection and reflection for C++
which is not yet available. While there are many related work based on
runtime approach, or templates most of them requiring some modification
to original code making it intrusive, or less performance oriented.


.SH OPTIONS
.TP
.B -D
output filename to be generated
.TP
.B -v
verbose invocation of the underlying clang tooling framework to aid you with 
identifying search paths, etc...

.SH EXAMPLES
.B h5cpp translation_unit.cpp -- $(CXXFLAGS)  -Dgenerated.h
will build AST from translation_unit.cpp and create HDF5 compound descriptors in generated.h given 
the following POD struct type Record:
.PP
.EX
.B struct.h:
.in +4n
struct particle_t {
    double x, y, z;
    int id;
};
.in
.EE
.PP
The output file `generated.hpp` are to be included in the translation unit file as if it existed,
as the following code snippet demonstrates:

.PP
.EX
.BI translation_unit.cpp:
.in +4n
#include <h5cpp/all>
#include <vector>
#include "struct.h" 
#include "generated.hpp"

int main() {
    auto fd = h5::create("run.h5", H5F_ACC_TRUNC);
    std::vector<particle_t> particles(100);
    h5::write(fd, "particles", particles);
}

.in
.EE
.PP
Once the LLVM based tool builds the AST, and identifies the entire tree of objects marked with the previously
discussed CRUD like operators, it will produce the correct minimal HDF5 type descriptor and the necessary 
registration macro.
.PP
.EX
.B generated.h:
.in +4n
/* Copyright (c) 2018-2026 vargalabs, Toronto,ON Canada */
#pragma once
#include <hdf5.h>

namespace h5 {
    //template specialization of particle_t to create HDF5 COMPOUND type
    template<> hid_t inline register_struct<particle_t>(){

        hid_t ct_00 = H5Tcreate(H5T_COMPOUND, sizeof (particle_t));
        H5Tinsert(ct_00, "x",	HOFFSET(particle_t,x),H5T_NATIVE_DOUBLE);
        H5Tinsert(ct_00, "y",	HOFFSET(particle_t,y),H5T_NATIVE_DOUBLE);
        H5Tinsert(ct_00, "z",	HOFFSET(particle_t,z),H5T_NATIVE_DOUBLE);
        H5Tinsert(ct_00, "id",	HOFFSET(particle_t,id),H5T_NATIVE_INT);

        //if not used with h5cpp framework, but as a standalone code generator then
        //the returned 'hid_t ct_00' must be closed: H5Tclose(ct_00);
        return ct_00;
    };
}
H5CPP_REGISTER_STRUCT(particle_t);

.in
.EE
.PP
Typically the compiler is invoked from a
.B Makefile
in the following manner:
.PP
.EX
.B Makefile:
.in +4n
[...]
generated.h: struct.h
	h5cpp  struct.cpp -- $(CXXFLAGS) $(INCLUDES) -Dgenerated.h

struct.o : struct.cpp generated.h 
	$(CXX) $(INCLUDES) -o struct.o  $(CXXFLAGS) -c struct.cpp

struct: struct.o
	$(CXX) $^ $(LIBS) -o $@	
.in
.EE
.PP

Details set of examples may be found in
.B /usr/share/h5cpp/compound
directory, for general use cases, interaction with linear algebra libraries as well as 
scaling the library to MPI based clusters.


.SH AUTHOR
2018-2026 steven varga <steven@vargalabs.com>

.UR http://h5cpp.org