Configuration — just-makeit.toml¶

Every project scaffolded by just-makeit new contains a just-makeit.toml file at the project root. It is the single source of truth for the project's structure: what objects exist, what state they carry, what types and flags were used, and how the build system is configured.

just-makeit reads this file before every object, add, method, property, and script command — you never need to pass the project name or repeat earlier choices on the command line.

What is stored¶

A lifted --impl body is stored in the manifest (as impl, create_impl, reset_impl, destroy_impl, …), so jm regenerate and jm apply can re-stamp it. Edits you make afterwards to the sacred _core.c are yours and live only in source — the manifest holds the original lift, not your later changes.

Project layout and schema¶

After just-makeit new my_project followed by just-makeit object engine. just-makeit.toml sits at the project root — every command reads it from there, no flags required.

```
my_project/
├── just-makeit.toml
├── CMakeLists.txt
├── Makefile
├── pyproject.toml
├── cmake/
│   ├── my_project-config.cmake.in
│   └── my-project.pc.in
├── native/
│   ├── inc/
│   │   ├── my_project.h
│   │   ├── clib_common.h
│   │   ├── pyex_common.h
│   │   └── engine/
│   │       └── engine_core.h
│   ├── src/
│   │   ├── my_project_lib.c
│   │   └── engine/
│   │       ├── engine_core.c
│   │       ├── engine_ext.c
│   │       └── CMakeLists.txt
│   ├── tests/
│   │   └── test_engine_core.c
│   └── benchmarks/
│       └── bench_engine_core.c
└── src/
    └── my_project/
        ├── __init__.py
        ├── engine.pyi
        ├── tests/
        │   └── test_engine.py
        └── benchmarks/
            └── bench_engine.py
```

```toml
[project]
name             = "my_project"
version          = "0.1.0"
build            = "cmake"
perf             = "false"
pytest           = "false"
pytest_benchmark = "false"

# One section per object, named after the object.
[engine]
arg_type    = "float _Complex"
return_type = "float _Complex"
mutable     = "false"
no_state    = "false"
no_step     = "false"

# One entry per --state declaration.
[[engine.state]]
name    = "gain"
type    = "double"
default = "1.0"

# One entry per --init-param.
[[engine.init_params]]
name    = "order"
type    = "int"
default = "4"

# One entry per --array-arg.
[[engine.array_args]]
name = "coeffs"
type = "float32"

# One entry per `just-makeit method`.
[[engine.methods]]
name        = "normalize"
return_type = "void"
params      = [{name = "scale", type = "double"}]

# One entry per `just-makeit property`.
[[engine.properties]]
name     = "peak"
type     = "double"
writable = true
field    = true

# Module subpackage, named after the module.
[module.filter]
objects = ["fir", "biquad"]

[[module.filter.functions]]
name        = "design_lowpass"
return_type = "void"
doc         = "Compute FIR coefficients for a lowpass filter."
params      = [{name = "cutoff", type = "double"}]

[fir]
arg_type    = "float _Complex"
return_type = "float _Complex"
mutable     = "false"
no_state    = "false"
no_step     = "false"

[[fir.state]]
name    = "coeffs"
type    = "float[16]"
default = "0.0f"
```

Module dependencies & external libraries¶

jm apply regenerates each module's CMakeLists.txt, so dependency wiring must be declared in the manifest — a hand-edited link line is clobbered on the next apply. Four keys cover every case; none of them require post-apply patching, and jm status --check stays clean with no allowlist.

extra_link_libs — external and sibling libraries¶

[module.source]
objects = ["nco", "lo", "awgn"]
# system libs and generator expressions are fine:
extra_link_libs = ["$<$<PLATFORM_ID:Linux>:mvec>", "${MY_STATIC_LIB}", "m"]

[module.wfm]
objects = ["waveform_engine"]
# link sibling cores from other modules by their <obj>_core target name:
extra_link_libs = ["source_core", "lfsr_core", "m"]

Set it from the CLI with jm module <m> --extra-link-libs TARGET (repeatable).

