`logos-cpp-generator` bridges pure C++ module implementations to the Logos runtime's Qt plugin system. Module authors write standard C++ and the generator produces all Qt boilerplate automatically.
## The --from-header Pipeline
This is the primary mode for universal modules:
```
C++ impl header (your code)
│
▼
parseImplHeader() — extracts public methods, maps C++ types to LIDL types
│
▼
ModuleDecl (internal AST)
│
├──► <name>_qt_glue.h — Plugin class + ProviderObject with typed wrappers
1.**ProviderObject** — Inherits `LogosProviderBase`. Holds `m_impl` (your impl class). Each public method gets a typed wrapper that converts Qt params to C++ std params, calls `m_impl.method(...)`, and converts the return value back. For `LogosMap`/`LogosList` returns, an `nlohmannToQVariant()` helper handles the conversion. If the impl declares a public `emitEvent` callback, the constructor wires it to `LogosProviderBase::emitEvent`.
`LogosMap` and `LogosList` (from `<logos_json.h>`) are `nlohmann::json` aliases for returning structured data without Qt. The generator sets a `jsonReturn` flag on these methods and emits an `nlohmannToQVariant()` conversion in the glue layer.
LIDL is a lightweight Interface Definition Language. Instead of parsing a C++ header, you write a `.lidl` file:
```
module crypto_utils {
version "1.0.0"
description "Cryptographic utilities"
method hash(input: tstr) -> tstr
method verify(input: tstr, hash: tstr) -> bool
method generateKey(bits: int) -> tstr
method listAlgorithms() -> [tstr]
}
```
Both paths (C++ header and LIDL) produce identical generated output. Use `--from-header` for most modules; use LIDL when you want to define the interface before writing the implementation.
## Common Issues
- **Unknown type warning**: If the generator encounters a C++ type not in the mapping table, it maps to `any` (`QVariant`). Prefer explicit types from the table.
- **Class not found**: `--impl-class` must exactly match the class name in the header (case-sensitive).
- **metadata.json mismatch**: The `name` in metadata.json must match the expected plugin binary name.
- **Generated files not found by CMake**: Ensure `generated_code/` files are listed in `CMakeLists.txt` SOURCES and the directory is in INCLUDE_DIRS.
## In CMakeLists.txt
```cmake
logos_module(
NAMEmy_module
SOURCES
src/my_module_impl.h
src/my_module_impl.cpp
generated_code/my_module_qt_glue.h
generated_code/my_module_dispatch.cpp
INCLUDE_DIRS
${CMAKE_CURRENT_SOURCE_DIR}/generated_code
)
```
## In flake.nix
The generator runs in `preConfigure`, before CMake:
