Patchwork Install and generate docs for gdb-add-index

login
register
mail settings
Submitter Sergio Durigan Junior
Date Jan. 11, 2018, 9:35 p.m.
Message ID <20180111213530.23774-1-sergiodj@redhat.com>
Download mbox | patch
Permalink /patch/25347/
State New
Headers show

Comments

Sergio Durigan Junior - Jan. 11, 2018, 9:35 p.m.
The "gdb-add-index" script has been resurrected on:

  commit caf26be91a584ef141ac5d3cb31007731af8b8e3
  Author: Samuel Bronson <naesten@gmail.com>
  Date:   Fri Nov 15 16:09:33 2013 -0500

      Resurrect gdb-add-index as a contrib script

However, for some reason (I couldn't find it in the archives), only
the script has been checked-in; the Makefile parts responsible for
installing it in the system were left out.  This commit fixes that, by
also resurrecting the Makefile and documentation bits.

This commit is part of our effort to upstream the local Fedora GDB
changes.  With this commit, we'll only carry a very small
Fedora-specific modification to the script.

gdb/ChangeLog:
2017-01-11  Tom Tromey  <tom@tromey.com>

	* Makefile.in (install-only): Install gdb-add-index.

gdb/doc/ChangeLog:
2017-01-11  Tom Tromey  <tom@tromey.com>
	    Sergio Durigan Junior  <sergiodj@redhat.com>

	* gdb.texinfo (Index Files): Mention gdb-add-index.
	(gdb-add-index man): New section.
	* Makefile.in (gdb-add-index.1): New rule to generate manpage
	from gdb.texinfo.
---
 gdb/Makefile.in     |  9 ++++++++
 gdb/doc/Makefile.in |  9 +++++++-
 gdb/doc/gdb.texinfo | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+), 1 deletion(-)