depends_on — link and include a dependency¶

When an object actually calls another object's C API (not just links it), use depends_on on the object, not the module. It links the dependency's core and auto-includes its header, so opaque-typed fields compile:

[waveform_engine]
depends_on = ["source", "lfsr"]   # links source_core/lfsr_core + includes both headers

Prefer this over naming the cores in extra_link_libs whenever the dependency's types or functions are referenced from your _core.c.

c_deps — hand-written C support directories¶

For a pure-C directory (object libraries, vendored code) that has no Python binding but that modules link against:

[project]
c_deps = ["io", "vendor_dsp"]   # add_subdirectory(native/src/io), …

Each listed dir owns its CMakeLists.txt (define add_library(<name>_core …), tests, etc.); modules then link it via extra_link_libs = ["io_core", …]. CLI: jm new --c-dep DIR (repeatable).

no_generate — hand-written extension modules¶

For a module whose binding is written by hand (e.g. a free-function API over an opaque capsule):

[module.io]
no_generate = "true"

jm apply emits the add_subdirectory(native/src/io) and otherwise leaves the module untouched — io_ext.c, io.pyi, and its CMakeLists.txt are yours. Pair with reexports on a sibling module to fold its symbols into a generated package __init__.py.

Worked example: three interdependent modules + a C support dir¶

[project]
c_deps = ["io"]                    # hand-written native/src/io (io_core, …)

[module.source]
objects = ["source", "lfsr"]
extra_link_libs = ["${DOPPLER_STATIC_LIBRARY}", "io_core", "m"]

[module.wfm]
objects = ["waveform_engine"]
extra_link_libs = ["source_core", "lfsr_core", "m"]
# …or, if waveform_engine calls source/lfsr APIs, drop those two libs and use:
#   [waveform_engine]
#   depends_on = ["source", "lfsr"]

This is exactly the wiring doppler uses (c_deps = ["hbdecim", "resamp", "wfmcompose"]; [module.ddc] extra_link_libs = ["lo_core", …]; [synth] depends_on = ["lo", "awgn", "pn"]) — fully declarative, idempotent across jm apply.

Complete CLI ↔ TOML mapping¶

Every TOML key the schema accepts maps to a CLI flag. This is the Phase 2 acceptance bar from the implementation plan: no feature should require a TOML edit before it can be used.

Status legend: ✅ on main · 🟡 CLI flag pending (TOML works today).

CLI and TOML are both first-class authoring paths. The CLI is the recommended way (presets, validators, errors); TOML editing is a fully supported alternative for power users or for knobs the CLI hasn't yet exposed. The 🟡 rows below are TOML-only today and are tracked for CLI parity — but unlike previous phrasing, this is no longer "by design"; the goal is parity.

[project] keys¶

[<component>] keys¶

[[<component>.state]] entries¶

The three rare modifiers (opaque, no_ctor, roles) currently require editing just-makeit.toml directly. CLI flags are pending (syntax under discussion: --state name:type:opaque, --state name:type:no-ctor, --state name:type:role=config). Until those land, hand-editing the manifest is the workaround.

[[<component>.init_params]] entries¶

[[<component>.methods]] entries¶

[[<component>.properties]] entries¶

[<component>] lifecycle impl bodies¶

The --impl file::N:M form lifts source lines N..M (inclusive, 1-based) instead of a named function body; it composes with the slot prefixes (create::file::N:M) and out-of-bounds ranges error cleanly.

[module.<name>] keys¶

reexports folds names from a sibling extension (typically a no_generate module whose binding/.pyi are hand-written) into this module's generated __init__.py — both the import block and __all__ — so the re-export glue regenerates from the manifest instead of being a hand-edit jm apply would clobber. Output is single-line, matching the rest of the package.

[[module.<name>.functions]] entries¶

Counts¶

