Templated Features¶
A project does not pick templates; it picks features. The pack’s features.json is the
map between the two: per target, each feature names the templates it renders and the
features it requires. Templates stay flat in one directory per target (cpp/, python/,
typescript/), and the selection is expressed one level up.
A project names its features in its kibo.toml, and
kibo-project does the rest: it resolves the closure, renders each
template, writes the embedded definitions and copies the runtime, as features.json
declares. Calling the jar by hand is covered in Command-line usage.
The catalogue¶
C++¶
The requires of the C++ features was measured, not decided: it is the #include graph of
the generated C++, interface and build unioned, since asking for a feature means compiling it.
Feature |
What it gives |
Requires |
Templates |
|---|---|---|---|
|
The type system and everything that cannot be pulled apart from it. Data, Codec, Model and AnyConcept include one another in both directions; there is no cut. |
— |
|
|
The name of every field, as a constant ( |
— |
|
|
The path of every field, built once from its name ( |
|
|
|
The attachments a unit declares, in a |
|
|
|
The attachments a unit declares, in a Commit database: |
|
|
|
The attachments a unit declares, reading only: |
|
|
|
A function pool, host side: the functions the application implements, and the pool that registers them, for its embedded Python or a service. |
|
|
|
A function pool, client side: |
|
|
|
An attachment function pool, host side: the functions over a Commit state the application implements, and the pool that registers them. |
|
|
|
An attachment function pool, client side: |
|
|
Every C++ file lands in the target’s output directory, flat. A file rendered once per DSM
namespace is named <infrastructure>_<unit>_<template>, a file rendered once for the model
<infrastructure>_<template>, a file rendered once per pool <infrastructure>_<pool>_<template>.
For a model named features with one namespace Demo, one function pool Tools and one
attachment function pool PlayerModel:
Feature |
Files |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Python¶
Feature |
What it gives |
Requires |
Templates |
|---|---|---|---|
|
The package: its entry point, the types each namespace declares, and the container bindings the model mentions. |
— |
|
|
The name of every field, as a constant ( |
— |
|
|
The path of every field, built once from its name ( |
|
|
|
The attachments a unit declares, in a |
|
|
|
The attachments a unit declares, in a Commit database: |
|
|
|
The attachments a unit declares, reading only: |
|
|
|
A function pool in the host’s embedded Python: |
|
|
|
A function pool, client side: |
|
|
|
An attachment function pool in the host’s embedded Python: |
|
|
|
An attachment function pool, client side: |
|
|
|
What makes the package installable, and therefore typed. |
|
|
The package is the directory <output>/<infrastructure>/. Base renders __init__.py at
its root (definitions(), the units) and in each unit, <unit>/data.py and containers.py;
Fields, Paths and the three attachment usages render <unit>/fields.py,
<unit>/paths.py, <unit>/database_attachments.py, <unit>/commit_attachments.py and
<unit>/reads.py, which a unit’s __init__.py does not import. A pool is a subpackage,
<pool>/__init__.py, which re-exports nothing, with a module per side: <pool>/embedded.py
(Pool, the Pool and AttachmentPool features) and <pool>/remote.py (Remote,
PoolRemote and AttachmentPoolRemote). Wheel is the one feature whose two files do not land
beside the modules: py.typed goes inside the package, pyproject.toml one level up, at the
target’s output. Without py.typed a type checker reports Stub file not found and every
annotation of the package is invisible; without pyproject.toml, pip install refuses the
directory. See Python Wheels.
TypeScript¶
Feature |
What it gives |
Requires |
Templates |
|---|---|---|---|
|
The package: its entry point, the types each namespace declares, and the container bindings the model mentions. |
— |
|
|
The name of every field, as a constant. |
— |
|
|
The path of every field, built once from its name. |
|
|
|
The attachments a unit declares, in a |
|
|
|
The attachments a unit declares, in a Commit database: |
|
|
|
A function pool, client side: |
|
|
|
An attachment function pool, client side: |
|
|
|
What makes the package buildable and installable: |
|
|
The sources are the directory <output>/src/. Base renders index.ts at its root and in
each unit, definitions.ts, <unit>/data.ts and containers.ts; Fields, Paths and the
two attachment usages render <unit>/fields.ts, <unit>/paths.ts,
<unit>/database_attachments.ts and <unit>/commit_attachments.ts, which a unit’s index.ts
does not export. No host embeds Node, so TypeScript has the client side only, and no Reads:
PoolRemote renders pools.ts (every function pool, one namespace each) and
<pool>/index.ts, <pool>/remote.ts (Remote); AttachmentPoolRemote the same with
attachment_pools.ts. Package renders package.json and tsconfig.json at the
target’s output, the package root. See npm Packages.
Resolving a selection¶
resolve.py, beside features.json, walks requires depth first and returns the closure,
dependencies first, then the templates of that closure, deduplicated, in order. A name the
target does not declare is refused with the list of those it does; a cycle is refused.
$ ./resolve.py cpp CommitAttachments
features : Base Fields Paths CommitAttachments
data.cpp.stg
data.hpp.stg
codec.cpp.stg
codec.hpp.stg
model.cpp.stg
model.hpp.stg
any_concept.cpp.stg
any_concept.hpp.stg
fields.hpp.stg
paths.cpp.stg
paths.hpp.stg
commit_attachments.cpp.stg
commit_attachments.hpp.stg
From Python, resolve.closure("cpp", ["CommitAttachments"]) gives the feature names and
resolve.templates("cpp", ["CommitAttachments"]) the template paths. kibo-project does the same
walk, and kibo_project.py plan shows it, with where each template lands — sources for the
directory the templates render into, root for the target’s output itself:
[python] python -n features -> /…/python
features: Base, DatabaseAttachments, Wheel
python/__init__.py.stg sources
python/data.py.stg sources
python/containers.py.stg sources
python/database_attachments.py.stg sources
python/pyproject.toml.stg root
python/py.typed.stg sources
[typescript] typescript -n features -> /…/typescript
features: Base, Fields, Paths, CommitAttachments, Package
typescript/index.ts.stg sources
typescript/definitions.ts.stg sources
typescript/data.ts.stg sources
typescript/containers.ts.stg sources
typescript/fields.ts.stg sources
typescript/paths.ts.stg sources
typescript/commit_attachments.ts.stg sources
typescript/package.json.stg root
typescript/tsconfig.json.stg root
What sits beside the templates¶
Besides the features, features.json declares what a tool driving kibo needs to know of the
pack, so that the tool carries no knowledge of its own:
generator.kibo— the oldest kibo exposing the Template Model the templates consume,>=2.1.0. A floor: a later kibo exposing the same Template Model renders them too.layout, per target — where the templates render, below the target’s output (sources), which templates render at the output itself (root), theruntimecopied beside the sources, and the embedded definitions (resources) with their encoding.reserved, per target and per family of names — the names the pack’s own code takes: the members every generated class inherits from the runtime’s proxy, which a field would mask (wrap_value,copy,typein Python;wrapValue,equals,toJSONin TypeScript), and the modules at the package’s root, which a namespace or a pool would replace (containers,definitions,resources,pools, and in TypeScriptattachment_poolsandindex). A DSM name meeting one stops the generation, saying how to spell it otherwise for that target — kibo-project.validation, per target — the checks run once a target is written. C++ needs none: its compiler refuses invalid code and says why. Python and TypeScript can run code a name has broken without a word, so Python is imported, every structure built and the package checked withmypy --strict; TypeScript is checked withtsc --noEmit. A check whose tool is not found fails.
Target |
|
|
|
|
|---|---|---|---|---|
|
the output |
— |
— |
|
|
|
|
|
|
|
|
|
|
|
The runtime and the embedded definitions go with a feature: "with": "Base" for both, in
every target. They are written beside the templates of the feature that reads them, so a
target that does not render Base — the client side of a pool, rendered with
with_requirements = false — gets neither.
The runtime belongs to the pack, not to dsviper: the proxy base, the registry that wraps and
unwraps values, the container views (Sequence, Mapping, Ordered, Optional, Variant)
and AttachmentBase, the base every generated attachment derives from, holding its runtime
id and descriptor, written once and copied into every generated package
(_codegen/ in Python: proxy.py, container.py, attachment.py; src/_codegen/ in
TypeScript: proxy.ts, container.ts, attachment.ts, registry.ts, value.ts). It
versions with the templates that call it. Python names the optional’s view Option: an
annotation Optional[D] reads as typing.Optional, a value or None, where it is a box opened
with unwrap(). The declared classes keep their name in both languages (Optional_of_…). The embedded definitions are decoded once by the
package’s definitions(), or by codec::definitions() in C++.
A project’s own features¶
A project can add its features to the pack’s selection: a manifest of the same shape as
features.json, whose templates sit beside it (<manifest dir>/<language>/<template>), and
whose features may require the pack’s. A feature name the pack already declares is refused.
{
"cpp": {
"Report": {
"doc": "A report of every structure the model declares.",
"templates": ["report.md.stg"],
"requires": ["Fields"]
}
}
}
resolve.py takes it with --with (repeatable), and from Python with
extra=[...]:
$ ./resolve.py cpp Report --with my-templates/features.json
features : Fields Report
fields.cpp.stg
fields.hpp.stg
report.md.stg
In a project, kibo-project reads the manifests listed in [generator] manifests, paths
relative to the project file:
[generator]
templates = "2"
manifests = ["my-templates/features.json"]
[target.cpp]
features = ["Report"]
output = "report"
A third-party template writes its own header: its licence and the runtime it needs are its author’s to state. The templates such a manifest names read the Template Model, as the pack’s do.
Picking a feature set¶
A selection is a target of the project’s kibo.toml; name the features you want and the
closure follows. This project renders the C++ with the Commit attachments and a function
pool on both sides, the Python package as an installable wheel over a Database, and the
TypeScript package with its manifest and a pool’s client:
[project]
definitions = "definitions"
infrastructure = "features"
[generator]
templates = "2"
[target.cpp]
features = ["CommitAttachments", "Pool", "PoolRemote"]
output = "cpp/generated"
[target.python]
features = ["DatabaseAttachments", "Wheel"]
output = "python"
[target.typescript]
features = ["Base", "PoolRemote", "Package"]
output = "typescript"
Common selections:
Use |
Target |
Features |
|---|---|---|
Types and the codec only |
|
|
Typed documents in a |
|
|
Typed documents in a Commit database |
|
|
A library that reads documents from either database |
|
|
Field names for code that uses the dynamic API |
|
|
A service: server and client in one binary |
|
|
A client of a service, in another binary |
|
|
Python inside a host application that embeds it |
|
|
An installable Python package |
|
a usage, |
A buildable TypeScript package |
|
a usage, |
Several targets of one language — a server and its client, say — name each target for what it
produces and state its language; see the project file.