bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: document "west gtags" command

Browse Source 
Document this command's existence, provide basic usage, and describe
the locations of resources where additional help etc. should be found.

Signed-off-by: Martí Bolívar <marti.bolivar@oss.qualcomm.com>
This commit is contained in:
Martí Bolívar 2025-02-19 00:10:33 -08:00 committed by Carles Cufí
parent 2db0fb60f2
commit 70efa2b120
1 changed files with 49 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
doc/develop/west/zephyr-cmds.rst
View File

@ -219,3 +219,52 @@ You can list all known standard descriptor names using::
You can print the offset of the descriptors inside the image using::
west bindesc get_offset
Indexing the sources with GNU Global: ``west gtags``
****************************************************
.. important:: You must install the ``gtags`` and ``global`` programs provided
by `GNU Global`_ to use this command.
The ``west gtags`` command lets you create a GNU Global tags file for the entire
west workspace::
west gtags
.. _GNU Global: https://www.gnu.org/software/global/
This will create a tags file named ``GTAGS`` in the workspace :ref:`topdir
<west-workspace>` (it will also create other Global-related metadata files
named ``GPATH`` and ``GRTAGS`` in the same place).
You can then run the ``global`` command anywhere inside the
workspace to search for symbol locations using this tags file.
For example, to search for definitions of the ``arch_system_halt()`` function,
starting from the ``zephyr/drivers`` directory::
$ cd zephyr/drivers
$ global -x arch_system_halt
arch_system_halt 65 ../arch/arc/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason)
arch_system_halt 455 ../arch/arm64/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason)
arch_system_halt 137 ../arch/nios2/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason)
arch_system_halt 18 ../arch/posix/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason)
arch_system_halt 17 ../arch/x86/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason)
arch_system_halt 126 ../arch/xtensa/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason)
arch_system_halt 21 ../kernel/fatal.c FUNC_NORETURN __weak void arch_system_halt(unsigned int reason)
This prints the search symbol, the line it is defined on, a relative path to
the file it is defined in, and the line itself, for all places where the symbol
is defined.
Additional tips:
- This can also be useful to search for vendor HAL function definitions.
- See the ``global`` command's manual page for more information on how to use
this tool.
- You should run ``global``, **not** ``west global``. There is no need for a
separate ``west global`` command since ``global`` already searches for the
``GTAGS`` file starting from your current working directory. This is why you
need to run ``global`` from inside the workspace.