• ✅ on main: ~66 keys (every common path; Phase 2 stack shipped in 0.13.23)
• 🟡 CLI flag pending: 15 keys — rare modifiers (opaque, no_ctor, roles, buf_field/expr property variants, init_post_parse_impl, default_raw/real_type init-param details, no_generate module, max_results / max_results_param). These are foot-guns to close: TOML is the persistence layer, not the user interface. Each will get a CLI flag in Phase 3.

Phase 2 acceptance bar — "every TOML field has a 'Reachable via CLI' column ✓" — is met for the common path. The remaining 🟡 rows are tracked Phase 3 work, not by-design exceptions.

Schema reference¶

[project]¶

[<object>]¶

One section per standalone object or module-member object. The section name is whatever you passed to just-makeit object <name>.

[[<object>.state]]¶

One entry per --state declaration.

[[<object>.array_args]]¶

Fixed-size array constructor arguments added with --array-arg.

[[<object>.init_params]]¶

Constructor-only parameters added with --init-param (no getter/setter, no reset). Same name / type / default keys as state.

[[<object>.methods]]¶

One entry per just-makeit method call.

nogil wraps the pure-C kernel of a variable_output execute method in Py_BEGIN_ALLOW_THREADS / Py_END_ALLOW_THREADS (numpy accessors hoisted out first), so a thread-per-shard worker — one object + output buffer per thread — scales across cores instead of serialising on the GIL. Opt-in: it is sound only when the object is not shared across threads concurrently (one object per stream).

[[<object>.properties]]¶

One entry per just-makeit property call.

[module.<name>]¶

[[module.<name>.functions]]¶

One entry per just-makeit function call.

Inspecting config¶

just-makeit config

Prints a summary of the project and every object's state variables:

project:  my_project
version:  0.1.0

engine:
  gain:          double = 1.0
  center_freq:   double = 1000.0

To update the version:

just-makeit config version 0.2.0

Reconstructing a project¶

just-makeit script reads just-makeit.toml and prints the exact sequence of CLI commands that would recreate the project from scratch:

just-makeit script          # print to stdout
just-makeit script | sh     # pipe directly into a shell to rebuild

Example output for a two-object project:

#!/usr/bin/env sh
# Reconstructed from just-makeit.toml

just-makeit new my_project

cd my_project

just-makeit object engine \
    --state "gain:double:1.0" \
    --state "center_freq:double:1000.0"

just-makeit object detector \
    --arg-type "float _Complex" \
    --state "threshold:float:0.5f"

When is this useful?¶

Moving a project. Copy just-makeit.toml to a new machine, run just-makeit script | sh, and the full scaffold is regenerated. Your own code (business logic in *_core.c, tests, customisations) travels with the project directory as normal; the script just recreates the generated boilerplate if it was ever lost or corrupted.

Starting fresh after a breaking change. If a just-makeit update changes generated file layouts, just-makeit script | sh in an empty directory produces a clean scaffold at the current version.

Documentation / reproducibility. Commit just-makeit.toml to record exactly how the project was built. Anyone can reproduce the generated structure without needing to remember the original command sequence.

Editing TOML by hand¶

The file is plain TOML — you can edit it directly. just-makeit will read your changes on the next command. The rules:

• Order matters for state variables: [[<object>.state]] entries are emitted in the order they appear, which controls constructor argument order in both C and Python.
• Keys must come before sub-table arrays: all scalar keys on an object section (impl, create_impl, reset_impl, destroy_impl, arg_type, mutable, …) must appear before the first [[<object>.state]] or [[<object>.methods]] entry. TOML parses bare keys after an array-of-tables header as part of that entry, not the parent section, so keys placed after a [[…]] line are silently dropped by the parser.
• Editing a signature in TOML (removing a state variable, changing a method's return type) propagates to the glue files (_ext.c, .pyi, CMakeLists.txt) and the public declarations in _core.h on the next command, but the sacred _core.c body is left as you wrote it. Run jm regenerate <obj> to rebuild that component cleanly from the manifest (this discards the _core.c body — git stash first).
• Don't rename the file — just-makeit always looks for just-makeit.toml at the project root.