<!---
 Copyright (c) 2018 vargaconsulting, Toronto,ON Canada
 Author: Varga, Steven <steven@vargaconsulting.ca>
--->


Compiling arbitrary POD types to HDF file compund types with H5CPP compiler   {#link_h5cpp_compiler}
====================================================================================================

h5cpp compiler is a fully functional clang based source code transformation tool, that identifies POD C/C++ struct types referenced by 
`h5::create | h5::read | h5::write | h5::append` operators in each TU translation units and generates the necessary HDF5 data descriptions. 

What does this mean in plain English? You take some include files, and a valid c++ program file, then all you have to do to create an HDF5 dataset is
the following:
```cpp
#include <h5cpp/core>
/* 'ddl.h' will be generated by 'h5cpp' see below '-Dddl.h' option
 the translation unit TU mustbe a valid error free c++17 code with the exception of 
 missing 'ddl.h' file. 
 */
#include <ddl.h>

#include <h5cpp/io> 

int main() {
	h5::create<some_complicated_struct>("file.h5", "dataset_name", h5::gzip{9} | h5::chunk{512} );
	return 0;
}
```
then invoke the compiler which will create the data definitions for you:
```bash
h5cpp  struct.cpp --  -I../path/to/h5cpp-llvm  -Dddl.h
```
Beside `h5::create` there are convenient IO operators `h5::read | h5::write | h5::append` provided, they work independently from `h5::create` and capable of producing the right output. Follow [these instructions](@ref link_h5cpp_install) to set up llvm 7.0.0 to compile the tool.

**CAVEAT:**
LLVM/CLANG++ **error messages are suppressed**, in case of passing invalid translation unit, a set of c++17 files, no error message is produced. This is because of the compile phase is two pass:
1. build up AST from translation unit, and find the referenced struct dataype
2. produce output that will be included in later

Therefore in this phase the input translation unit is invalid, and will produce error message, no matter what. To prevent false negative it was decided to suppress error messages entirely. The author is aware of the built in BUG: **invalid translations units will not have error messages printed out**; In time, if there is interest in the compiler/source code transformation tool, the error reporting capability may be restored.

The `h5cpp-llvm` directory must contain the llvm includes `h5cpp` was compiled with. In case of static linking this directory still must be present, as the clang tooling runtime architecture depends on it.

