Revise a sentence to avoid misinterpretation. Move @cindex entries
before the text they index. Refer to trace frames regarding partial
reads.
Approved-By: Eli Zaretskii <eliz@gnu.org>
The current gdb-add-index manual page is a bit out-of-date. This
commit fixes a few deficiencies:
- gdb-add-index does not use objdump; it uses objcopy and readelf
- missing info on environment variables (in appropriate ENVIRONMENT section).
- missing mention of -dwarf-5 option
- adds important notice about FILENAME being writable
- explains exit status
- the script adds appropriate section(s) to the file; it does not
output new files with the section(s)
Approved-By: Eli Zaretskii <eliz@gnu.org>
Oleg pointed out that when renaming from "status" to "enabled" in the
Python TUI events patch, I neglected to update one spot in the
documentation. This patch fixes this. I'm checking it in as obvious.
You can verify that this change is correct by examining
gdb/python/py-event-types.def.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32162
This patch reuses the "title" style for titles -- in particular the
header line of a list display.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-By: Keith Seitz <keiths@redhat.com>
Approved-By: Andrew Burgess <aburgess@redhat.com>
This adds a new "command" style that is used when styling the name of
a gdb command.
Note that not every instance of a command name that is output by gdb
is changed here. There is currently no way to style error() strings,
and there is no way to mark up command help strings.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=31747
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-By: Keith Seitz <keiths@redhat.com>
Approved-By: Andrew Burgess <aburgess@redhat.com>
While testing DAP, we found a situation where a compiler-generated
variable caused the "variables" request to fail -- the variable in
question being an apparent 67-megabyte string.
It seems to me that artificial variables like this aren't interesting
to DAP users, and the gdb CLI omits these as well.
This patch changes DAP to omit these variables, adding a new
gdb.Symbol.is_artificial attribute to make this possible.
Intel has EOL'ed the Nios II architecture, and it's time to remove support
from all toolchain components before it gets any more bit-rotten from
lack of maintenance or regular testing.
At present, process record/replay and reverse debugging has been
implemented on LoongArch. Update the NEWS and doc to record this
new change.
Signed-off-by: Hui Li <lihui@loongson.cn>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
Signed-off-by: Tiezhu Yang <yangtiezhu@loongson.cn>
Eli mentioned [1] that given that we use US English spelling in our
documentation, we should use "behavior" instead of "behaviour".
In wikipedia-common-misspellings.txt there's a rule:
...
behavour->behavior, behaviour
...
which leaves this as a choice.
Add an overriding rule to hardcode the choice to common-misspellings.txt:
...
behavour->behavior
...
and add a rule to rewrite behaviour into behavior:
...
behaviour->behavior
...
and re-run spellcheck.sh on gdb*.
Tested on x86_64-linux.
[1] https://sourceware.org/pipermail/gdb-patches/2024-November/213371.html
The 80-column-help-string self-test can fail if gdb's install
directory is too long, because the help for "jit-reader-load" includes
JIT_READER_DIR.
This help text is actually somewhat misleading, though.
JIT_READER_DIR is not actually used directly -- instead the relocated
variant is used.
This patch adds a new "show jit-reader-directory" command and changes
the help text to refer to this instead. I considered adding a "set"
command as well, but since absolute paths are acceptable here, and
since this is a very niche command anyway, I figured there was no need
to bother.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32357
Reviewed-By: Kévin Le Gouguec <legouguec@adacore.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Andrew Burgess <aburgess@redhat.com>
I noticed the gdb.LazyString documentation did not mention how to
create one. Then, while adding this, I found a couple other ways that
this documentation could be clarified.
Approved-By: Eli Zaretskii <eliz@gnu.org>
When debugging readline issues I'd like an easy way to know (for sure)
what version of readline GDB is using. This could also be useful when
writing readline tests, knowing the precise readline version will
allow us to know if we expect a test to pass or not.
Add the readline library version to the output of the 'show
configuration' command. Also include a suffix indicating if we are
using the system readline, or the statically linked in readline.
The information about static readline vs shared readline can be
figured out from the configure command output, but having it repeated
in the readline version line makes it super easy to grok within tests,
and it's super cheap, so I don't see this as a problem.
A customer noted that there is no way to prevent the "current language
does not match this frame" warning. This patch adds a new setting to
allow this warning to be suppressed.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Andrew Burgess <aburgess@redhat.com>
Implement extension_language_ops::find_objfile_from_buildid within
GDB's Python API. Doing this allows users to write Python extensions
that can help locate missing objfiles when GDB opens a core file. A
handler might perform some project- or site-specific actions to find a
missing objfile. Or might provide some project- or site-specific
advice to the user on how they can obtain the missing objfile.
The implementation is very similar to the approach taken in:
commit 8f6c452b5a
Date: Sun Oct 15 22:48:42 2023 +0100
gdb: implement missing debug handler hook for Python
The following new commands are added as commands implemented in
Python, this is similar to how the Python missing debug and unwinder
commands are implemented:
info missing-objfile-handlers
enable missing-objfile-handler LOCUS HANDLER
disable missing-objfile-handler LOCUS HANDLER
To make use of this extension hook a user will create missing objfile
handler objects, and registers these handlers with GDB. When GDB
opens a core file and encounters a missing objfile each handler is
called in turn until one is able to help. Here is a minimal handler
that does nothing useful:
import gdb
import gdb.missing_objfile
class MyFirstHandler(gdb.missing_objfile.MissingObjfileHandler):
def __init__(self):
super().__init__("my_first_handler")
def __call__(self, pspace, build_id, filename):
# This handler does nothing useful.
return None
gdb.missing_objfile.register_handler(None, MyFirstHandler())
Returning None from the __call__ method tells GDB that this handler
was unable to find the missing objfile, and GDB should ask any other
registered handlers.
Possible return values from a handler:
- None: This means the handler couldn't help. GDB will call other
registered handlers to see if they can help instead.
- False: The handler has done all it can, but the objfile couldn't
be found. GDB will not call any other handlers, and will
continue without the objfile.
- True: The handler has installed the objfile into a location where
GDB would normally expect to find it. GDB should repeat its
normal lookup process and the objfile should now be found.
- A string: The handler can return a filename, which is the missing
objfile. GDB will load this file.
Handlers can be registered globally, or per program space. GDB checks
the handlers for the current program space first, and then all of the
global handles. The first handler that returns a value that is not
None, has "handled" the missing objfile, at which point GDB continues.
The implementation of this feature is mostly straight forward. I have
reworked some of the missing debug file related code so that it can be
shared with this feature. E.g. gdb/python/lib/gdb/missing_files.py is
mostly content moved from gdb/python/lib/gdb/missing_debug.py, but
updated to be more generic. Now gdb/python/lib/gdb/missing_debug.py
and the new file gdb/python/lib/gdb/missing_objfile.py both call into
the missing_files.py file.
For gdb/python/lib/gdb/command/missing_files.py this is even more
extreme, gdb/python/lib/gdb/command/missing_debug.py is completely
gone now and gdb/python/lib/gdb/command/missing_files.py provides all
of the new commands in a generic way.
I have made one change to the existing Python API, I renamed the
attribute Progspace.missing_debug_handlers to
Progspace.missing_file_handlers. I don't see this as too
problematic. This attribute was only used to implement the missing
debug feature and was never documented beyond the fact that it
existed. There was no reason for users to be touching this attribute.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This patch started as an attempt to allow the 'Size attribute to be
applied to types, and not just objects.
However, that turns out to be difficult due to the Ada semantcs of
'Size. In particular, Ada requires 'Size to denote the size of the
representation of the value, so for example Boolean'Size must be 1.
Implementing this properly requires information not readily available
to gdb... and while we could synthesize this information in many
cases, it also seemed to me that this wasn't strictly very useful when
debugging.
So instead, this patch adds support for the 'Object_Size attribute,
which is somewhat closer to 'sizeof'.
Note also that while 'Object_Size is defined for some dynamic types, I
chose not to implement this here, as again this information is not
readily available -- and I think it's preferable to error than to
print something that might be incorrect.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
A question was asked on stackoverflow.com about the guile function
get-basic-type[1] which is mentioned in the docs along with an example
of its use.
The problem is, the function was apparently never actually added to
GDB. But it turns out that it's pretty easy to implement, so lets add
it now. Better late than never.
The implementation mirrors the Python get_basic_type function. I've
added a test which is a copy of the documentation example.
One issue is that the docs suggest that the type will be returned as
just "int", however, I'm not sure what this actually means. It makes
more sense that the function return a gdb:type object which would be
represented as "#<gdb:type int>", so I've updated the docs to show
this output.
[1] https://stackoverflow.com/questions/79058691/unbound-variable-get-basic-type-in-gdb-guile-session
Reviewed-By: Kevin Buettner <kevinb@redhat.com>
This patch introduces ADR to the Modula-2 language interface.
It return the address of the parameter supplied.
The patch also contains a dejagnu test for ADR.
Tested on x86_64-linux.
Approved-By: Tom Tromey <tom@tromey.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This patch adds separate styling for line numbers. That is, whenever
gdb prints a source line number, it uses this style.
v2 includes a change to ensure that %ps works in query.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-by: Keith Seitz <keiths@redhat.com>
GDB deprecated the commands "show/set mpx bound" in GDB 15.1, as Intel
listed Intel(R) Memory Protection Extensions (MPX) as removed in 2019.
MPX is also deprecated in gcc (since v9.1), the linux kernel (since v5.6)
and glibc (since v2.35). Let's now remove MPX support in GDB completely.
This includes the removal of:
- MPX functionality including register support
- deprecated mpx commands
- i386 and amd64 implementation of the hooks report_signal_info and
get_siginfo_type
- tests
- and pretty printer.
We keep MPX register numbers to not break compatibility with old gdbservers.
Approved-By: Felix Willgerodt <felix.willgerodt@intel.com>
One thing GDB always does when the inferior stops is finding out where
it's stopped at, by way of querying the value of the program counter
register.
To save a packet round trip, the remote target can send the PC
value (often alongside other frequently consulted registers such as the
stack pointer) in the stop reply packet as an "expedited register".
Test that this is actually done for the targets where gdbserver is
supposed to.
Extend the "maintenance print remote-registers" command output with an
"Expedited" column which says "yes" if the register was seen by GDB in
the last stop reply packet it received, and is left blank otherwise.
Tested for regressions on aarch64-linux-gnu native-extended-remote.
The testcase was tested on aarch64-linux-gnu, i686-linux-gnu and
x86_64-linux-gnu native-remote and native-extended-remote targets.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
Event tracing allows GDB to show information about interesting asynchronous
events when tracing with Intel PT. Subsequent patches will add support for
displaying each type of event.
Enabling event-tracing unconditionally would result in rather noisy output, as
breakpoints themselves result in interrupt events. Which is why this patch adds
a set/show command to allow the user to enable/disable event-tracing before
starting a recording. The event-tracing setting has no effect on an already
active recording. The default setting is off. As event tracing will use the
auxiliary infrastructure added by ptwrite, the user can still disable printing
events, even when event-tracing was enabled, by using the /a switch for the
record instruction-history/function-call-history commands.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
This commit changes the 'target ...' commands that accept a filename
to take a quoted or escaped filename rather than a literal filename.
What this means in practice is that if you are specifying a filename
that contains no white space or quote characters, then nothing should
change, e.g.:
target exec /path/to/some/file
works both before and after this commit.
However, if a user wishes to specify a file containing white space
then either the entire filename needs to be quoted, or the special
white space needs to be escaped. Before this patch a user could
write:
target exec /path/to a file/containing spaces
But after this commit the user would have to choose one of:
target exec "/path/to a file/containing spaces"
or
target exec /path/to\ a\ file/containing\ spaces
Obviously this is a potentially breaking change. The benefit of
making this change is consistency. Commands that take multiple
arguments (one of which is a filename) or in the future, commands that
take filename options, will always need to use quoted/escaped
filenames, so converting all unquoted filename commands to use quoting
or escaping makes the UI more consistent.
Additionally (though this is probably not a common problem), GDB
strips trailing white space from commands that the user enters. As
such it is not possible to reference any file that ends in white space
unless the quoting / escaping style is used. Though I suspect very
few users run into this problem!
The downside obviously is that this is a UI breaking change.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This commit changes how GDB processes command arguments for the
following commands:
compile file
maint print c-tdesc
save gdb-index
After this commit these commands will now expect their single filename
argument to be (optionally) quoted if it contains any special
characters (e.g. whit space or quotes).
If the filename does not contain any special characters then nothing
changes. As an example:
(gdb) save gdb-index /path/to/some/directory/
will work before and after this patch. However, if the directory
name contains a white space then before this patch a user would write:
(gdb) save gdb-index /path/to some/directory/
But this will now fail as GDB will consider this as two arguments,
'/path/to' and 'some/directory/'. To pass this single directory name
a user must now do one of these:
(gdb) save gdb-index "/path/to some/directory/"
(gdb) save gdb-index '/path/to some/directory/'
(gdb) save gdb-index /path/to\ some/directory/
This brings these commands into line with commands like 'file' and
'symbol-file', which have supported quoted filenames for a while.
The motivation for this change is to make handling of filename
arguments consistent throughout GDB. We can't move to all commands
taking non-quoted filenames as the non-quoted style only allows for a
single argument. Additionally, the non-quoted style doesn't allow for
filenames that end in white space (though this is probably pretty
rare). So, if we want to have consistency the only choice is to move
towards supporting quote filenames.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
The 'remove-symbol-file' command doesn't currently offer command
completion. This commit addresses this.
The 'remove-symbol-file' uses gdb_argv to split its command arguments,
this means that the filename the command expects can be quoted.
However, the 'remove-symbol-file' command is a little weird in that it
also has a '-a' option, if this option is passed then the command
expects not a filename, but an address.
Currently the remove_symbol_file_command function splits the command
args using gdb_argv, checks for a '-a' flag by looking at the first
argument value, and then expects the filename or address to occupy a
single entry in the gdb_argv array.
The first thing I do is handle the '-a' flag using GDB's option
system. I model this option as a flag_option_def (a boolean option).
I've dropped the use of gdb_argv and instead use the new(ish) function
extract_single_filename_arg, which was added a couple of commits back,
to parse the filename argument (when '-a' is not given).
If '-a' is given the the remove-symbol-file command expects an address
rather than a filename. As we previously split the arguments using
gdb_argv this meant the address needed to appear as a single
argument. So a user could write:
(gdb) remove-symbol-file 0x1234
Or they could write:
(gdb) remove-symbol-file some_function
Both of these would work fine. But a user could not write:
(gdb) remove-symbol-file some_function + 0x1000
As only the 'some_function' part would be processed. Now the user
could do this:
(gdb) remove-symbol-file "some_function + 0x1000"
By enclosing the address expression in quotes this would be handled as
a single argument. However, this is a little weird, that's not how
commands like 'print' or 'x' work. Also this functionality was
neither documented, or tested.
And so, in this commit, by removing the use of gdb_argv I bring the
'remove-symbol-file' command inline with GDB's other commands that
take an expression, the quotes are no longer needed.
Usually in a completer we call 'complete_options', but don't actually
capture the option values. But for remove-symbol-file I do. This
allows me to spot when the '-a' option has been given, I can then
complete the rest of the command line as either a filename or an
expression.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
While reviewing a patch I wanted to understand which blocks existed at
a given address.
The 'maint print symbols' command does provide some of this
information, but that command displays all blocks within a given
symtab. If I want to know which blocks are at a given address I have
to figure that out for myself based on the output of 'maint print
symbols' ... and I'm too lazy for that!
So this command lists just those blocks at a given address, along with
information about the blocks type. This new command doesn't list the
symbols within each block, for that my expectation is that you'd cross
reference the output with that of 'maint print symbols'.
The new command format is:
maintenance info blocks
maintenance info blocks ADDRESS
This lists the blocks at ADDRESS, or at the current $pc if ADDRESS is
not given. Blocks are listed starting at the global block, then the
static block, and then the progressively narrower scoped blocks.
For each block we list the internal block pointer (which allows easy
cross referencing with 'maint print symbols'), the inferior address
range, along with other useful information.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Simon Marchi <simon.marchi@efficios.com>
While reviewing a patch I wanted to view GDB's inline frame state. I
don't believe there's currently a maintenance command to view this
information, so in this commit I've added one.
The new command is:
maintenance info inline-frames
maintenance info inline-frames ADDRESS
The command lists the inline frames that start at ADDRESS, or at the
current $pc if no ADDRESS is given. The command also displays the
"outer" function in which the inline functions are present.
An example of the command output:
(gdb) maintenance info inline-frames
Cached inline state information for thread 1.
program counter = 0x401137
skipped frames = 1
bar
> foo
main
(gdb)
This tells us that function 'main' called 'foo' which called 'bar'.
The functions 'foo' and 'bar' are both inline and both start at the
address 0x401137. Currently GDB considers the inferior to be stopped
in frame 'foo' (note the '>' marker), this means that there is 1
skipped frame (function 'bar').
The function 'main' is the outer function. The outer function might
not start at 0x401137, it is simply the function that contains the
inline functions.
If the user does a 'step' then GDB will not actually move the inferior
forward, but will instead simply tell the user that the inferior
entered 'bar'. The output of 'maint info inline-frames' will change
like this:
(gdb) step
bar () at inline.c:6
6 ++global_counter;
(gdb) maintenance info inline-frames
Cached inline state information for thread 1.
program counter = 0x401137
skipped frames = 0
> bar
foo
main
(gdb)
Now GDB is in function 'bar' and there are no skipped frames.
I have renamed skipped_symbols to function symbols within the
inline_state class. We are now going to carry the "outer"
function (the function that contains all the inlined functions) within
this list (as the last entry), so the old name didn't really make
sense. As a consequence of this rename I've updated some comments.
I've changed stopped_by_user_bp_inline_frame to take a symbol rather
than a block. Previously we just used the block to access the
associated function symbol. After this commit we can just pass in the
function symbol directly, so lets do that.
New function gather_inline_frames contains some of the logic pulled
from skip_inline_frames. This new function builds the list of all
symbols of inlined functions that start at a given $pc value and also
the "outer" function that contains all of the inlined functions.
In skip_inline_frames I've split the loop logic into two. The loop to
build the function symbol list has moved to gather_inline_frames. The
loop to figure out how many of the inlined functions we are skipping
remains in skip_inline_frames and uses the result of calling
gather_inline_frames.
In inline_skipped_symbol there are some minor updates to the comment,
and I've tweaked one of the asserts now that the function symbols list
also contains the "outer" function (a <= becomes <).
The maintenance_info_inline_frames function is now and implements the
new maintenance command.
And _initialize_inline_frame is updated to register the new command.
I've added a basic test for the new command. Please excuse the file
name for the new test, in the next commit I'll be adding additional
tests and at that point the file name will make sense.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Simon Marchi <simon.marchi@efficios.com>
Call the ptwrite filter function whenever a ptwrite event is decoded.
The returned string is written to the aux_data string table and a
corresponding auxiliary instruction is appended to the function segment.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This enables gdb and gdbserver to communicate about ptwrite support. If
ptwrite support would be enabled unconditionally, GDBs with older libipt
versions would break.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This function allows to clear the trace data from python, forcing to
re-decode the trace for successive commands.
This will be used in future ptwrite patches, to trigger re-decoding when
the ptwrite filter changes.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Auxiliary instructions are no real instructions and get their own object
class, similar to gaps. gdb.Record.instruction_history is now possibly a
list of gdb.RecordInstruction, gdb.RecordGap or gdb.RecordAuxiliary
objects.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Print the auxiliary data when a btrace_insn of type BTRACE_INSN_AUX
is encountered in the function-call-history. Printing is
active by default, it can be silenced with the /a modifier.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Print the auxiliary data when a btrace_insn of type BTRACE_INSN_AUX
is encountered in the instruction-history. Printing is active by default,
it can be silenced with the /a modifier.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Auxiliary instructions are pseudo instructions pointing to auxiliary data.
This auxiliary data can be printed in all commands displaying (record
function-call-history, record instruction-history) or stepping through
(stepi etc.) the execution history, which will be introduced in the next
commits.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Remove the support for the QNX Neutrino OS (tdep and native bits). This
has been unmaintained for years, and we don't have a way to see if it
works (or even builds, for the native parts). Without somebody actively
maintaining it, this is just a burden for developers, especially that
this port does a few weird unique things that require reasoning about
when doing big change.
Support for GDBserver was removed in 2020, commit 613f149a90
("gdbserver: remove support for Neutrino").
Change-Id: I4e25ec26ab06636629adebd02ceb161ee31c232d
Approved-by: Kevin Buettner <kevinb@redhat.com>
When building the GDB info manual I see this warning:
gdb.texinfo:41447: warning: @anchor should not appear on @item line
And indeed line 41447 looks like this:
@item @anchor{maint info breakpoints}maint info breakpoints
I propose moving the @anchor{...} part to the previous line which
silences the warning.
Approved-By: Eli Zaretskii <eliz@gnu.org>
It also tests the gcore script being run without its accessible
terminal.
This test was written by Jan Kratochvil a long time ago. I modernized
the test making it use various procs from lib/gdb.exp, reorganizing it
and added some comments.
Modify the gcore script to make it possible to pass the --data-directory to
it. This prevents a lot of these warnings:
Python Exception <class 'AttributeError'>: module 'gdb' has no attribute
'_handle_missing_debuginfo'
Tested by using make check-all-boards.
Co-Authored-By: Jan Kratochvil <jan.kratochvil@redhat.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
A while ago, an AdaCore user reported some difficulties with the
'define' command. While some of these difficulties are intrinsic, or
at least difficult to change, it seemed sensible to document a couple
of the typical problems -- and to make the text describing argument
substitution a bit more prominent.
Approved-By: Eli Zaretskii <eliz@gnu.org>
This commit adds the GDB side of target_ops::fileio_stat. There's an
implementation for inf_child_target, which just calls 'lstat', and
there's an implementation for remote_target, which sends a new
vFile:stat packet.
The new packet is documented.
There's still no users of target_fileio_stat as I have not yet added
support for vFile::stat to gdbserver. If these packets are currently
sent to gdbserver then they will be reported as not supported and the
ENOSYS error code will be returned.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
I noticed that the 'all-doc' build target doesn't build all the doc
formats, 'man' and 'html' are missing.
This commit updates 'all-doc' so that all formats are built.
This doesn't change the default 'all' target, which is the default
target used when building GDB itself, the 'all' target continues to
just build the 'info' docs.
There should be no difference in the actual generated output after
this commit, I'm just changing what gets built.
Approved-By: Tom Tromey <tom@tromey.com>
After this commit:
commit 0700386f14 (gdb-tmp-c)
Date: Wed May 8 19:12:57 2024 +0100
gdb/doc: fix parallel build of pdf and dvi files
When building the dvi or pdf targets you'd get errors like this:
mkdir: cannot create directory ‘texi2dvi_tmpdir/gdb_dvi’: No such file or directory
mkdir: cannot create directory ‘texi2dvi_tmpdir/gdb_pdf’: No such file or directory
fixed by ensuring the directory is created before calling texi2dvi.
When building with 'make -j20 -C gdb/doc all-doc' I often see problems
caused from trying to build some dvi files in parallel with some pdf
files. The problem files are: gdb.dvi and gdb.pdf; stabs.dvi and
stabs.pdf; and annotate.dvi and annotate.pdf.
The problem is that building these files create temporary files in the
local directory. There's already a race here that two make threads
might try to create these files at the same time.
But it gets worse, to avoid issues where a failed build could leave
these temporary files in a corrupted state, and so prevent the next
build from succeeding, the recipe for each of these files deletes all
the temporary files first, this obviously causes problems if some
other thread has already started the build and is relying on these
temporary files.
To work around this problem I propose we start using the --build and
--build-dir options for texi2dvi (which is the same tool used to
create the pdf files). These options were added in texinfo 4.9 which
was released in June 2007. We already require using a version of
texinfo after 4.9 (I tried to build with 4.13 and the doc build failed
as some of the texinfo constructs were not understood), so this patch
has not changed the minimum required version at all.
The --build flag allows the temporary files to be placed into a
sub-directory, and the --build-dir option allows us to control the
name of that sub-directory.
What we do is create a unique sub-directory for each target that
invokes texi2dvi, all of the unique sub-directories are created within
a single directory texi2dvi_tmpdir, and so after a complete doc build,
we are left with a build tree like this:
build/gdb/doc/
'-- texi2dvi_tmpdir/
|-- annotate_dvi/
|-- annotate_pdf/
|-- gdb_dvi/
|-- gdb_pdf/
|-- stabs_dvi/
'-- stabs_pdf/
I've left out all the individual files that live within these
directories for simplicity.
To avoid corrupted temporary files preventing a future build to
complete, each recipe deletes its associated sub-directory from within
texi2dvi_tmpdir/ before it attempts a build, this ensures a fresh
start each time.
And the mostlyclean target deletes texi2dvi_tmpdir/ and all its
sub-directories, ensuring that everything is cleaned up.
For me, with this fix in place, I can now run 'make -j20 -C gdb/doc
all-doc' without seeing any build problems.
Approved-By: Pedro Alves <pedro@palves.net>
There are two problems we encounter when trying to build the refcard
related target in parallel, i.e.:
$ make -j20 -C gdb/doc/ refcard.dvi refcard.ps refcard.pdf
These problems are:
(1) The refcard.dvi and refcard.pdf targets both try and generate the
tmp.sed and sedref.tex files. If two make threads end up trying
to create these files at the same time then the result is these
files become corrupted.
I've fixed this by creating a new rule that creates sedref.tex,
both refcard.dvi and refcard.pdf now depend on this, and make will
build sedref.tex just once. The tmp.sed file is now generated as
refcard.sed, this is generated and deleted as a temporary file
within the sedref.tex recipe.
(2) Having created sedref.tex the recipes for refcard.dvi and
refcard.pdf both run various LaTeX based tools with sedref.tex as
the input file. The problem with this is that these tools all
rely on creating temporary files calls sedref.*.
If the refcard.dvi and refcard.pdf rules run at the same time then
these temporary files clash and overwrite each other causing the
build to fail.
We already copy the result file in order to rename it, our input
file is sedref.tex which results in an output file named
sedref.dvi or sedref.pdf, but we actually want refcard.dvi or
refcard.pdf. So within the recipe for refcard.dvi I copy the
input file from sedref.tex to sedref_dvi.tex. Now all the temp
files are named sedref_dvi.* and the output is sedref_dvi.dvi, I
then rename this new output file to refcard.dvi.
I've done the same thing for refcard.pdf, but I copy the input
to sedref_pdf.tex.
In this way the temp files no longer clash, and both recipes can
safely run in parallel.
After this commit I was able to reliably build all of the refcard
targets in parallel. There should be no change in the final file.
Approved-By: Tom Tromey <tom@tromey.com>
In gdb/doc/Makefile.in the TEXI2POD variable is used to invoke
texi2pod.pl, which process the .texinfo files. This also handles the
'include' directives within the .texinfo files.
Like the texi2dvi and texi2pdf tools, texi2pod.pl handles the -I flag
to add search directories for resolving 'include' directives within
.texinfo files.
When GDB runs TEXI2POD we include gdb-cfg.texi, which then includes
GDBvn.texi.
When building from a git checkout the gdb-cfg.texi files and
GDBvn.texi files will be created in the build directory, which is
where texi2pod.pl is invoked, so the files will be found just fine.
However, for a GDB release we ship gdb-cfg.texi and GDBvn.texi in the
source tree, along with the generated manual (.1 and .5) files.
So when building a release, what normally happens is that we spot that
the .1 and .5 man files are up to date, and don't run the recipe to
regenerate these files.
However, if we deliberately touch the *.texinfo files in a release
source tree, and then try to rebuild the man files, we'll get an error
like this:
make: Entering directory '/tmp/release-build/build/gdb/doc'
TEXI2POD gdb.1
cannot find GDBvn.texi at ../../../gdb-16.0.50.20240529/gdb/doc/../../etc/texi2pod.pl line 251, <GEN0> line 16.
make: *** [Makefile:664: gdb.1] Error 2
make: Leaving directory '/tmp/release-build/build/gdb/doc'
The problem is that texi2pod.pl doesn't know to look in the source
tree for the GDBvn.texi file.
If we compare this to the recipe for creating (for example) gdb.dvi,
which uses texi2dvi, this recipe adds '-I $(srcdir)' to the texi2dvi
command line, which allows texi2dvi to find GDBvn.texi in the source
tree.
In this commit I add a similar -I option to the texi2pod.pl command
line. After this, given a GDB release, it is possible to edit (or
just touch) the gdb.texinfo file and rebuild the man pages, the
GDBvn.texi will be picked up from the source tree.
If however a dependency for GDBvn.texi is changed in a release tree
then GDBvn.texi will be regenerated into the build directory and this
will be picked up in preference to the GDBvn.texi in the source tree,
just as you would want.
Approved-By: Tom Tromey <tom@tromey.com>
In a git checkout of the source code we don't have a version.subst
file in the gdb/doc directory. When building the GDB docs the
version.subst file is generated on demand (we have a recipe for that).
However, in a release tar file we do include a copy of the
version.subst file in the source tree, as a result the version.subst
recipe will not be run.
If, in a release build, we force the running of any recipe that
depends on version.subst then we run into a problem. For example,
slightly confusingly, if we 'touch gdb/doc/version.subst' within the
unpacked source tree of a release, then 'make -C gdb/doc GDBvn.texi'
in the build tree, we'll see:
make: Entering directory '/tmp/build/build/gdb/doc'
GEN GDBvn.texi
sed: can't read version.subst: No such file or directory
make: Leaving directory '/tmp/build/build/gdb/doc'
The problem is that every reference to version.subst in GDB's Makefile
assumes that the version.subst file will always be in the build
directory.
Handily version.subst is always the first dependency in every recipe
that uses that file. As such we can replace references to
version.subst with $<, make will expand this to the location where the
dependency was found.
In the case of the man page generation, the reference to version.subst
is hidden inside POD2MAN. It seemed a little confusing adding a use
of $< within POD2MAN, so I've moved the use into the recipe, which I
think is clearer.
I've also added comments for the two rules that I've modified to
explain our use of $<.
After this change it is possible to rebuild the man pages even when
version.subst is located in the source tree.
Approved-By: Tom Tromey <tom@tromey.com>
We have two rules, one each for building the .1 and .5 man pages. The
only actual difference is that one rule passes --section=1 and the
other passes --section=5 (see the definitions of POD2MAN1 and POD2MAN5
respectively.
I figure by using the suffix from the target of the rule we can
combine these two rules into one.
I use:
$(subst .,,$(suffix $@))
This gets the suffix from the target, either '.1' or '.5', and the
'subst' removes the '.' leaving '1' or '5'.
Now that I'm not using a static pattern rule for building the man
pages, the advice in the 'make' documentation is to not use $*, so
I've moved away from that to instead use $(basename $@), e.g. for
'gdbinit.5' this gives 'gdbinit', which is what we want.
There should be no difference in what is created after this change.
Approved-By: Tom Tromey <tom@tromey.com>
