[RFA] [4/4] Remove libgdb API (gdb.h & doc)

[RFA] [4/4] Remove libgdb API (gdb.h & doc)

[Keith Seitz]

[-- Attachment #1: Type: text/plain, Size: 392 bytes --]

Hi,

This final patch simply removes the gdb.h and removes mention of it from 
the makefile and gdbint.texinfo.

Keith

ChangeLog
2012-01-12  Keith Seitz  <keiths@redhat.com>

	* Makefile.in (HFILES_NO_SRCDIR): Remove gdb.h.
	* gdb.h: Remove file.

doc/ChangeLog
2012-01-12  Keith Seitz  <keiths@redhat.com>

	* gdbint.texinfo (Node libgdb): Remove all mention
	of gdb.h and associated text.

[-- Attachment #2: remove-gdb_h.patch --]
[-- Type: text/x-patch, Size: 3416 bytes --]

diff --git a/gdb/Makefile.in b/gdb/Makefile.in
index 25067f1..8b0b768 100644
--- a/gdb/Makefile.in
+++ b/gdb/Makefile.in
@@ -772,7 +772,7 @@ c-lang.h d-lang.h frame.h event-loop.h block.h cli/cli-setshow.h	\
 cli/cli-decode.h cli/cli-cmds.h cli/cli-dump.h cli/cli-utils.h \
 cli/cli-script.h macrotab.h symtab.h version.h gnulib/wchar.in.h \
 gnulib/string.in.h gnulib/str-two-way.h \
-gnulib/stdint.in.h remote.h gdb.h sparc-nat.h \
+gnulib/stdint.in.h remote.h sparc-nat.h \
 gdbthread.h dwarf2-frame.h dwarf2-frame-tailcall.h nbsd-nat.h dcache.h \
 amd64-nat.h s390-tdep.h arm-linux-tdep.h exceptions.h macroscope.h \
 gdbarch.h bsd-uthread.h gdb_stat.h memory-map.h	memrange.h \
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index 136f77f..1dd8a57 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -1769,8 +1769,6 @@ Observer - @file{gdb-events.h}.
 Builder - @file{ui-out.h}
 @item
 Event Loop - @file{event-loop.h}
-@item
-Library - @file{gdb.h}
 @end itemize
 
 The model that ties these components together is described below.
@@ -1853,12 +1851,6 @@ The event-loop will eventually be made re-entrant.  This is so that
 @value{GDBN} can better handle the problem of some commands blocking
 instead of returning.
 
-@subheading Library - @file{gdb.h}
-@file{libgdb} is the most obvious component of this system.  It provides
-the query interface.  Each function is parameterized by a @code{ui-out}
-builder.  The result of the query is constructed using that builder
-before the query function returns.
-
 @node Values
 @chapter Values
 @section Values
diff --git a/gdb/gdb.h b/gdb/gdb.h
deleted file mode 100644
index 97b787d..0000000
--- a/gdb/gdb.h
+++ /dev/null
@@ -1,44 +0,0 @@
-/* Library interface into GDB.
-   Copyright (C) 1999, 2001, 2007-2012 Free Software Foundation, Inc.
-
-   This file is part of GDB.
-
-   This program is free software; you can redistribute it and/or modify
-   it under the terms of the GNU General Public License as published by
-   the Free Software Foundation; either version 3 of the License, or
-   (at your option) any later version.
-
-   This program is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
-
-#ifndef GDB_H
-#define GDB_H
-
-struct ui_out;
-
-/* Return-code (RC) from a gdb library call.  (The abreviation RC is
-   taken from the sim/common directory.) */
-
-enum gdb_rc {
-  /* The operation failed.  The failure message can be fetched by
-     calling ``char *error_last_message(void)''.  The value is
-     determined by the catch_errors() interface.  The MSG parameter is
-     set to a freshly allocated copy of the error message.  */
-  /* NOTE: Since ``defs.h:catch_errors()'' does not return an error /
-     internal / quit indication it is not possible to return that
-     here.  */
-  GDB_RC_FAIL = 0,
-  /* No error occured but nothing happened.  Due to the catch_errors()
-     interface, this must be non-zero.  */
-  GDB_RC_NONE = 1,
-  /* The operation was successful.  Due to the catch_errors()
-     interface, this must be non-zero.  */
-  GDB_RC_OK = 2
-};
-
-#endif

Re: [RFA] [4/4] Remove libgdb API (gdb.h & doc)

[Eli Zaretskii]

> Date: Fri, 13 Jan 2012 11:59:31 -0800
> From: Keith Seitz <keiths@redhat.com>
> 
> This final patch simply removes the gdb.h and removes mention of it from 
> the makefile and gdbint.texinfo.
> [...]
> -@subheading Library - @file{gdb.h}
> -@file{libgdb} is the most obvious component of this system.  It provides
> -the query interface.  Each function is parameterized by a @code{ui-out}
> -builder.  The result of the query is constructed using that builder
> -before the query function returns.

I admit I don't really understand where all this is going.  We are not
removing libgdb itself, are we?  If we are, there are many more
references to libgdb in the manual that need to be removed or
rewritten.

If we are not removing libgdb, but only gdb.h, then I have 2
questions:

  . Why does it make sense to remove gdb.h, if the library is going to
    stay?

  . The text you remove above speaks about libgdb; gdb.h is just
    mentioned as the related header.  Even if gdb.h is going to be
    removed, it doesn't make sense IMO to remove the description of
    libgdb itself, because otherwise the rest of this section will
    make no sense at all.  The section's name, let me remind you, is
    "libgdb components", so how omitting libgdb itself from the
    discussion could possibly be TRT?  E.g., all those references to
    "queries" will have no real meaning.

What am I missing?

Re: [RFA] [4/4] Remove libgdb API (gdb.h & doc)

[Tom Tromey]

>>>>> "Keith" == Keith Seitz <keiths@redhat.com> writes:

Keith> This final patch simply removes the gdb.h and removes mention of it
Keith> from the makefile and gdbint.texinfo.

The code bits of this are ok once the rest of the series is approved.

thanks,
Tom

Re: [RFA] [4/4] Remove libgdb API (gdb.h & doc)

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> I admit I don't really understand where all this is going.  We are
Eli> not removing libgdb itself, are we?

No.

Eli> If we are not removing libgdb, but only gdb.h, then I have 2
Eli> questions:

Eli>   . Why does it make sense to remove gdb.h, if the library is going to
Eli>     stay?

gdb.h declares a few wrappers that follow a different exception
convention from the rest of gdb.  However, there aren't enough of these
wrappers to actually interface any client program with the rest of gdb;
clients in practice will have to use the other exception handling
mechanism.  So, at present this stuff serves to obfuscate more than
help.  Also, I don't think anybody is going to, or should, work on
extending this interface.

So, removing this is a cleanup.  It helps make gdb more regular.

Tom

Re: [RFA] [4/4] Remove libgdb API (gdb.h & doc)

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: Keith Seitz <keiths@redhat.com>, gdb-patches@sourceware.org
> Date: Mon, 16 Jan 2012 10:19:30 -0700
> 
> Eli>   . Why does it make sense to remove gdb.h, if the library is going to
> Eli>     stay?
> 
> gdb.h declares a few wrappers that follow a different exception
> convention from the rest of gdb.  However, there aren't enough of these
> wrappers to actually interface any client program with the rest of gdb;
> clients in practice will have to use the other exception handling
> mechanism.  So, at present this stuff serves to obfuscate more than
> help.  Also, I don't think anybody is going to, or should, work on
> extending this interface.
> 
> So, removing this is a cleanup.  It helps make gdb more regular.

Thanks for the explanations.

In that case, I think the change to the manual went one notch too far:
it should only remove references to gdb.h, but not to libgdb itself.
IOW, rephrase the text that references gdb.h and libgdb such that it
references only the latter.

TIA