[PATCH v2 4/4] Add doc and news for DWARF index cache

Simon Marchi
2018-07-25T22:47:31Z

This patch adds doc and news for the feature introduced by the previous
patch.

gdb/ChangeLog:

* NEWS: Mention the index cache.

gdb/doc/ChangeLog:

* gdb.texinfo (Index Files Speed Up GDB): Add section about
symbol index cache.
---
gdb/NEWS | 3 +++
gdb/doc/gdb.texinfo | 36 ++++++++++++++++++++++++++++++++++++
2 files changed, 39 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 76b963e..9c8c912 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -7,6 +7,9 @@
can be passed using the '[ADDRESS]:PORT' notation, or the regular
'ADDRESS:PORT' method.

+* DWARF index cache: GDB can now automatically save indices DWARF symbols on
+ disk to speed up further loading of the same binaries.
+
* New commands

frame apply [all | COUNT | -COUNT | level LEVEL...] [FLAG]... COMMAND
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b36a39b..9533c72 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -20095,6 +20095,42 @@ There are currently some limitation on indices. They only work when
for DWARF debugging information, not stabs. And, they do not
currently work for programs using Ada.

+@subsection Automatic symbol index cache
+
+It is possible for GDB to automatically save a copy of this index in a cache
+on disk and retrieve it from there when loading the same binary in the future.
+This feature can be turned on with @command{set index-cache on}. The following
+commands can be used to tweak the behavior of the index cache.
+
+@table @code
+
+@item set index-cache on
+@itemx set index-cache off
+
+Enable or disable the use of the symbol index cache.
+
+@item set index-cache directory @var{directory}
+@itemx show index-cache directory
+Set/show the directory where index files will be saved. By default, the value
+@code{$XDG_CACHE_HOME/gdb} is used if the @code{XDG_CACHE_HOME} environment
+variable is defined. The value @code{$HOME/.cache/gdb} is used otherwise.
+
+There is no limit on the disk space used by index cache. It is perfectly safe
+to delete the content of that directory to free up disk space.
+
+@item set index-cache format @var{format}
+@itemx show index-cache format
+Set/show the format in which index files are saved. @var{format} can be either
+@code{gdb} (the default) or @code{dwarf-5}. Note that @value{GDBN} is currently
+only able to read back files in the @code{gdb} format from the cache, so
+@code{dwarf-5} is not very useful.
+
+@item show index-cache stats
+Print the number of cache hits and misses for the index cache since the launch
+of @value{GDBN}.
+
+@end table
+
@node Symbol Errors
@section Errors Reading Symbol Files

--
2.7.4