get_build_info

Return the detail of ONE build: its identity, its health, its memory map and its defines.

Read-only with the two exceptions that get_project_status also has: it removes the marker of a missing build when it finds that build again, and a reindex.pid or a reindex.pending of a process that no longer runs. It spawns no subprocess. On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. get_project_status lists the builds in builds. Without the arguments the answer is an error that lists the builds. A project of one build needs no selector.

The health fields (status, reindex_state, reindex_needed, reindex_reasons, index_message, modified_files_count and the others) have the meaning that get_project_status gives them, for this build only. The version fields (update_notice, a restart after an upgrade) are in get_project_status.

About memory: origin and length hold the expression the script writes, thus they differ by platform — an mbed script writes 0xefe00 and a Zephyr script writes ((673792) - 0xe6). origin_value and length_value hold the number, and both are None for an expression that names a symbol, such as ORIGIN(RAM) + LENGTH(RAM). A name that the link command defines with --defsym counts as a number: the STM32 Arduino core writes LENGTH = LD_MAX_DATA_SIZE and gets length_value 98304. The end of a region is origin_value + length_value.

memory is empty for a build system that records no linker script, such as Keil or IAR. A PlatformIO project records its link only in fw-context index --build: SCons writes no file with the link command, thus the build asks pio run -t envdump. An empty list for PlatformIO means that no build recorded the link yet, and fw-context index --build is the step. An empty list means "not recorded", never "no memory".

defines holds only the names that EVERY translation unit of the build carries with the same value, so the tool never shows the defines of one file as the defines of the build. defines_varying counts the names left out, thus a name absent from defines is either not defined at all or not defined everywhere. Measured on the Mbed project, 27 names are in all 881 units and 59 in only some, where the three assembly files get a shorter set.

This is the configuration the BUILD states, not every macro the preprocessor saw. The second is three orders of magnitude larger — 27800 distinct names on the STM32 project — and almost all of it comes from the headers and the compiler. A Zephyr build keeps its real configuration in autoconf.h (740 CONFIG_* names) and passes few -D flags, so defines says little there and a great deal on an mbed build, where it holds APPLICATION_ADDR, APPLICATION_SIZE, and CMSIS_VECTAB_VIRTUAL.

Args: project_root: Project root directory. Auto-detected from CWD if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name. fast: When True (default), the header check reuses the cached manifest hashes. False recomputes them.

Returns: dict: {variant, image, board, config_hash, project_id, project_root, build_system, compile_commands, indexed_at (str — UTC), first_indexed_at, symbol_count, file_count, reference_count, modified_files_count, header_affected_tus, manifest_verification, analysis, description, vendor_paths, project_paths, effective_vendor_patterns (list[str] — the SQL LIKE patterns that this build really used to mark vendor code, for example ["mbed-os/%"]; empty when the manifest cannot be read. The two lists above hold what the config asks for, this one what the index did), status, reindex_state (str or None — see get_project_status), reindex_needed, reindex_reasons, stale, index_message, entry_point (str — the ENTRY() of the linker script of the build, empty when no script names one), memory (list[dict] — the MEMORY regions of the build: {name, attributes, origin, length, origin_value, length_value, file_path, line}), defines (dict — the -D flags of the build), defines_varying (int), bg_reindex_running (bool), reindex_progress (str or None), vec_available (bool), vec_error (str, optional), _warning (str, optional), client_restart_required (bool, optional), client_restart_reason (str, optional)}

A refusal of the selector, or an index with no build config, gives
a dict that holds ``error`` alone.  A project that is not
initialized, that has no index, or whose config file cannot be used
(``"config_error"``) gets the answer of ``get_project_status``.
``config_warnings`` (a list) comes as in ``get_project_status``.