cpp-iface-gen
Protocols: Interface Gen
The Node-free C interface generator. It reads the JSON Schemas in `schemas.readonly` and emits one typed
C header per schema, so no per-protocol .h/.cpp is maintained by hand. It is the C++ twin of
npm-iface-gen: both read the same ifacegenconfig.json, pin a schema
to the same hash, and generate the same names.
Adding iface-gen to the Project
The commands in this section are run from the root of the consuming project, the directory that holds
ifacegenconfig.json, with the submodule checked out as cpp-iface-gen.git directly beneath it. Adjust the paths
if the submodule lives elsewhere, for example under src/.
Adding the submodule
cpp-iface-gen is added to the consuming project as a git submodule, next to the project’s other *.git
submodules (at the repo root, or under src/; existing projects do both). The generated headers extend the
base classes of cpp-json-msg, so that submodule comes along:
git submodule add git@gitlab.com:interop-protocols/cpp-iface-gen.git cpp-iface-gen.git
git submodule add git@gitlab.com:interop-protocols/cpp-json-msg.git cpp-json-msg.git
git submodule update --init --recursive
The generated headers #include two things in place, nothing is copied: the runtime
cpp-iface-gen.git/Iface.h and the base classes cpp-json-msg.git/json_msg+ack.h. The default include
paths therefore assume the two submodules are siblings in a directory that is on the include path (the
directory holding them is added with target_include_directories). A different layout is accommodated
with --iface-include / --base-include, or the per-target keys of the same name (see
ifacegenconfig.json).
Compiling
The generator is source only; the submodule ignores its own build/ and the binary, so each checkout
builds it once. It depends on nlohmann/json and nothing else (the
SHA-256 implementation is vendored):
vcpkg install nlohmann-json
cmake -S cpp-iface-gen.git -B cpp-iface-gen.git/build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build cpp-iface-gen.git/build --config Release
ctest --test-dir cpp-iface-gen.git/build # optional: SHA-256 self-test + end-to-end tests
With a multi-config generator (Visual Studio, Xcode) the binary lands in the configuration’s subdirectory,
cpp-iface-gen.git/build/Release/iface-gen (iface-gen.exe on Windows), which is the form the examples on this
page use. A single-config generator (Make, Ninja) ignores --config and puts it in cpp-iface-gen.git/build/
directly.
-
Plain CMake does not read
$VCPKG_ROOT; without the toolchain filefind_packagefails with "Could not find nlohmann_json". The toolchain is only needed at the configure step and is cached inbuild/. Under Git Bash pass it in Windows form (C:/Users/…/vcpkg.cmake), not as an MSYS/c/…path. On Linuxapt install nlohmann-json3-devworks without a toolchain file. -
The generated headers have two further dependencies that belong to the consuming project, not to the generator: json-schema-validator (used by
Iface.hto validate a message against its embedded schema) andcpp-json-msg. Typicallyfind_package(nlohmann_json_schema_validator CONFIG REQUIRED), linknlohmann_json_schema_validator::validator, and compilecpp-json-msg.git/json_msg+ack.cpp. -
The templates for the IPSME scaffold (
src/IPSME/,src/shells/) are located by searching upward from the executable, so a binary left in its build directory finds them. A binary copied elsewhere needs--templates cpp-iface-gen.git/src.
Nothing in the consuming project’s own build depends on the generator: generated output is committed and compiled like any other source, and the generator is re-run only when a schema or the config changes.
ifacegenconfig.json
One ifacegenconfig.json at the root of the consuming project. The file is shared with the npm
generator: a schema registry (each schema declared once, pinned by its SHA-256) plus a list of output
targets. A target is a C++ target when it has out-cpp; a target without it belongs to the npm
generator and is skipped.
A starter config is printed by a bare --config:
./cpp-iface-gen.git/build/Release/iface-gen --config > ifacegenconfig.json
A C++ consumer (an IPSME participant with two interfaces) looks like:
{
"schemas": {
"Echo": { "src": "~/protocols.git/schemas.readonly/schema_Discovery_objs/schema_Echo.json", "sha256": "<sha256 of the schema bytes>" },
"Discovery": { "src": "~/protocols.git/schemas.readonly/schema_Discovery.json", "sha256": "<sha256 of the schema bytes>" }
},
"targets": [
{
"root": "src",
"IPSME": { "main": "main.cpp", "object": "App", "runtime": "native", "shape": "flat", "out": "IPSME" },
"schema-cache": "schemas",
"out-cpp": "generated",
"prefix": "interface-",
"namespace": "iface_gen",
"delete": true,
"schemas": [ "Echo", "Discovery" ]
}
],
"version": 4
}
All paths in the config are resolved relative to the config file, after a leading ~ and any $VAR /
${VAR} have been expanded. The expansion is done by the generator itself, not by the shell, so it behaves the
same from PowerShell, cmd, bash and an IDE.
srcA src is usually written home-relative, so one committed config works for every developer regardless of where the
consuming project is checked out:
"Discovery": { "src": "~/protocols.git/schemas.readonly/schema_Discovery.json", "sha256": "<sha256 of the schema bytes>" }
-
~is the current user’s home directory:$HOMEon macOS and Linux (/Users/<name>,/home/<name>),%USERPROFILE%on Windows (C:\Users\<name>). The same~/protocols.git/…therefore resolves on every OS as long as the schemas repo is checked out directly under the home directory. -
$VARand${VAR}expand to that environment variable. For the home directory prefer~over$HOME: on WindowsHOMEis normally unset outside Git Bash, and inside Git Bash it is the MSYS-style/c/Users/<name>, which a native program resolves against the current drive to a path that does not exist.$HOMEis fine on macOS and Linux. -
Use forward slashes. Both generators accept
/on every OS, Windows included. Backslashes work only on Windows and must be doubled inside JSON ("~\\protocols.git\\…"), so they tie the config to one platform. The slash style has no effect on the pin: the hash is over the schema’s bytes, not its path. -
A relative
src(../../protocols.git/schemas.readonly/…) resolves against the directory holdingifacegenconfig.jsonand instead ties the config to the checkout layout (the schemas repo as a sibling). Either form is fine; what matters for a build is the pin, and onceschema-cacheis populated thesrcneed not exist at all.
| key | meaning |
|---|---|
|
The config format version. Must be |
|
The registry: |
|
The list of outputs; each entry is described below. |
| key | meaning |
|---|---|
|
Path to the schema (relative to the config, |
|
The pin: the plain |
|
|
| key | meaning |
|---|---|
|
Optional. A relative directory under the config dir; all of the target’s write paths ( |
|
Directory for content-addressed copies of the verified schemas, |
|
Directory for the generated |
|
Literal filename prefix, default |
|
Top-level namespace of the generated classes, default |
|
|
|
The registry names to generate for this target. A name without a registry entry is a hard error. |
|
Optional. Its presence requests the editable IPSME participant scaffold: |
|
Per-target overrides of the |
|
npm targets only; see |
A run writes, per target:
-
out-cpp: one header per schema plus<prefix>introspection.h. Regenerated wholesale; never hand-edit. -
schema-cache: the verified schema copies. Commit. -
main,Interface_<object>.hppand the IPSMEoutdirectory: the participant scaffold. These are yours to edit; a re-run folds template changes into them with a 3-way merge. -
ifacegen-base/next to the config: the merge ancestors for the scaffold. Commit. -
A
* text eol=lf.gitattributesin each managed directory, so anautocrlf=truecheckout cannot smudge the committed artifacts.
CLI interface
Two modes. Config mode (--config <file>) is the one a project uses; ad-hoc mode takes interface
names or schema paths on the command line and reads them from --schemas with no pins or cache. A bare
--config prints the starter config; -h and -v print help and the generator version.
./cpp-iface-gen.git/build/Release/iface-gen --config ifacegenconfig.json # build/iface-gen with Make or Ninja
The generator exits non-zero on any error (a version mismatch, a pin mismatch, an unknown flag), so the line can gate a build step.
iface-gen --helpiface-gen (C++) — Node-free IPSME interface generator (config v3)
Usage:
iface-gen [Name|schema.json ...] [options] ad-hoc: generate from --schemas DIR
iface-gen --config <file> config-driven (registry + targets)
iface-gen --config print a starter config template
Options:
--schemas DIR schema dir for ad-hoc NAME resolution (default: schema)
--out DIR output dir for the generated headers (default: .)
--prefix TOK literal filename prefix (default: interface-)
--namespace NS top-level C++ namespace (default: iface_gen; never bare "iface")
--base-include INC #include path to cpp-json-msg's base header
--iface-include INC #include path to the cpp-iface runtime (Iface.h)
--msgenv-include INC IPSME scaffold: path to IPSME_MsgEnv.h (omit -> commented placeholder)
--eventlog-include INC IPSME scaffold: path to IEventLog.hpp
--eventlog-ext-include INC IPSME bridge: path to InMemory_EventLog_ext.hpp
--templates DIR override the templates dir (default: next to gen.cpp)
--seed-bases adopt existing IPSME scaffold output that has no base
--force corrupt schema-cache blob: re-read the src, verify the pin, rewrite the blob
--clean remove the headers this run would generate, then stop
--delete prune outputs not produced by this run
--no-debug fail if any registry entry has debug:true
--config [file] config mode; bare prints a starter template
-h, --help show this help and exit
-v, --version print the generator version and exit
In config mode the per-target keys supply what the ad-hoc flags would (--out, --prefix,
--namespace, --delete); the flags that remain meaningful alongside --config are the include
overrides (defaults for targets that do not set them), --templates, and the three guards --no-debug,
--seed-bases and --force. --clean is ad-hoc only: it removes the headers the invocation names and
writes nothing, where --delete generates and then prunes.
Generating the Bridge and Responders
Beyond the per-interface headers, a config target with an IPSME block also generates an editable IPSME
participant scaffold: the wiring between the messaging environment and your application that would otherwise be
written by hand. The headers are regenerated wholesale and never edited. The scaffold is the opposite, a skeleton
you fill in, which is why every scaffold file is written through a 3-way merge (see Merge-on-gen: these files are yours to edit).
The IPSME block
{
"root": "src",
"IPSME": { "main": "main.cpp", "object": "App", "out": "IPSME" },
"schema-cache": "schemas",
"out-cpp": "generated",
"namespace": "iface_gen",
"msgenv-include": "cpp-msgenv-sdbus.git/IPSME_MsgEnv.h",
"delete": true,
"schemas": [ "Echo", "Discovery", "MessagingEnv" ]
}
-
main: the participant’s entrypoint file (defaultmain.cpp), written at the target root. -
object: the participant’s name (default: the stem ofmain). It names the application interface,Interface_<object>.hpp, and fills the$object$token in the templates. -
out: the directory for the bridge and the responders (defaultIPSME), relative to the target root. -
msgenv-include,eventlog-include,eventlog-ext-include,base-include: the#includepaths the scaffold is wired with (the transport’sIPSME_MsgEnv.h,IEventLog.hpp, the bridge’sInMemory_EventLog_ext.hpp, cpp-json-msg’s header). Each falls back to the CLI flag of the same name.msgenv-includeis optional: left out, the scaffold emits a commented// #include "IPSME_MsgEnv.h"placeholder for you to point at your transport. -
runtimeandshape: required. The participant’s runtime context and template, in the vocabulary shared with the npm generator. C++ has one template pair, so the only accepted combination is"runtime": "native"(an OS process) with"shape": "flat"(amain()plus an interface class); the JavaScript runtimes and theclassandcomponentshapes are hard errors here, not silent fallbacks. Both are written into the scaffold’s headers as documentation.msgenv-includeis the third axis, the transport: the author’s literal, never derived fromruntimeor the OS. The v3shellkey is a hard error that names the migration.
The templates live in src/IPSME/ and src/shells/ of the submodule and can be overridden with --templates DIR.
What it emits
| file | what |
|---|---|
|
The entrypoint, a stubbed skeleton: it constructs the bridge with |
|
The application interface the responders call back into. Your application implements it; the responders see nothing else of the application. |
|
The singleton bridge. It |
|
One per envelope schema. A private |
Only envelope schemas get a responder. A schema with at least one JSON_Msg/JSON_Eff/JSON_Ack message yields a
Responder_<iface>; a plain-JSON schema (Echo, Hyperport) gets its header but no responder.
Merge-on-gen: these files are yours to edit
Re-running the generator must not clobber your edits, so each scaffold file is written through a git 3-way merge:
-
base: the pristine generated output of the previous run,
-
ours: the file on disk now, that is the base plus your edits,
-
theirs: the freshly generated output.
git merge-file folds template changes into your file and raises conflict markers only where a regenerated line
overlaps a line you touched; everywhere else the merge is silent. The base is kept in a mirror tree next to the
config, ifacegen-base/<target>/<out-rel>/<file>.v<version>, one snapshot per file stamped with the generator
version that produced it (a non-source extension, so it never compiles in). <target> is the target’s root, or
target-01, target-02, … for targets without one. Commit ifacegen-base/ together with the scaffold: it is
what makes the next merge possible on any checkout. The merge needs the git binary on the path.
Every run reports one status per scaffold file:
ipsme -> main.cpp + Interface_App.hpp + 2 responder(s) [merge-on-gen]
main -> main.cpp [unchanged]
iface -> Interface_App.hpp [unchanged]
bridge -> IPSME_Bridge.hpp [merged] [base v3.1.28 -> v3.1.29]
resp -> Responder_Discovery.hpp [CONFLICTS(1) — resolve markers]
-
created: first run, no output yet. Output and base are written together, identical. -
unchanged: the generator’s output equals the base, so your file is left alone. On a generator version bump the base is re-stamped, shown as[base vX → vY]. -
merged: the template changed since the base and the change folded into your file cleanly. The base advanced. -
CONFLICTS(n): innregions both you and the generator changed the same lines. Resolve the markers as with any git conflict; the base has already advanced, so the next run reportsunchanged. -
seeded: only with--seed-bases, see Adopting a scaffold file that already exists.
Reading a conflict
The markers are git’s diff3 style (zdiff3 with git 2.35 or newer, which keeps lines common to both sides out of
the conflict), so a conflict shows three sections, with the base in the middle:
<<<<<<< yours (edited) <- on disk now (base + your edits)
...A...
||||||| base (generated) <- the last pristine generated skeleton (the common ancestor)
...B...
=======
...C... <- the freshly generated output
>>>>>>> generated (new)
Resolve by comparing each side with the base B in the middle:
-
A equals B: you did not touch this region, only the generator did. Take C.
-
C equals B: the generator did not change it, only you did. Keep A.
-
A and C both differ from B: both of you changed it. Merge by hand.
That middle section is why diff3 is worth the extra markers: without it you would see only your version against the new one and have to guess who changed what.
Adopting a scaffold file that already exists
The invariant is strict: output present implies a base exists, otherwise the run stops with an error. The generator
will not fabricate an ancestor under a file that never descended from one, because the first merge after that would
silently duplicate or corrupt it. So an existing hand-written bridge is not retrofitted with a base; you reach the
managed state through created, then bring your logic onto the generated skeleton:
cp src/IPSME/IPSME_Bridge.hpp /tmp/IPSME_Bridge.mine.hpp # 1. preserve your current bridge
rm src/IPSME/IPSME_Bridge.hpp # 2. remove it so gen takes the `created` path
./cpp-iface-gen.git/build/Release/iface-gen --config ifacegenconfig.json # 3. [created]: pristine bridge + its base, in sync
git difftool --no-index src/IPSME/IPSME_Bridge.hpp /tmp/IPSME_Bridge.mine.hpp # 4. 2-way merge your logic INTO the generated file
git add src/IPSME/IPSME_Bridge.hpp ifacegen-base/ # 5. commit the reconciled file AND its base
git commit -m "adopt IPSME_Bridge under iface-gen management"
After step 3 the base equals the pristine output; in step 4 you edit that file, so your bridge genuinely descends from the base and every later run is a clean 3-way merge.
| Never paste your old file over the generated stub. The base must be a true ancestor. Drop a from-scratch file on top with the stub recorded as its base, and the first template change merges as a paste-over that silently duplicates or corrupts your code. |
--seed-bases is the one-time opt-in for the reverse direction: it records a base for existing output that has none
and leaves the output untouched (status seeded). Use it only when you are certain the output already descends from
the generated skeleton, for example after a renamed target or a lost ifacegen-base/; otherwise future merges may
duplicate.