CLI

Two command-line tools ship with ifw-iptool: ifwIpToolCompiler and ifwIpToolValidator. This chapter starts with a five-step Quickstart against the bundled TSTINS example, then documents each tool in detail.

Quickstart

These steps take you from a freshly-installed ifw-iptool to a validated IP and a Sequencer-loadable sample OBD. They use the bundled TSTINS example as input.

Prerequisites

  • ifw-iptool has been built and installed (waf install), so ifwIpToolCompiler and ifwIpToolValidator are on $PATH and the IpTool schema + bundled example are under $INTROOT/resource/.

  • The CII Config Service Python bindings (elt.configng) are available — standard CII install.

  • A clone of the ifw-iptool repository (so this manual’s commands match the repo paths). All output goes to a tmp/ directory under the repo root; choose a different -o if you prefer.

Steps

  1. Open a terminal at the repository root (the directory containing wscript and the lib/ tree):

    cd <path-to-clone>/ifw-iptool

  2. Confirm CFGPATH includes $INTROOT/resource. After waf install, the IpTool schema, the OTTO ip_schemata, and the bundled TSTINS example all live under $INTROOT/resource/ and the CII Config Service finds them automatically if CFGPATH is set up the standard way:

    echo "$CFGPATH"   # should contain $INTROOT/resource

    If it does not, add it:

    export CFGPATH="$INTROOT/resource:$CFGPATH"

    Working without an install: if you haven’t run waf install, point CFGPATH at the source tree instead:

    export CFGPATH="$PWD/lib/resource:$CFGPATH"

  3. Compile the bundled TSTINS example. The TSTINS sources live in the standalone example/tstins/ project:

    ifwIpToolCompiler \
    -f example/tstins/ipt/resource/ipt/tstins/tstins.meta.ipt.yaml \
       example/tstins/ipt/resource/ipt/tstins/*.tpl.ipt.yaml \
    -o tmp

    Or build the example the standalone way (waf configure / build / install / validate-ip) from example/tstins/:

    cd example/tstins && waf configure build install

    On success, the compiler writes tmp/resource/ip/tstins/ip/ (the IP) and tmp/ipt/tstins/ (the demo aids) and exits with status 0. If it fails, the error message names the offending source file and instance — start there.

  4. Inspect the result. The compiler emits two trees:

    The IP itself, consumed by the preparation tools:

    tmp/resource/ip/tstins/ip/
    format.json
    templates.json
    constraints.json
    checklist.json
    laser.json
    templates/<tpl>.json    (one Template Signature per template)
tmp/resource/doc/tstins/ip/
    tstins_template_manual.tex          (prose skeleton; pass --keep-manual-prose to preserve)
    tstins_template_manual_data.tex     (auto-generated tables)

    The demo aids, NOT part of the IP:

    tmp/ipt/tstins/
    obd/<tpl>.obd.json                          (one sample OBD per template)
    seq/tstins/stubs/<tpl>.py                   (one Sequencer stub per template)

  5. Validate the generated IP against the OTTO IP schemata:

    ifwIpToolValidator -i tmp/resource/ip/tstins/ip

    A clean run prints OK and exits with status 0. Any schema violation is reported with the artefact and JSON path of the offending value.

  6. (optional) Load a sample OBD in the Sequencer. The generated stubs are addressed via PYTHONPATH; nothing else needs to be added to CFGPATH:

    export PYTHONPATH="$PWD/tmp/ipt/tstins/seq:$PYTHONPATH"
seqtool gui &
# In the GUI: ob tmp/ipt/tstins/obd/tstins_img_acq.obd.json

    The Sequencer imports each template’s stub as tstins.stubs.<templateName>; that package lives under tmp/ipt/tstins/seq/ (as tstins/stubs/<templateName>.py) which is what we put on PYTHONPATH.

  7. (automatic) Template Reference Manual PDF. The compiler builds the manual PDF by default (running pdflatex, falling back to latexmk). Step 3 already produced tmp/resource/doc/tstins/ip/tstins_template_manual.pdf alongside the .tex files. To skip the PDF build (e.g. on a machine without LaTeX installed), pass --omit-pdf:

    ifwIpToolCompiler \
    -f example/tstins/ipt/resource/ipt/tstins/tstins.meta.ipt.yaml \
       example/tstins/ipt/resource/ipt/tstins/*.tpl.ipt.yaml \
    -o tmp \
    --omit-pdf

    PDF-build failures are non-fatal: the IP is still emitted; the compiler reports any LaTeX issues at the end of its summary.

Once the Quickstart is green, replace the TSTINS sources with your own .ipt.yaml files (start by copying the TSTINS example tree and adapting it) and repeat steps 3–5.

ifwIpToolCompiler

Compiles a set of IpTool YAML sources into a complete OTTO Instrument Package and matching Sequencer Script stubs:

ifwIpToolCompiler \\
    -f <meta.ipt.yaml> <tpl.ipt.yaml> ... \\
    -o <output_base>

Options:

-f, --files

Input IPT YAML files (globs supported). Must include one *.meta.ipt.yaml (providing ip_metadata) and one or more *.tpl.ipt.yaml. *.keys.ipt.yaml files are typically included indirectly via !cfg.include and do not need to be listed on the command line.

-o, --output

Base directory. The compiler writes resource/ and seq/ trees underneath. Must NOT end with resource.

--no-seq-stubs

Skip Sequencer stub generation.

--no-manual

Skip Template Reference Manual (LaTeX) generation. By default the compiler emits both <instr>_template_manual.tex (the prose skeleton) and <instr>_template_manual_data.tex (auto-generated tables) under <output>/resource/doc/<instr>/ip/. Both files are regenerated on every compile.

--keep-manual-prose

Preserve a pre-existing <instr>_template_manual.tex instead of regenerating it. The auto-generated data file is still regenerated. Use this once the instrument team has started filling in prose sections they don’t want clobbered on subsequent compiles.

--omit-pdf

Skip the manual PDF build. By default the compiler runs pdflatex (run twice for cross-references and TOC), falling back to latexmk if pdflatex is unavailable, to produce <instr>_template_manual.pdf. Requires pdflatex or latexmk on PATH. Failures are non-fatal regardless of this flag: the IP itself is still emitted successfully; LaTeX/PDF errors are reported at the end of the compiler’s summary.

--jobs N, -j N

Worker processes for the CII Config Service load phase, which dominates compile time on real-instrument-sized projects (each input file goes through full YAML parse + typedef check + include resolution). The default (0 / auto) picks min(8, cpu_count()) and caps to the input count. Use --jobs 1 to force the original serial path (useful for debugging or on fork-unsafe environments). Tiny projects (4 or fewer inputs) always load serially regardless - the worker-pool startup overhead exceeds the gain. Workers run in spawned processes (clean CII Config Service state per worker); snapshots come back in input order so ip_metadata and per-template !cfg.merge semantics are unchanged from the serial path.

-l, --log-level

Log verbosity (DEBUG, INFO, WARN, ERROR).

Exit codes:

  • 0 — success.

  • 1 — compilation or validation error (message printed with source file and offending instance name).

  • 2 — CLI-level error (no input files, bad --output).

  • 3 — unexpected / internal error (please report as a bug).

ifwIpToolValidator

Validates a generated IP tree against the OTTO ip_schemata JSON Schemas:

ifwIpToolValidator -i <output>/resource/ip/<instr>/ip

The -i argument can also be a parent directory; the validator auto-descends to the IP. Any of these point at the same IP:

  • .../resource/ip/<instr>/ip — the IP directory itself

  • .../resource/ip/<instr> — the instrument directory

  • .../resource/ip — the parent of the instrument dir

  • .../resource — the resource root

An IP directory must contain BOTH a format.json (mandatory: IP format, instrument, version) and a templates/ subdirectory; the validator uses both as sentinels to locate the IP.

The schema root is taken from (in order) -o/--otto-ip-schemata, CFGPATH’s first entry containing schema/otto/ip_schemata, or the repo-bundled ifw-iptool/lib/resource/schema/otto/ip_schemata. -o accepts an absolute or relative path; if you point at the parent of ip_schemata/ (e.g. .../schema/otto) the validator auto-descends.

Exit codes:

  • 0 — IP is valid.

  • 1 — at least one schema violation was found.

  • 2 — CLI-level error (could not locate IP or schemas).