[Lldb-commits] [lldb] [lldb][Docs] Add equivalents of GDB's "skip" to command map (PR #120740)

[David Spickett via lldb-commits]

https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/120740

>From 65de95430fce9315a5d34aec589796818d5cd06f Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 20 Dec 2024 14:38:05 +0000
Subject: [PATCH 1/3] [lldb][Docs] Add equivalent of GDB's "skip" to command
 map

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.
---
 lldb/docs/use/map.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

>From feb68917b39e1ed559ce98350e08a50415ab9b49 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 20 Dec 2024 15:23:44 +0000
Subject: [PATCH 2/3] note thread step-in and sif

---
 lldb/docs/use/map.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/lldb/docs/use/map.rst b/lldb/docs/use/map.rst
index cb1c266078679e..e66b18a2e06fd8 100644
--- a/lldb/docs/use/map.rst
+++ b/lldb/docs/use/map.rst
@@ -252,6 +252,23 @@ Ignore a function when doing a source level single step in
 Get the default value, make it into a capture group, then add another capture
 group for the new function name.
 
+You can ignore a function once using:
+
+.. code-block:: shell
+
+  (lldb) thread step-in -r ^abc
+
+Or you can do the opposite, only step into functions with a certain name:
+
+.. code-block:: shell
+
+  (lldb) sif abc
+  # Which is equivalent to:
+  (lldb) thread step-in -t abc
+
+``thread step-in`` has more options which cover some of ``skip``'s other
+features. See ``help thread step-in`` for details.
+
 Do a source level single step over in the currently selected thread
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

>From fc44d2baf4fd360da926018099d56db6be303e55 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 3 Jan 2025 14:09:58 +0000
Subject: [PATCH 3/3] address review comments

---
 lldb/docs/use/map.rst | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/lldb/docs/use/map.rst b/lldb/docs/use/map.rst
index e66b18a2e06fd8..ed285b2d1f6e90 100644
--- a/lldb/docs/use/map.rst
+++ b/lldb/docs/use/map.rst
@@ -247,10 +247,7 @@ Ignore a function when doing a source level single step in
 
   (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.
+  (lldb) settings set target.process.thread.step-avoid-regexp ^std::|^abc
 
 You can ignore a function once using:
 
@@ -258,10 +255,11 @@ You can ignore a function once using:
 
   (lldb) thread step-in -r ^abc
 
-Or you can do the opposite, only step into functions with a certain name:
+Or you can do the opposite, only step into functions matching a certain name:
 
 .. code-block:: shell
 
+  # Step in if abc is a substring of the function name.
   (lldb) sif abc
   # Which is equivalent to:
   (lldb) thread step-in -t abc