pycppgen

Overview

pycppgen is a Python script designed to parse and generate C++ reflection code based on user-defined tags. By embedding specific tags within your C++ code, the script dynamically generates reflection-ready templates and attributes to streamline your development workflow.

Motivation

This project was created as:

1. A learning exercise to explore Python programming.
2. A solution to improve reflection mechanisms within my Vulkan framework: VkFramework.

Design requeriments

• Non-instrusive: except for the comments to declare attributes.
• Fast: short iteration times are important.
• Flexible: no fixed tags or attributes.
• Plug & Play: just run the script and include the generated files.
• Inline everything: Support static linking and inherit reflection data from dependencies.

Features

• Tag-Based Code Generation: Add $[[pycppgen]] or $[[pycppgen <attributes>]] to a declaration in your C++ code to generate reflection data.
• Reflection Support: Includes both language reflection and user-provided attributes to enhance metadata management.
• Fast change detection: Caches as much data as possible to allow fast iteration

Similar projects and why I didn't use them

https://github.com/Manu343726/siplasplas: A library for C++ reflection and introspection -> doesn't support custom attributes https://github.com/jsoysouvanh/Refureku/tree/master: Refureku is a powerful C++17 runtime reflection dynamic library -> instrusive https://github.com/rttrorg/rttr: RTTR stands for Run Time Type Reflection -> macro based manual registration https://github.com/Neargye/magic_enum: Header-only C++17 library provides static reflection for enums, work with any enum type without any macro or boilerplate code -> I might end up using this one

The test

• Iterate over all enums and values, convert enum to string and string to enum (TODO: bit flags)

• Iterate over all reflected types and its members

• Dynamic reflection

Real world usage

Previous vkfw reflection was macro based:

And the macros weren't nice:

It was replaced by a single function:

And tags to the members:

Which generated the members info

And function wrappers

Usage

1. Clone the repository:

   git clone [https://github.com/<your-repo-name>.git](https://github.com/leobenaducci/pycppgen.git)

2. Run the Python script on your C++ files:

   python main.py <project-path> <options>
   options:
      -I<include_dir>
      -D<definition>
      --I<include_dirs_separated_by_semicolons>
      --D<dependencies>

3. Add $[[pycppgen]] or $[[pycppgen <attributes>]] tags in your C++ code where you want templates to be generated.

   Example struct decl:

   //$[[pycppgen tag1=3.f;test_tag=string with spaces;serialize]]
   struct A {
   
      //$[[pycppgen editable]]
      size_t B = 1;
   };
   

   Example enum decl:

   //$[[pycppgen bitflags]]
   enum class E : int {
      None = 0,
      Something = 1, //$[[pycppgen hidden]]
      Value = 2,
   };
   

Contribution

Feel free to fork the repository and submit pull requests. Suggestions and improvements are always welcome!

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Leo Benaducci (https://www.linkedin.com/in/leobenaducci/)