get_file_map
Get a structural map of all C/C++ symbols in a file, grouped by kind. See functions, classes, and enums at a glance before reading large files.
Instructions
Fast structural map of all C/C++ symbols in a file grouped by kind — libclang-powered table of contents. Like a table of contents before reading a chapter: see what functions, classes, and enums a file defines at a glance.
The index decides which file a path may reach: a path that no file of this build answers for is refused, and a header of the SDK that the build compiles is reachable like any file of the application.
Pass a path relative to the project root (src/main.cpp) or just the
filename (main.cpp). Returns symbols keyed by kind (function, method,
class, struct, enum, ...). Each kind has count (total) and items (first N,
default 30). Set max_per_kind=0 for unlimited, signatures=true for full sigs.
Enum constants (enum_constant) are grouped into subgroups by
parent enum. Each subgroup has name, count, and constants
(list of {name, qualified_name, line, enum_value}). The subgroup
count reflects the real total even when max_per_kind limits the
constants list.
For detailed symbol information use get_symbol_context or
lookup_symbol.
Read-only. No side effects. Use before reading a large file to orient yourself — see what functions, classes, and enums it defines.
Args: file_path: Path relative to project root, or just the filename. project_root: Project directory. Auto-detected 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. signatures: Include full function signatures. Default: False. max_per_kind: Max items per kind group (default 30, 0 = unlimited). variant: Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. image: Sysbuild image within the variant. Required when the variant holds several: each image is a separate program.
Returns: dict: {file, total_symbols, symbols: {kind: {count, items[], subgroups?[]}}}
Each item holds ``name``, ``qualified_name``, and ``line``, plus
``end_line`` when the symbol is a definition. The two line numbers
are the extent, thus ``file:line-end_line`` is the citation.
On failure the dict holds only ``error`` with the reason.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| project | No | 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 | No | Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. | |
| file_path | Yes | Path to source file — relative to project root or just filename. | |
| signatures | No | Include full function signatures in output. | |
| max_per_kind | No | Max items per symbol kind group (default 30, 0 = unlimited). | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |