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 file find_package fails with "Could not find nlohmann_json". The toolchain is only needed at the configure step and is cached in build/. Under Git Bash pass it in Windows form (C:/Users/…/vcpkg.cmake), not as an MSYS /c/… path. On Linux apt install nlohmann-json3-dev works 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.h to validate a message against its embedded schema) and cpp-json-msg. Typically find_package(nlohmann_json_schema_validator CONFIG REQUIRED), link nlohmann_json_schema_validator::validator, and compile cpp-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.

Home directory and slashes in src

A 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: $HOME on 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.

  • $VAR and ${VAR} expand to that environment variable. For the home directory prefer ~ over $HOME: on Windows HOME is 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. $HOME is 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 holding ifacegenconfig.json and 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 once schema-cache is populated the src need not exist at all.

Table 1. Top level
key meaning

version

The config format version. Must be 3; a missing or different value is a hard error.

schemas

The registry: "<Name>": { "src", "sha256", "debug" }. A name is declared once and selected by targets by name.

targets

The list of outputs; each entry is described below.

Table 2. Registry entry
key meaning

src

Path to the schema (relative to the config, ~/$VAR expanded) or a URL. The C++ generator never fetches: a URL src must already be in schema-cache (populated by the npm generator, or by hand).

sha256

The pin: the plain sha256sum of the schema bytes, identical to the npm generator’s. Every schema in schemas.readonly ships a .sha256 sidecar holding exactly this value. A mismatch is a hard error. The pin is over the raw bytes, so the schema must be LF; a CRLF file is rejected.

debug

true reads the local src without verifying it (a loud warning is printed; a URL src is an error). --no-debug refuses to run if any entry has it set.

Table 3. Target
key meaning

root

Optional. A relative directory under the config dir; all of the target’s write paths (out-cpp, schema-cache, the IPSME out) are placed under it, and it names the target (ifacegen-base/<root>/). Without it a target is named target-01, target-02, … and paths resolve against the config dir as-is. No absolute paths and no ...

schema-cache

Directory for content-addressed copies of the verified schemas, <sha256>.json. Commit it: a build then needs neither network nor the src path.

out-cpp

Directory for the generated <prefix><Name>.h headers. Marks the target as a C++ target.

prefix

Literal filename prefix, default interface- → interface-Discovery.h. Concatenated as-is, so supply the trailing - yourself.

namespace

Top-level namespace of the generated classes, default iface_gen (hyphens become underscores). Never bare iface, which collides with POSIX struct iface in <net/if.h>.

delete

true prunes any header in out-cpp (and cache blob in schema-cache) that this run did not produce. Only files carrying the generator’s marker are touched.

schemas

The registry names to generate for this target. A name without a registry entry is a hard error.

IPSME

Optional. Its presence requests the editable IPSME participant scaffold: main (the entrypoint file; default main.cpp), object (the participant name; default is the stem of main), out (directory for the bridge and responders; default IPSME) and the participant’s two required axes, runtime and shape. The vocabulary is shared with the npm generator; C++ accepts exactly "runtime": "native" (an OS process) with "shape": "flat" (main plus an interface class) and rejects the rest. The third axis, the transport, is the target-level msgenv-include. The v3 shell is a hard error.

base-include, iface-include, msgenv-include, eventlog-include, eventlog-ext-include

Per-target overrides of the #include paths written into the generated files, same as the CLI flags of the same name. msgenv-include is optional: omitted, the scaffold emits a commented placeholder for the transport header.

out-npm, scope

npm targets only; see npm-iface-gen.

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>.hpp and the IPSME out directory: 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 .gitattributes in each managed directory, so an autocrlf=true checkout 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 --help
iface-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 (default main.cpp), written at the target root.

  • object: the participant’s name (default: the stem of main). 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 (default IPSME), relative to the target root.

  • msgenv-include, eventlog-include, eventlog-ext-include, base-include: the #include paths the scaffold is wired with (the transport’s IPSME_MsgEnv.h, IEventLog.hpp, the bridge’s InMemory_EventLog_ext.hpp, cpp-json-msg’s header). Each falls back to the CLI flag of the same name. msgenv-include is optional: left out, the scaffold emits a commented // #include "IPSME_MsgEnv.h" placeholder for you to point at your transport.

  • runtime and shape: 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" (a main() plus an interface class); the JavaScript runtimes and the class and component shapes are hard errors here, not silent fallbacks. Both are written into the scaffold’s headers as documentation.

    msgenv-include is the third axis, the transport: the author’s literal, never derived from runtime or the OS. The v3 shell key 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

<main> (e.g. main.cpp)

The entrypoint, a stubbed skeleton: it constructs the bridge with IPSME_Bridge::get_instance(&app, &log) and drives process_msgs().

Interface_<object>.hpp

The application interface the responders call back into. Your application implements it; the responders see nothing else of the application.

<out>/IPSME_Bridge.hpp

The singleton bridge. It #include`s and constructs one responder per protocol, exposes a `protocol_<X>() accessor for each, dispatches every incoming message along the base chain (handler_json_msg, handler_json_eff, handler_json_ack, each base confirmed once before a responder sees the message) and runs the reprocess loop in process_msgs().

<out>/Responder_<iface>.hpp

One per envelope schema. A private handler<msg>() per message, where your handling goes, plus the base dispatch handler_json_{msg,eff,ack} that validates each message with its generated validate() and forwards it typed.

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): in n regions 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 reports unchanged.

  • 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.