The initial implementation of a diagnostic tool that collects valuable
information about esp-idf and failed build to assist in investigating
reported issues.
The gathered information includes environmental variables, details about
the python virtual environment, installed tools, platform information,
project_description.json, sdkconfig, build logs, map file, linker
scripts, and others.
usage:
1) create the default report
# allow diag to create the report directory name
$ idf.py diag
# explicitly specify the report directory
$ idf.py diag --output <report directory>
2) examine the contents of the generated <report directory> for
sensitive information and add additional content to the
<report directory>
3) create report archive zip file that can be shared or attached to
the reported issue
$ idf.py diag --zip <report directory>
The tool collects information as described in what are known as recipe
files. A recipe file is a YAML file, similar to an Ansible playbook or a
GitHub action, but much more simplified. Each recipe outlines how to
gather a set of related information. For instance, the manager.yml
recipe gathers data related to the component manager. Each recipe
includes metadata such as its description, tags, and steps. Tags are
used to determine which recipes to use; by default, all built-in recipes
located in tools/idf_py_actions/diag/recipes are used. Steps consist of
a list of commands to be executed. Currently, there are four commands:
file, exec, env, and glob. For more detailed information about recipes,
their format, and commands, please refer to
tools/idf_py_actions/diag/recipes/README.md.
Recipe example for component manager:
description: IDF Component Manager information
tags: [manager, base, project]
output: manager
steps:
- name: 'IDF Component Manager'
cmds:
- exec:
cmd: 'python -m idf_component_manager version'
output: manager.ver
- file:
path: '${PROJECT_DIR}/dependencies.lock'
- glob:
# Gather all idf_component.yml files from the project directory and
# save them in directories relative to the project directory within
# the idf_component directory.
pattern: 'idf_component.yml'
recursive: true
relative: true
path: '${PROJECT_DIR}'
output: 'idf_component/'
Create report for manager
1) all recipes with manager tag
$ idf.py diag --tag manager
2) use only the manager recipe explicitly; built-in recipes can be
referenced simply by their name, but all recipes can be referenced
by their path
$ idf.py diag --recipe manager
or
$ idf.py diag --recipe <full path>
To display available recipes, use
$ idf.py diag --list
and to verify recipes, use
$ idf.py diag --check
Both --list and --check honers the --tag and --recipe options.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
Currrently, all logs generated by RunTool are stored in files named
idf_py_(stdout|stderr)_output_$$, making it difficult to identify which
log corresponds to which command. To simplify this for idf-diag, include
the command arguments at the beginning of the log. This will allow
idf-diag to use regex to differentiate logs for build, monitor, flash,
and other commands and targets.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
Currently, we are only suggesting that the header file is likely not
part of the component's INCLUDE_DIRS. However, the header file may be
missing also because of the configuration settings. For instance, the
component might be disabled in sdkconfig, or the feature that supplies
the header might not be enabled. Enhance the hint message to address
this scenario as well.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
The object files are compiled simultaneously, which can result in
several error messages about missing headers. The current regex used to
find missing headers in the compiler's output employs a greedy search,
potentially capturing multiple error messages from different compilation
units. This can cause bug reports where the original component cannot be
identified. Strengthen the regex to ensure it only processes the first
reported error.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
This feature is useful for 3rd-party software to run GDB with predefined
options that described in project_description.json file
allow to pass custom options to "idf.py gdb":
--gdb-commands: command line arguments for gdb. (without changes)
-ex: pass command to gdb.
-x: pass gdbinit file to gdb. Alias for old --gdbinit command
__VA_NARG__ is copied from a forum post and is a pretty common implementation
with a high chance of causing naming collision
Added ESP_ namespace to avoid this.
Previously the error message was
CMake Error at /home/user/esp-idf/tools/cmake/build.cmake:296 (__component_get_property):
__component_get_property Function invoked with incorrect arguments for
function named: __component_get_property
Call Stack (most recent call first):
/home/user/esp-idf/tools/cmake/build.cmake:341 (__build_resolve_and_add_req)
/home/user/esp-idf/tools/cmake/build.cmake:638 (__build_expand_requirements)
/home/user/esp-idf/tools/cmake/project.cmake:710 (idf_build_process)
CMakeLists.txt:6 (project)
Now it will be:
CMake Error at /home/user/esp-idf/tools/cmake/build.cmake:298 (message):
Failed to resolve component 'whatever' required by component 'main'.
Call Stack (most recent call first):
/home/user/esp-idf/tools/cmake/build.cmake:345 (__build_resolve_and_add_req)
/home/user/esp-idf/tools/cmake/build.cmake:642 (__build_expand_requirements)
/home/user/esp-idf/tools/cmake/project.cmake:710 (idf_build_process)
CMakeLists.txt:6 (project)
Also improved the hint to show the component name in quotes.
