.. _rigs4zephyr_reference_commands: Commands ========== Two things exist for a person: building a rig, and ``west rigs``, which answers questions about rigs without building. The :term:`expander` itself (``rigc``) is run *by* ``cmake`` during configure, never directly by a person — its argument list is documented here anyway, because a failing configure prints it and ``build/rig/rerun-expand.sh`` re-runs it. .. contents:: :local: :depth: 1 Building a rig ---------------- .. code-block:: console $ west build -b -- -DRIG= Building a rig is not a command of its own — it is an ordinary ``west build`` (or a bare ``cmake -S ... -B ...``) invocation, one flag added. ``-DRIG=`` resolves ```` — either a persisted rig, named by its ``rig.yml`` ``rig.name`` field, or a :term:`shield template` promoted to a rig of one instance (see `Promotion targets`_ for the grammar) — into a devicetree overlay during configure. Every other ``west build``/cmake option works unchanged alongside it. Two rules this acquires: - **The board is required, and comes from** ``-b``/``--board`` (or ``-DBOARD=`` for a bare ``cmake`` invocation). A rig names a topology; no rig file declares a board, so there is nothing to fall back to and a rig build without a board is a configure-time error that says so. - ``--shield`` **must not be given.** A rig's own instances are the sole source of shields for a rig build; the combination is a fatal configure error. A ``SHIELD`` still cached in a build directory from an earlier non-rig configure trips it too — pristine the directory (``-p always``) when switching one to ``-DRIG``. The ``$ZEPHYR_BASE`` a rig build resolves against, and everything else about the build, is whatever an ordinary ``west build``/``cmake`` invocation would already use — nothing about ``-DRIG`` changes it. ``west rigs`` --------------- .. code-block:: console $ west rigs [-f FORMAT] [-n NAME_RE] $ west rigs --boards-for TARGET $ west rigs --explain TARGET With no arguments, lists the name of every rig discovered under the board roots of every Zephyr module that declares one — ``bridle`` does, so its own rigs are found with no path given. ``-f, --format FORMAT`` A Python format string, one line per rig. Keys: ``{name}`` (the rig's identity), ``{dir}`` (the directory holding its two files), ``{revisions}`` and ``{variants}`` (declared axis values, comma-separated, empty when the rig declares none). Default: ``{name}``. There is no ``{board}`` key. A rig declares no board, so a listing has nothing of its own to print — ``--boards-for`` is the question that replaces it. ``-n, --name NAME_RE`` List only rigs whose name matches this regular expression. ``--board-root DIR`` Add a board root to the scan. Repeatable. Rarely needed: module-declared roots are scanned already. ``--boards-for TARGET`` Instead of listing, print every board whose typed sockets satisfy ``TARGET`` — mating, bus-subset exposure, alias-aware reference resolution and stackability, censused from board sources with no cmake configure. ``TARGET`` resolves against both namespaces (a rig, or a :term:`promoted shield`), so *"which boards can host this module?"* is askable before any rig exists for it: .. code-block:: console $ west rigs --boards-for adafruit_data_logger frdm_k64f/mk64f12/rig nucleo_f401re/stm32f401xe/rig .. note:: This worked example comes from btr-shields, the harness repository the rig model comes from — see the note on :ref:`rigs4zephyr_tutorials_build-a-rig-that-exists`. It will not reproduce in bridle's own corpus: bridle already carries an unrelated, non-rig ``adafruit_data_logger`` shield (real hardware, no ``template: true``), and none of bridle's own boards declare their sockets through a ``board.yml`` ``extend:``/``variants`` board rig-extension — the shape this census reads — so ``--boards-for`` currently answers empty for any target here. Bridle's own two rigs (``lotus_buttons``, ``lotus_pwm_led``) are demonstrated end to end in :ref:`rigs4zephyr_tutorials_build-a-rig-that-exists` instead. **This is not a promise that the rig builds on a listed board.** GPIO position routing, chip-select allocation, address domains and net analysis all need the board's real devicetree, which this census does not read. It answers *cannot possibly work* with certainty, and *might work* otherwise. ``--explain TARGET`` Instead of listing, print the two files ``TARGET`` stands for — verbatim from disk for a persisted rig, or the synthesized pair a shield name desugars to when the target names a shield: .. code-block:: console $ west rigs --explain adafruit_data_logger # rig.yml rig: name: adafruit_data_logger # adafruit_data_logger.yml instances: - name: adafruit_data_logger shield: adafruit_data_logger Printed *as authored*: no axis is resolved into the text, so a variant's fragment is not folded in and a revision is not selected. This is the copy-paste source for turning a promoted shield into a checked-in rig. ``--rig TARGET`` Accepted and **without effect** on this command. It belongs to the standalone resolver ``cmake`` calls, which shares its argument definitions with this command; use ``--explain`` to resolve a target here. ``--boards-for`` and ``--explain`` each short-circuit the listing, so ``-f`` and ``-n`` do not apply to them. Both exit non-zero, with a diagnostic on stderr, on a target that does not resolve. Promotion targets ------------------- A ``TARGET`` — the value of ``--rig``, ``-DRIG``, ``--boards-for`` and ``--explain`` alike — is either the name of a persisted rig, or a **promoted shield**: a shield name (optionally a ``;``-separated list of them), each with its own optional revision and ``:``-separated assignments (``socket=``, ``socket.=``, ``config.