[lldb][Docs] Add equivalents of GDB's "skip" to command map

[DavidSpickett]

https://sourceware.org/gdb/current/onlinedocs/gdb.html/Skipping-Over-Functions-and-Files.html

We can't emulate all the features of that command but we can skip a function by name with some extra steps.

As far as I know this only matches function name unlike GDB that can filter on file and line and so on:

target.process.thread.step-avoid-regexp -- A regular expression defining functions step-in won't stop in.

It's likely it's got some corner cases that don't work, maybe inlining, but it doesn't seem worth going into it here.

I don't think we can chain lldb interpreter commands, so I have shown the steps separately.

I have also mentioned thread step-in and its alias sif. Which were new to me too.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

Changes

https://sourceware.org/gdb/current/onlinedocs/gdb.html/Skipping-Over-Functions-and-Files.html

We can't emulate all the features of that command but we can skip a function by name with some extra steps.

As far as I know this only matches function name unlike GDB that can filter on file and line and so on:

target.process.thread.step-avoid-regexp -- A regular expression defining functions step-in won't stop in.

It's likely it's got some corner cases that don't work, maybe inlining, but it doesn't seem worth going into it here.

I don't think we can chain lldb interpreter commands, so I have shown the steps separately.

---

Full diff: https://github.com/llvm/llvm-project/pull/120740.diff

1 Files Affected:

• (modified) lldb/docs/use/map.rst (+17)

diff --git a/lldb/docs/use/map.rst b/lldb/docs/use/map.rst
index fe9c3f53022fad..cb1c266078679e 100644
--- a/lldb/docs/use/map.rst
+++ b/lldb/docs/use/map.rst
@@ -235,6 +235,23 @@ Do a source level single step in the currently selected thread
   (lldb) step
   (lldb) s
 
+Ignore a function when doing a source level single step in
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: shell
+
+  (gdb) skip abc
+  Function abc will be skipped when stepping.
+
+.. code-block:: shell
+
+  (lldb) settings show target.process.thread.step-avoid-regexp
+  target.process.thread.step-avoid-regexp (regex) = ^std::
+  (lldb) settings set target.process.thread.step-avoid-regexp (^std::)|(^abc)
+
+Get the default value, make it into a capture group, then add another capture
+group for the new function name.
+
 Do a source level single step over in the currently selected thread
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

[DavidSpickett]

And you could make a custom command to do this of course, but my goal here is not to do that. I was just asked by someone whether we had anything at all like this and the command map is the first place I always check.

[kastiglione]

Should this also mention sif? When I want to skip one or more functions when stepping, I run sif desiredFunction.

[DavidSpickett]

Should this also mention sif?

I just learned that it exists, so yes!

[kastiglione]

for anyone interested: I override s to take an optional argument, so that it behaves like sif. In my .lldbinit:

command unalias s
command regex s
s/^$/step/
s/(.+)/sif %1/

[kastiglione]

thanks!

[jimingham]

This isn't directly relevant, but internally lldb has a "ShouldStopHere" mechanism that was meant to be extendable. Currently all the behaviors like the "library & regex avoid" settings are implemented in the DefaultShouldStopHere, but it wouldn't be terribly hard to add a more capable mechanism here, or even add a Python affordance so people could write their own logic.