h5cpp-compiler
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
debian
h5cpp-llvm
src
CHANGES
CONTRIBUTORS
INSTALL
Makefile
README
README.md
TODO
h5cpp.1

README.md

Source code transformation tool for HDF5 dataformat H5CPP header only library

This source code transformation tool simplifies the otherwise time consuming process of generating the shim code for HDF5 Compound datatypes by building the AST of a given TU translation unit, and identifying all POD datatypes referenced from H5CPP operators/functions. The result is a seamless persistence much similar to python, java or other reflection based languages.

The following excerpt shows the mechanism, how vec variable is marked by h5::write operator. When h5cpp tool is invoked it builds the full AST of the translation unit, finds the referenced types, then in topological order generates HDF5 COMPOUND datatype descriptors. The generated file has include guards, and meant to be used with H5CPP template library. POD struct types may be arbitrary deep, embedded in POD C like arrays, and may be referenced from STL containers. Currently stl::vector is supported, but in time full support will be provided.

...
std::vector<sn::example::Record> vec 
    = h5::utils::get_test_data<sn::example::Record>(20);
// mark vec  with an h5:: operator and delegate 
// the details to h5cpp compiler
h5::write(fd, "orm/partial/vector one_shot", vec );
...

// some include files with complex POD types, embedded in arbitrary name space
namespace sn {
	namespace typecheck {
		struct Record { /*the types with direct mapping to HDF5*/
			char  _char; unsigned char _uchar; short _short; unsigned short _ushort; int _int; unsigned int _uint;
			long _long; unsigned long _ulong; long long int _llong; unsigned long long _ullong;
			float _float; double _double; long double _ldouble;
			bool _bool;
			// wide characters are not supported in HDF5
			// wchar_t _wchar; char16_t _wchar16; char32_t _wchar32;
		};
	}
	namespace other {
		struct Record {                    // POD struct with nested namespace
			MyUInt                    idx; // typedef type 
			MyUInt                     aa; // typedef type 
			double            field_02[3]; // const array mapped 
			typecheck::Record field_03[4]; //
		};
	}
	namespace example {
		struct Record {                    // POD struct with nested namespace
			MyUInt                    idx; // typedef type 
			float             field_02[7]; // const array mapped 
			sn::other::Record field_03[5]; // embedded Record
			sn::other::Record field_04[5]; // must be optimized out, same as previous
			other::Record  field_05[3][8]; // array of arrays 
		};
	}
	namespace not_supported_yet {
		// NON POD: not supported in phase 1
		// C++ Class -> PODstruct -> persistence[ HDF5 | ??? ] -> PODstruct -> C++ Class 
		struct Container {
			double                            idx; // 
			std::string                  field_05; // c++ object makes it non-POD
			std::vector<example::Record> field_02; // ditto
		};
	}
	/* BEGIN IGNORED STRUCT */
	// these structs are not referenced with h5::read|h5::write|h5::create operators
	// hence compiler should ignore them.
	struct IgnoredRecord {
		signed long int   idx;
		float        field_0n;
	};
	/* END IGNORED STRUCTS */

CAVEAT:

  1. This LLVM/CLANG based tool requires a syntacticly/semantically valid input, otherwise silently fails with empty generated file. This is a result of the internal LLVM error reporting mechanism being muted, on the grounds that the input files: the actual TU translation unit is incomplete yet, and having that information printed would confuse users. Currently work is being done to design an alternative error reporting mechanism that allow to prcess and report syntactic errors on incomplete translation units.

  2. To compile h5cpp source code transformation tool is non-trivial, requires properly set up LLVM 6.0.0 environment with clang support. It is strongly suggested to download the debian based binary package.

  3. it requires the provided h5cpp-llvm/* include files be reachable only in the h5cpp tool invocation, otherwise the include files may collide the system compiler include files. This is not an error, but the property of the underlying LLVM/clang system. The correct invocation is: h5cpp your_translation_unit.cpp -- -v $(CXXFLAGS) -I/usr/include/h5cpp-llvm -Dgenerated.h given that h5cpp ins installed in /usr/bin.