Simon Marchi - Jan. 11, 2018, 10:27 p.m.
On 2018-01-11 04:35 PM, Sergio Durigan Junior wrote:
> The "gdb-add-index" script has been resurrected on:
> 
>   commit caf26be91a584ef141ac5d3cb31007731af8b8e3
>   Author: Samuel Bronson <naesten@gmail.com>
>   Date:   Fri Nov 15 16:09:33 2013 -0500
> 
>       Resurrect gdb-add-index as a contrib script
> 
> However, for some reason (I couldn't find it in the archives), only
> the script has been checked-in; the Makefile parts responsible for
> installing it in the system were left out.  This commit fixes that, by
> also resurrecting the Makefile and documentation bits.
> 
> This commit is part of our effort to upstream the local Fedora GDB
> changes.  With this commit, we'll only carry a very small
> Fedora-specific modification to the script.

Woo thanks!

I have some comments, but I'm just being picky.

> diff --git a/gdb/Makefile.in b/gdb/Makefile.in
> index 17b71c6e7c..d63220db4e 100644
> --- a/gdb/Makefile.in
> +++ b/gdb/Makefile.in
> @@ -1770,6 +1770,15 @@ install-only: $(CONFIG_INSTALL)
>  		  $(INSTALL_SCRIPT) gcore \
>  			  $(DESTDIR)$(bindir)/$$transformed_name; \
>  	fi
> +	transformed_name=`t='$(program_transform_name)'; \
> +			  echo gdb-add-index | sed -e "$$t"` ; \
> +		if test "x$$transformed_name" = x; then \
> +		  transformed_name=gdb-add-index ; \
> +		else \
> +		  true ; \
> +		fi ; \
> +		$(INSTALL_PROGRAM) $(srcdir)/contrib/gdb-add-index.sh \
> +			$(DESTDIR)$(bindir)/$$transformed_name$(EXEEXT)

I know this is just copy pasted from above, but doesn't the indentation look odd?
Shouldn't the if/else/fi and the INSTALL_PROGRAM lines be indented with one tab
less?

>  	@$(MAKE) DO=install "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do
>  
>  install-strip:
> diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
> index eafadee899..0323bc4ecb 100644
> --- a/gdb/doc/Makefile.in
> +++ b/gdb/doc/Makefile.in
> @@ -174,7 +174,7 @@ POD2MAN5 = pod2man --center="GNU Development Tools" \
>  		   --release="gdb-`sed q version.subst`" --section=5
>  
>  # List of man pages generated from gdb.texi
> -MAN1S = gdb.1 gdbserver.1 gcore.1
> +MAN1S = gdb.1 gdbserver.1 gcore.1 gdb-add-index.1
>  MAN5S = gdbinit.5
>  MANS = $(MAN1S) $(MAN5S)
>  
> @@ -633,6 +633,13 @@ gcore.1: $(GDB_DOC_FILES)
>  		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
>  	rm -f gcore.pod
>  
> +gdb-add-index.1: $(GDB_DOC_FILES)
> +	touch $@
> +	-$(TEXI2POD) $(MANCONF) -Dgdb-add-index < $(srcdir)/gdb.texinfo > gdb-add-index.pod
> +	-($(POD2MAN1) gdb-add-index.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
> +		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
> +	rm -f gdb-add-index.pod
> +
>  gdbinit.5: $(GDB_DOC_FILES)
>  	touch $@
>  	-$(TEXI2POD) $(MANCONF) -Dgdbinit < $(srcdir)/gdb.texinfo > gdbinit.pod
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index dba2fa766a..62fcdd524e 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -19775,6 +19775,14 @@ 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.
>  
> +@value{GDBN} comes with a program, @command{gdb-add-index}, which can
> +be used to add the index to a symbol file.  It takes the symbol file
> +as its only argument:
> +
> +@smallexample
> +$ gdb-add-index symfile
> +@end smallexample
> +

Would it be good to put the part about gdb-add-index earlier in the page/section,
for example just after the first paragraph?  The doc starts by telling you the
manual method with the scary objcopy lines and all.  I think it would be nice if
it started by telling: here's the easy and recommended way, and then here are all
the gory details about how it's done internally, if you need it.  I could imagine
users starting to read the section, and stopping midway because they think it's
too complicated/not worth it, and never get to the gdb-add-index part.

Simon
Sergio Durigan Junior - Jan. 12, 2018, 4:17 a.m.
On Thursday, January 11 2018, Simon Marchi wrote:

> On 2018-01-11 04:35 PM, Sergio Durigan Junior wrote:
>> The "gdb-add-index" script has been resurrected on:
>> 
>>   commit caf26be91a584ef141ac5d3cb31007731af8b8e3
>>   Author: Samuel Bronson <naesten@gmail.com>
>>   Date:   Fri Nov 15 16:09:33 2013 -0500
>> 
>>       Resurrect gdb-add-index as a contrib script
>> 
>> However, for some reason (I couldn't find it in the archives), only
>> the script has been checked-in; the Makefile parts responsible for
>> installing it in the system were left out.  This commit fixes that, by
>> also resurrecting the Makefile and documentation bits.
>> 
>> This commit is part of our effort to upstream the local Fedora GDB
>> changes.  With this commit, we'll only carry a very small
>> Fedora-specific modification to the script.
>
> Woo thanks!
>
> I have some comments, but I'm just being picky.

Thanks for the review, Simon.

>> diff --git a/gdb/Makefile.in b/gdb/Makefile.in
>> index 17b71c6e7c..d63220db4e 100644
>> --- a/gdb/Makefile.in
>> +++ b/gdb/Makefile.in
>> @@ -1770,6 +1770,15 @@ install-only: $(CONFIG_INSTALL)
>>  		  $(INSTALL_SCRIPT) gcore \
>>  			  $(DESTDIR)$(bindir)/$$transformed_name; \
>>  	fi
>> +	transformed_name=`t='$(program_transform_name)'; \
>> +			  echo gdb-add-index | sed -e "$$t"` ; \
>> +		if test "x$$transformed_name" = x; then \
>> +		  transformed_name=gdb-add-index ; \
>> +		else \
>> +		  true ; \
>> +		fi ; \
>> +		$(INSTALL_PROGRAM) $(srcdir)/contrib/gdb-add-index.sh \
>> +			$(DESTDIR)$(bindir)/$$transformed_name$(EXEEXT)
>
> I know this is just copy pasted from above, but doesn't the indentation look odd?
> Shouldn't the if/else/fi and the INSTALL_PROGRAM lines be indented with one tab
> less?

Ah, you're right.  Strange, I don't know why it is indented this way
originally.  Anyway, fixed it.

>>  	@$(MAKE) DO=install "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do
>>  
>>  install-strip:
>> diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
>> index eafadee899..0323bc4ecb 100644
>> --- a/gdb/doc/Makefile.in
>> +++ b/gdb/doc/Makefile.in
>> @@ -174,7 +174,7 @@ POD2MAN5 = pod2man --center="GNU Development Tools" \
>>  		   --release="gdb-`sed q version.subst`" --section=5
>>  
>>  # List of man pages generated from gdb.texi
>> -MAN1S = gdb.1 gdbserver.1 gcore.1
>> +MAN1S = gdb.1 gdbserver.1 gcore.1 gdb-add-index.1
>>  MAN5S = gdbinit.5
>>  MANS = $(MAN1S) $(MAN5S)
>>  
>> @@ -633,6 +633,13 @@ gcore.1: $(GDB_DOC_FILES)
>>  		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
>>  	rm -f gcore.pod
>>  
>> +gdb-add-index.1: $(GDB_DOC_FILES)
>> +	touch $@
>> +	-$(TEXI2POD) $(MANCONF) -Dgdb-add-index < $(srcdir)/gdb.texinfo > gdb-add-index.pod
>> +	-($(POD2MAN1) gdb-add-index.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
>> +		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
>> +	rm -f gdb-add-index.pod
>> +
>>  gdbinit.5: $(GDB_DOC_FILES)
>>  	touch $@
>>  	-$(TEXI2POD) $(MANCONF) -Dgdbinit < $(srcdir)/gdb.texinfo > gdbinit.pod
>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index dba2fa766a..62fcdd524e 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -19775,6 +19775,14 @@ 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.
>>  
>> +@value{GDBN} comes with a program, @command{gdb-add-index}, which can
>> +be used to add the index to a symbol file.  It takes the symbol file
>> +as its only argument:
>> +
>> +@smallexample
>> +$ gdb-add-index symfile
>> +@end smallexample
>> +
>
> Would it be good to put the part about gdb-add-index earlier in the page/section,
> for example just after the first paragraph?  The doc starts by telling you the
> manual method with the scary objcopy lines and all.  I think it would be nice if
> it started by telling: here's the easy and recommended way, and then here are all
> the gory details about how it's done internally, if you need it.  I could imagine
> users starting to read the section, and stopping midway because they think it's
> too complicated/not worth it, and never get to the gdb-add-index part.

That's a good point.  I moved the text up (after the first paragraph, as
suggested) and modified it a bit:

  ...
  @node Index Files
  @section Index Files Speed Up @value{GDBN}
  @cindex index files
  @cindex @samp{.gdb_index} section

  When @value{GDBN} finds a symbol file, it scans the symbols in the
  file in order to construct an internal symbol table.  This lets most
  @value{GDBN} operations work quickly---at the cost of a delay early
  on.  For large programs, this delay can be quite lengthy, so
  @value{GDBN} provides a way to build an index, which speeds up
  startup.

  For convenience, @value{GDBN} comes with a program,
  @command{gdb-add-index}, which can be used to add the index to a
  symbol file.  It takes the symbol file as its only argument:

  @smallexample
  $ gdb-add-index symfile
  @end smallexample

  It is also possible to do the work manually.  Here is what
  @command{gdb-add-index} does behind the curtains.
  ...

I will submit the full patch as a v2.

Thanks,
Eli Zaretskii - Jan. 12, 2018, 8:33 a.m.
> From: Sergio Durigan Junior <sergiodj@redhat.com>
> Cc: Tom Tromey <tom@tromey.com>,	Eli Zaretskii <eliz@gnu.org>,	Sergio Durigan Junior <sergiodj@redhat.com>
> Date: Thu, 11 Jan 2018 16:35:30 -0500
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index dba2fa766a..62fcdd524e 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -19775,6 +19775,14 @@ 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.
>  
> +@value{GDBN} comes with a program, @command{gdb-add-index}, which can
> +be used to add the index to a symbol file.  It takes the symbol file
> +as its only argument:
> +
> +@smallexample
> +$ gdb-add-index symfile
> +@end smallexample

I think we should have a cross-reference here to the detailed
description of this script.

> +@node gdb-add-index man
> +@heading gdb-add-index

Please add an index entry here:

 @pindex gdb-add-index

> +@c man begin DESCRIPTION gdb-add-index
> +When GDB finds a symbol file, it scans the symbols in the file in order
> +to construct an internal symbol table.  This lets most GDB operations
> +work quickly--at the cost of a delay early on.  For large programs,
> +this delay can be quite lengthy, so GDB provides a way to build an
> +index, which speeds up startup.

Please use @value{GDBN} instead of a literal "GDB".

> +To determine whether a file contains such an index, use the command
> +@command{readelf -S filename}: the index is stored in a section named
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Commands typed by the user should have the @kbd markup, not @command.
The latter is for names of shell commands, i.e. in general file names
of executable programs and scripts.

> +@code{.gdb_index}.  Note that the index is never generated for files that do
   ^^^^^^^^^^^^^^^^^
File names should have the @file markup.

> +not contain DWARF debug information (sections named @code{.debug_*}).

I think this sentence is too obscure.  I think we should say
explicitly that the index can only be produced on systems which use
ELF binaries and DWARF debug info.  E.g., users of GDB on MS-Windows
should understand from this that they cannot use this feature.

> +@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
> +in the @code{PATH} environment variable.  If you want to use different
          ^^^^^^^^^^^
Environment variables should have the @env markup.

> +versions of these programs, you can specify them through the
> +@code{GDB} and @code{OBJDUMP} environment variables.

Likewise.

> +
> +See more in
> +@ifset man
> +the @value{GDBN} manual in node @code{Index Files}
> +-- shell command @code{info -f gdb -n 'Index Files'}.
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@kbd, not @code.

Also, please use quotation "like this", because 'like this' only works
on Posix platforms.

The documentation part is OK with those fixed.

Thanks.
Sergio Durigan Junior - Jan. 12, 2018, 4:58 p.m.
Thanks for the thorough review, Eli!

On Friday, January 12 2018, Eli Zaretskii wrote:

>> From: Sergio Durigan Junior <sergiodj@redhat.com>
>> Cc: Tom Tromey <tom@tromey.com>,	Eli Zaretskii <eliz@gnu.org>,	Sergio Durigan Junior <sergiodj@redhat.com>
>> Date: Thu, 11 Jan 2018 16:35:30 -0500
>> 
>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index dba2fa766a..62fcdd524e 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -19775,6 +19775,14 @@ 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.
>>  
>> +@value{GDBN} comes with a program, @command{gdb-add-index}, which can
>> +be used to add the index to a symbol file.  It takes the symbol file
>> +as its only argument:
>> +
>> +@smallexample
>> +$ gdb-add-index symfile
>> +@end smallexample
>
> I think we should have a cross-reference here to the detailed
> description of this script.

OK, included:

  For convenience, @value{GDBN} comes with a program,
  @command{gdb-add-index}, which can be used to add the index to a
  symbol file.  It takes the symbol file as its only argument:

  @smallexample
  $ gdb-add-index symfile
  @end smallexample

  @xref{gdb-add-index}.

>> +@node gdb-add-index man
>> +@heading gdb-add-index
>
> Please add an index entry here:
>
>  @pindex gdb-add-index

Done.

>> +@c man begin DESCRIPTION gdb-add-index
>> +When GDB finds a symbol file, it scans the symbols in the file in order
>> +to construct an internal symbol table.  This lets most GDB operations
>> +work quickly--at the cost of a delay early on.  For large programs,
>> +this delay can be quite lengthy, so GDB provides a way to build an
>> +index, which speeds up startup.
>
> Please use @value{GDBN} instead of a literal "GDB".

Fixed.

>> +To determine whether a file contains such an index, use the command
>> +@command{readelf -S filename}: the index is stored in a section named
>    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Commands typed by the user should have the @kbd markup, not @command.
> The latter is for names of shell commands, i.e. in general file names
> of executable programs and scripts.

Fixed.

>> +@code{.gdb_index}.  Note that the index is never generated for files that do
>    ^^^^^^^^^^^^^^^^^
> File names should have the @file markup.

This refers to a section name, not a file name.  Should it still be
marked as @file?

>> +not contain DWARF debug information (sections named @code{.debug_*}).
>
> I think this sentence is too obscure.  I think we should say
> explicitly that the index can only be produced on systems which use
> ELF binaries and DWARF debug info.  E.g., users of GDB on MS-Windows
> should understand from this that they cannot use this feature.

Here's how I've rewritten this part:

  To determine whether a file contains such an index, use the command
  @kbd{readelf -S filename}: the index is stored in a section named
  @code{.gdb_index}.  The index file can only be produced on systems
  which use ELF binaries and DWARF debug information (i.e., sections
  named @code{.debug_*}).

>> +@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
>> +in the @code{PATH} environment variable.  If you want to use different
>           ^^^^^^^^^^^
> Environment variables should have the @env markup.

Fixed.

>> +versions of these programs, you can specify them through the
>> +@code{GDB} and @code{OBJDUMP} environment variables.
>
> Likewise.

Fixed.

>> +
>> +See more in
>> +@ifset man
>> +the @value{GDBN} manual in node @code{Index Files}
>> +-- shell command @code{info -f gdb -n 'Index Files'}.
>                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> @kbd, not @code.
>
> Also, please use quotation "like this", because 'like this' only works
> on Posix platforms.

Fixed.

> The documentation part is OK with those fixed.

Thanks!  I'll wait for your reply re. the @file question, and then push
it.
Eli Zaretskii - Jan. 12, 2018, 6:39 p.m.
> From: Sergio Durigan Junior <sergiodj@redhat.com>
> Cc: gdb-patches@sourceware.org,  tom@tromey.com
> Date: Fri, 12 Jan 2018 11:58:39 -0500
> 
> >> +@code{.gdb_index}.  Note that the index is never generated for files that do
> >    ^^^^^^^^^^^^^^^^^
> > File names should have the @file markup.
> 
> This refers to a section name, not a file name.  Should it still be
> marked as @file?

No, it's my bad.  @code is fine.

> >> +not contain DWARF debug information (sections named @code{.debug_*}).
> >
> > I think this sentence is too obscure.  I think we should say
> > explicitly that the index can only be produced on systems which use
> > ELF binaries and DWARF debug info.  E.g., users of GDB on MS-Windows
> > should understand from this that they cannot use this feature.
> 
> Here's how I've rewritten this part:
> 
>   To determine whether a file contains such an index, use the command
>   @kbd{readelf -S filename}: the index is stored in a section named
>   @code{.gdb_index}.  The index file can only be produced on systems
>   which use ELF binaries and DWARF debug information (i.e., sections
>   named @code{.debug_*}).

Looks good, thanks.

Patch

diff --git a/gdb/Makefile.in b/gdb/Makefile.in
index 17b71c6e7c..d63220db4e 100644
--- a/gdb/Makefile.in
+++ b/gdb/Makefile.in
@@ -1770,6 +1770,15 @@  install-only: $(CONFIG_INSTALL)
 		  $(INSTALL_SCRIPT) gcore \
 			  $(DESTDIR)$(bindir)/$$transformed_name; \
 	fi
+	transformed_name=`t='$(program_transform_name)'; \
+			  echo gdb-add-index | sed -e "$$t"` ; \
+		if test "x$$transformed_name" = x; then \
+		  transformed_name=gdb-add-index ; \
+		else \
+		  true ; \
+		fi ; \
+		$(INSTALL_PROGRAM) $(srcdir)/contrib/gdb-add-index.sh \
+			$(DESTDIR)$(bindir)/$$transformed_name$(EXEEXT)
 	@$(MAKE) DO=install "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do
 
 install-strip:
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index eafadee899..0323bc4ecb 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -174,7 +174,7 @@  POD2MAN5 = pod2man --center="GNU Development Tools" \
 		   --release="gdb-`sed q version.subst`" --section=5
 
 # List of man pages generated from gdb.texi
-MAN1S = gdb.1 gdbserver.1 gcore.1
+MAN1S = gdb.1 gdbserver.1 gcore.1 gdb-add-index.1
 MAN5S = gdbinit.5
 MANS = $(MAN1S) $(MAN5S)
 
@@ -633,6 +633,13 @@  gcore.1: $(GDB_DOC_FILES)
 		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
 	rm -f gcore.pod
 
+gdb-add-index.1: $(GDB_DOC_FILES)
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dgdb-add-index < $(srcdir)/gdb.texinfo > gdb-add-index.pod
+	-($(POD2MAN1) gdb-add-index.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f gdb-add-index.pod
+
 gdbinit.5: $(GDB_DOC_FILES)
 	touch $@
 	-$(TEXI2POD) $(MANCONF) -Dgdbinit < $(srcdir)/gdb.texinfo > gdbinit.pod
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index dba2fa766a..62fcdd524e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19775,6 +19775,14 @@  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.
 
+@value{GDBN} comes with a program, @command{gdb-add-index}, which can
+be used to add the index to a symbol file.  It takes the symbol file
+as its only argument:
+
+@smallexample
+$ gdb-add-index symfile
+@end smallexample
+
 @node Symbol Errors
 @section Errors Reading Symbol Files
 
@@ -42750,6 +42758,7 @@  switch (die->tag)
 * gdbserver man::               Remote Server for the GNU Debugger man page
 * gcore man::                   Generate a core file of a running program
 * gdbinit man::                 gdbinit scripts
+* gdb-add-index man::           Add index files to speed up GDB
 @end menu
 
 @node gdb man
@@ -43426,6 +43435,59 @@  Richard M. Stallman and Roland H. Pesch, July 1991.
 @end ifset
 @c man end
 
+@node gdb-add-index man
+@heading gdb-add-index
+
+@c man title gdb-add-index Add index files to speed up GDB
+
+@c man begin SYNOPSIS gdb-add-index
+gdb-add-index @var{filename}
+@c man end
+
+@c man begin DESCRIPTION gdb-add-index
+When GDB finds a symbol file, it scans the symbols in the file in order
+to construct an internal symbol table.  This lets most GDB operations
+work quickly--at the cost of a delay early on.  For large programs,
+this delay can be quite lengthy, so GDB provides a way to build an
+index, which speeds up startup.
+
+To determine whether a file contains such an index, use the command
+@command{readelf -S filename}: the index is stored in a section named
+@code{.gdb_index}.  Note that the index is never generated for files that do
+not contain DWARF debug information (sections named @code{.debug_*}).
+
+@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
+in the @code{PATH} environment variable.  If you want to use different
+versions of these programs, you can specify them through the
+@code{GDB} and @code{OBJDUMP} environment variables.
+
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{Index Files}
+-- shell command @code{info -f gdb -n 'Index Files'}.
+@end ifset
+@ifclear man
+@ref{Index Files}.
+@end ifclear
+@c man end
+
+@c man begin SEEALSO gdb-add-index
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
 @include gpl.texi
 
 @node GNU Free Documentation License