libqasm
library for handling cQASM files
src/cqasm/tree-gen/README.md
Go to the documentation of this file.
1 # tree-gen
2 
3 [![Documentation Status](https://readthedocs.org/projects/tree-gen/badge/?version=latest)](https://tree-gen.readthedocs.io/en/latest)
4 [![GitHub Actions Build Status](https://github.com/QE-Lab/tree-gen/workflows/Test/badge.svg)](https://github.com/qe-lab/tree-gen/actions)
5 
6 `tree-gen` is a C++ and Python code generator for tree-like structures common in
7 parser and compiler codebases. The tree is described using a simple and concise
8 language, so all the repetitive C++ and Python stuff can be generated. This
9 includes serialization and deserialization to [CBOR](https://cbor.io/), allowing
10 easy interoperation between C++ and Python.
11 
12 ## Usage and "installation"
13 
14 `tree-gen` is a very lightweight tool, intended to be compiled along with your
15 project rather than to actually be installed. The assumption is that your main
16 project will be written in C++ and that you're using CMake. If these assumptions
17 are invalid, you'll have to do some extra work on your own. If they *are* valid,
18 however, it should be really easy. Just include `tree-gen` as a submodule or
19 copy it into your project, then do something like
20 
21 ```cmake
22 add_subdirectory(tree-gen)
23 
24 # To generate the files from your tree description file:
25 generate_tree_py(
26  "${CMAKE_CURRENT_SOURCE_DIR}/input-tree-specification.tree"
27  "${CMAKE_CURRENT_BINARY_DIR}/generated-header-file.hpp"
28  "${CMAKE_CURRENT_BINARY_DIR}/generated-source-file.cpp"
29  "${CMAKE_CURRENT_BINARY_DIR}/generated-python-file.py"
30 )
31 
32 # To add generated-source-file.cpp to your program:
33 add_executable/add_library(
34  my-software
35  "${CMAKE_CURRENT_BINARY_DIR}/generated-source-file.cpp"
36 )
37 
38 # To add generated-header-file.hpp to the search path:
39 target_include_directories(
40  my-software
41  PRIVATE "${CMAKE_CURRENT_BINARY_DIR}"
42 )
43 
44 # To use tree-gen's support library (you could substitute your own if you feel
45 # up to the task):
46 target_link_libraries(my-software tree-lib)
47 ```
48 
49 and CMake *Should*™ handle everything for you.
50 
51 `tree-gen` does have some dependencies:
52 
53  - A compiler with C++11 support (MSVC, GCC, and Clang are tested in CI);
54  - Flex 2.6.1+
55  - Bison 3.0+
56 
57 If you're on a POSIX system and Flex/Bison are too old or not installed, the
58 buildsystem will attempt to download and build them from source for you.
59 
60 For usage information beyond this, [Read The Docs](https://tree-gen.readthedocs.io/).
61 
62 ## Project structure
63 
64  - `generator`: source and private header files for the generator program.
65  - `src`: source and private header files for the support library.
66  - `include`: public header files for the support library.
67  - `cmake`: contains CMake helper modules for building flex/bison from source
68  if they are not installed.
69  - `examples`: examples showing how to use `tree-gen`. These are also used as
70  tests, and their content and output is directly used to generate the
71  ReadTheDocs documentation.
72  - `tests`: additional test cases for things internal to `tree-gen`.
73  - `doc`: documentation generation for ReadTheDocs.