[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
mgorny requested changes to this revision. mgorny added inline comments. This revision now requires changes to proceed. Comment at: lldb/docs/testsuite/best-practices.rst:19 + +:: + …seems to be a common pattern in LLVM. (and similarly for other instances of `::`) Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108812/new/ https://reviews.llvm.org/D108812 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108807: [LLDB][Docs] Convert links.md & lldb-for-gdb-users.txt file to respective .rst files
mgorny added inline comments. Comment at: lldb/docs/use/lldb-for-gdb-users.rst:40 + +> (lldb) process launch -- -program_arg value This style looks a bit weird. Any reason not to use indentation instead of `>`? Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108807/new/ https://reviews.llvm.org/D108807 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108807: [LLDB][Docs] Convert links.md & lldb-for-gdb-users.txt file to respective .rst files
xgupta updated this revision to Diff 369251. xgupta added a comment. remove extra ">" Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108807/new/ https://reviews.llvm.org/D108807 Files: lldb/docs/lldb-for-gdb-users.txt lldb/docs/use/links.md lldb/docs/use/links.rst lldb/docs/use/lldb-for-gdb-users.rst Index: lldb/docs/use/lldb-for-gdb-users.rst === --- lldb/docs/use/lldb-for-gdb-users.rst +++ lldb/docs/use/lldb-for-gdb-users.rst @@ -1,8 +1,14 @@ +LLDB for GDB users +== + Here's a short precis of how to run lldb if you are familiar with the gdb command set: +.. contents:: + :local: -1) LLDB Command Structure: +LLDB Command Structure: +--- First some details on lldb command structure to help orient you... @@ -10,6 +16,8 @@ the lldb command syntax fairly structured. The commands are all of the form +:: + [-options [option-value]] [argument [argument...]] The command line parsing is done before command execution, so it is @@ -27,6 +35,8 @@ arguments are the arguments you are passing to the program. So if you wanted to pass an argument that contained a "-" you would have to do: +:: + (lldb) process launch -- -program_arg value We also tried to reduce the number of special purpose argument @@ -35,10 +45,14 @@ this is the breakpoint command. In gdb, to set a breakpoint, you would just say: +:: + (gdb) break foo.c:12 or +:: + (gdb) break foo if foo is a function. As time went on, the parser that tells foo.c:12 @@ -48,24 +62,34 @@ you want to break on. The lldb commands are more verbose but also precise. So you say: +:: + (lldb) breakpoint set -f foo.c -l 12 to set a file & line breakpoint. To set a breakpoint on a function by name, you do: +:: + (lldb) breakpoint set -n foo This can allow us to be more expressive, so you can say: +:: + (lldb) breakpoint set -M foo to break on all C++ methods named foo, or: +:: + (lldb) breakpoint set -S alignLeftEdges: to set a breakpoint on all ObjC selectors called alignLeftEdges:. It also makes it easy to compose specifications, like: +:: + (lldb) breakpoint set -s foo.dylib -n foo for all functions called foo in the shared library foo.dylib. Suggestions @@ -73,12 +97,16 @@ So for instance: +:: + (lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]" Just like gdb, the lldb command interpreter does a shortest unique string match on command names, so the previous command can also be typed: +:: + (lldb) b s -n "-[SKTGraphicView alignLeftEdges:]" lldb also supports command completion for source file names, symbol @@ -97,10 +125,14 @@ Finally, there is a mechanism to construct aliases for commonly used commands. So for instance if you get annoyed typing +:: + (lldb) b s -f foo.c -l 12 you can do: +:: + (lldb) command alias bfl breakpoint set -f %1 -l %2 (lldb) bfl foo.c 12 @@ -126,40 +158,48 @@ with the "script" command. - -2) A typical session: - +A typical session: +-- a) Setting the program to debug: + As with gdb, you can start lldb and specify the file you wish to debug on the command line: -$ lldb /Projects/Sketch/build/Debug/Sketch.app -Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). +:: + + lldb /Projects/Sketch/build/Debug/Sketch.app + Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). or you can specify it after the fact with the "file" command: -(lldb) file /Projects/Sketch/build/Debug/Sketch.app -Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). +:: + (lldb) file /Projects/Sketch/build/Debug/Sketch.app + Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). -b) Setting breakpoints: +b) Setting breakpoints: +``` We've discussed how to set breakpoints above. You can use "help break set" to see all the options for breakpoint setting. For instance, we might do: -(lldb) b s -S alignLeftEdges: -Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 +:: + + (lldb) b s -S alignLeftEdges: + Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 You can find out about the breakpoints you've set with: -(lldb) break list -Current breakpoints: -1: name = 'alignLeftEdges:', locations = 1, resolved = 1 - 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x000100010d5b, resolved, hit count = 0 +:: + + (lldb) break list + Current breakpoints: + 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 + 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x000100010d5b, resolved, hit count = 0 Not
[Lldb-commits] [PATCH] D108807: [LLDB][Docs] Convert links.md & lldb-for-gdb-users.txt file to respective .rst files
xgupta added inline comments. Comment at: lldb/docs/use/lldb-for-gdb-users.rst:40 + +> (lldb) process launch -- -program_arg value mgorny wrote: > This style looks a bit weird. Any reason not to use indentation instead of > `>`? Yes, I mistakenly followed https://lldb.llvm.org/resources/build.html style, corrected it now. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108807/new/ https://reviews.llvm.org/D108807 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108807: [LLDB][Docs] Convert links.md & lldb-for-gdb-users.txt file to respective .rst files
mgorny accepted this revision. mgorny added a comment. This revision is now accepted and ready to land. Presuming you've verified that it renders correctly, LGTM. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108807/new/ https://reviews.llvm.org/D108807 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
xgupta updated this revision to Diff 369252.
xgupta added a comment.
Fix .. code-block::
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D108812/new/
https://reviews.llvm.org/D108812
Files:
lldb/docs/testsuite/best-practices.rst
lldb/docs/testsuite/best-practices.txt
Index: lldb/docs/testsuite/best-practices.txt
===
--- lldb/docs/testsuite/best-practices.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-This document attempts to point out some best practices that prove to be helpful
-when building new test cases in the tot/test directory. Everyone is welcomed to
-add/modify contents into this file.
-
-o Do not use hard-coded line numbers in your test case. Instead, try to tag the
- line with some distinguishing pattern, and use the function line_number()
- defined in lldbtest.py which takes filename and string_to_match as arguments
- and returns the line number.
-
-As an example, take a look at test/breakpoint_conditions/main.c which has these
-two lines:
-
-return c(val); // Find the line number of c's parent call here.
-
-and
-
-return val + 3; // Find the line number of function "c" here.
-
-The Python test case TestBreakpointConditions.py uses the comment strings to
-find the line numbers during setUp(self) and use them later on to verify that
-the correct breakpoint is being stopped on and that its parent frame also has
-the correct line number as intended through the breakpoint condition.
-
-o Take advantage of the unittest framework's decorator features to properly
- mark your test class or method for platform-specific tests.
-
-As an example, take a look at test/forward/TestForwardDeclaration.py which has
-these lines:
-
-@unittest2.skipUnless(sys.platform.startswith("darwin"), "requires Darwin")
-def test_with_dsym_and_run_command(self):
-"""Display *bar_ptr when stopped on a function with forward declaration of struct bar."""
-self.buildDsym()
-self.forward_declaration()
-
-This tells the test harness that unless we are running "darwin", the test should
-be skipped. This is because we are asking to build the binaries with dsym debug
-info, which is only available on the darwin platforms.
-
-o Cleanup after yourself. A classic example of this can be found in test/types/
- TestFloatTypes.py:
-
-def test_float_types_with_dsym(self):
-"""Test that float-type variables are displayed correctly."""
-d = {'CXX_SOURCES': 'float.cpp'}
-self.buildDsym(dictionary=d)
-self.setTearDownCleanup(dictionary=d)
-self.float_type()
-
-...
-
-def test_double_type_with_dsym(self):
-"""Test that double-type variables are displayed correctly."""
-d = {'CXX_SOURCES': 'double.cpp'}
-self.buildDsym(dictionary=d)
-self.setTearDownCleanup(dictionary=d)
-self.double_type()
-
-This tests different data structures composed of float types to verify that what
-the debugger prints out matches what the compiler does for different variables
-of these types. We're using a dictionary to pass the build parameters to the
-build system. After a particular test instance is done, it is a good idea to
-clean up the files built. This eliminates the chance that some leftover files
-can interfere with the build phase for the next test instance and render it
-invalid.
-
-TestBase.setTearDownCleanup(self, dictionary) defined in lldbtest.py is created
-to cope with this use case by taking the same build parameters in order to do
-the cleanup when we are finished with a test instance, during
-TestBase.tearDown(self).
-
-o Class-wise cleanup after yourself.
-
-TestBase.tearDownClass(cls) provides a mechanism to invoke the platform-specific
-cleanup after finishing with a test class. A test class can have more than one
-test methods, so the tearDownClass(cls) method gets run after all the test
-methods have been executed by the test harness.
-
-The default cleanup action performed by the plugins/darwin.py module invokes the
-"make clean" os command.
-
-If this default cleanup is not enough, individual class can provide an extra
-cleanup hook with a class method named classCleanup , for example,
-in test/breakpoint_command/TestBreakpointCommand.py:
-
-@classmethod
-def classCleanup(cls):
-system(["/bin/sh", "-c", "rm -f output.txt"])
-
-The 'output.txt' file gets generated during the test run, so it makes sense to
-explicitly spell out the action in the same TestBreakpointCommand.py file to do
-the cleanup instead of artificially adding it as part of the default cleanup
-action which serves to cleanup those intermediate and a.out files.
Index: lldb/docs/testsuite/best-practices.rst
===
--- /dev/null
+++ lldb/docs/testsuite/best-practices.rst
@@ -0,0 +1,109 @@
+Best practices in writing testcases for LLDB
+===
[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
xgupta added inline comments. Comment at: lldb/docs/testsuite/best-practices.rst:19 + +:: + mgorny wrote: > …seems to be a common pattern in LLVM. > > (and similarly for other instances of `::`) Thanks, I missed that. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108812/new/ https://reviews.llvm.org/D108812 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
mgorny accepted this revision. mgorny added a comment. This revision is now accepted and ready to land. Thanks for doing this. Presuming you've verified that it renders correctly, LGTM. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108812/new/ https://reviews.llvm.org/D108812 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108807: [LLDB][Docs] Convert links.md & lldb-for-gdb-users.txt file to respective .rst files
xgupta updated this revision to Diff 369253. xgupta added a comment. Herald added a subscriber: arphaman. add lldb-for-gdb-users entry to index.rst Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108807/new/ https://reviews.llvm.org/D108807 Files: lldb/docs/index.rst lldb/docs/lldb-for-gdb-users.txt lldb/docs/use/links.md lldb/docs/use/links.rst lldb/docs/use/lldb-for-gdb-users.rst Index: lldb/docs/use/lldb-for-gdb-users.rst === --- lldb/docs/use/lldb-for-gdb-users.rst +++ lldb/docs/use/lldb-for-gdb-users.rst @@ -1,8 +1,14 @@ +LLDB for GDB users +== + Here's a short precis of how to run lldb if you are familiar with the gdb command set: +.. contents:: + :local: -1) LLDB Command Structure: +LLDB Command Structure: +--- First some details on lldb command structure to help orient you... @@ -10,6 +16,8 @@ the lldb command syntax fairly structured. The commands are all of the form +:: + [-options [option-value]] [argument [argument...]] The command line parsing is done before command execution, so it is @@ -27,6 +35,8 @@ arguments are the arguments you are passing to the program. So if you wanted to pass an argument that contained a "-" you would have to do: +:: + (lldb) process launch -- -program_arg value We also tried to reduce the number of special purpose argument @@ -35,10 +45,14 @@ this is the breakpoint command. In gdb, to set a breakpoint, you would just say: +:: + (gdb) break foo.c:12 or +:: + (gdb) break foo if foo is a function. As time went on, the parser that tells foo.c:12 @@ -48,24 +62,34 @@ you want to break on. The lldb commands are more verbose but also precise. So you say: +:: + (lldb) breakpoint set -f foo.c -l 12 to set a file & line breakpoint. To set a breakpoint on a function by name, you do: +:: + (lldb) breakpoint set -n foo This can allow us to be more expressive, so you can say: +:: + (lldb) breakpoint set -M foo to break on all C++ methods named foo, or: +:: + (lldb) breakpoint set -S alignLeftEdges: to set a breakpoint on all ObjC selectors called alignLeftEdges:. It also makes it easy to compose specifications, like: +:: + (lldb) breakpoint set -s foo.dylib -n foo for all functions called foo in the shared library foo.dylib. Suggestions @@ -73,12 +97,16 @@ So for instance: +:: + (lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]" Just like gdb, the lldb command interpreter does a shortest unique string match on command names, so the previous command can also be typed: +:: + (lldb) b s -n "-[SKTGraphicView alignLeftEdges:]" lldb also supports command completion for source file names, symbol @@ -97,10 +125,14 @@ Finally, there is a mechanism to construct aliases for commonly used commands. So for instance if you get annoyed typing +:: + (lldb) b s -f foo.c -l 12 you can do: +:: + (lldb) command alias bfl breakpoint set -f %1 -l %2 (lldb) bfl foo.c 12 @@ -126,40 +158,48 @@ with the "script" command. - -2) A typical session: - +A typical session: +-- a) Setting the program to debug: + As with gdb, you can start lldb and specify the file you wish to debug on the command line: -$ lldb /Projects/Sketch/build/Debug/Sketch.app -Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). +:: + + lldb /Projects/Sketch/build/Debug/Sketch.app + Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). or you can specify it after the fact with the "file" command: -(lldb) file /Projects/Sketch/build/Debug/Sketch.app -Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). +:: + (lldb) file /Projects/Sketch/build/Debug/Sketch.app + Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). -b) Setting breakpoints: +b) Setting breakpoints: +``` We've discussed how to set breakpoints above. You can use "help break set" to see all the options for breakpoint setting. For instance, we might do: -(lldb) b s -S alignLeftEdges: -Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 +:: + + (lldb) b s -S alignLeftEdges: + Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 You can find out about the breakpoints you've set with: -(lldb) break list -Current breakpoints: -1: name = 'alignLeftEdges:', locations = 1, resolved = 1 - 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x000100010d5b, resolved, hit count = 0 +:: + + (lldb) break list + Current breakpoints: + 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 + 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch
[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
xgupta updated this revision to Diff 369254.
xgupta added a comment.
Herald added a subscriber: arphaman.
add best-practices entry to index.rst
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D108812/new/
https://reviews.llvm.org/D108812
Files:
lldb/docs/index.rst
lldb/docs/testsuite/best-practices.rst
lldb/docs/testsuite/best-practices.txt
Index: lldb/docs/testsuite/best-practices.txt
===
--- lldb/docs/testsuite/best-practices.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-This document attempts to point out some best practices that prove to be helpful
-when building new test cases in the tot/test directory. Everyone is welcomed to
-add/modify contents into this file.
-
-o Do not use hard-coded line numbers in your test case. Instead, try to tag the
- line with some distinguishing pattern, and use the function line_number()
- defined in lldbtest.py which takes filename and string_to_match as arguments
- and returns the line number.
-
-As an example, take a look at test/breakpoint_conditions/main.c which has these
-two lines:
-
-return c(val); // Find the line number of c's parent call here.
-
-and
-
-return val + 3; // Find the line number of function "c" here.
-
-The Python test case TestBreakpointConditions.py uses the comment strings to
-find the line numbers during setUp(self) and use them later on to verify that
-the correct breakpoint is being stopped on and that its parent frame also has
-the correct line number as intended through the breakpoint condition.
-
-o Take advantage of the unittest framework's decorator features to properly
- mark your test class or method for platform-specific tests.
-
-As an example, take a look at test/forward/TestForwardDeclaration.py which has
-these lines:
-
-@unittest2.skipUnless(sys.platform.startswith("darwin"), "requires Darwin")
-def test_with_dsym_and_run_command(self):
-"""Display *bar_ptr when stopped on a function with forward declaration of struct bar."""
-self.buildDsym()
-self.forward_declaration()
-
-This tells the test harness that unless we are running "darwin", the test should
-be skipped. This is because we are asking to build the binaries with dsym debug
-info, which is only available on the darwin platforms.
-
-o Cleanup after yourself. A classic example of this can be found in test/types/
- TestFloatTypes.py:
-
-def test_float_types_with_dsym(self):
-"""Test that float-type variables are displayed correctly."""
-d = {'CXX_SOURCES': 'float.cpp'}
-self.buildDsym(dictionary=d)
-self.setTearDownCleanup(dictionary=d)
-self.float_type()
-
-...
-
-def test_double_type_with_dsym(self):
-"""Test that double-type variables are displayed correctly."""
-d = {'CXX_SOURCES': 'double.cpp'}
-self.buildDsym(dictionary=d)
-self.setTearDownCleanup(dictionary=d)
-self.double_type()
-
-This tests different data structures composed of float types to verify that what
-the debugger prints out matches what the compiler does for different variables
-of these types. We're using a dictionary to pass the build parameters to the
-build system. After a particular test instance is done, it is a good idea to
-clean up the files built. This eliminates the chance that some leftover files
-can interfere with the build phase for the next test instance and render it
-invalid.
-
-TestBase.setTearDownCleanup(self, dictionary) defined in lldbtest.py is created
-to cope with this use case by taking the same build parameters in order to do
-the cleanup when we are finished with a test instance, during
-TestBase.tearDown(self).
-
-o Class-wise cleanup after yourself.
-
-TestBase.tearDownClass(cls) provides a mechanism to invoke the platform-specific
-cleanup after finishing with a test class. A test class can have more than one
-test methods, so the tearDownClass(cls) method gets run after all the test
-methods have been executed by the test harness.
-
-The default cleanup action performed by the plugins/darwin.py module invokes the
-"make clean" os command.
-
-If this default cleanup is not enough, individual class can provide an extra
-cleanup hook with a class method named classCleanup , for example,
-in test/breakpoint_command/TestBreakpointCommand.py:
-
-@classmethod
-def classCleanup(cls):
-system(["/bin/sh", "-c", "rm -f output.txt"])
-
-The 'output.txt' file gets generated during the test run, so it makes sense to
-explicitly spell out the action in the same TestBreakpointCommand.py file to do
-the cleanup instead of artificially adding it as part of the default cleanup
-action which serves to cleanup those intermediate and a.out files.
Index: lldb/docs/testsuite/best-practices.rst
===
--- /dev/null
+++ lldb/docs/testsuite/best-practices.rst
@@ -0,0
[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
xgupta added a comment. I can confirm that it renders correctly, please commit it at your convenience. Thanks. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108812/new/ https://reviews.llvm.org/D108812 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108807: [LLDB][Docs] Convert links.md & lldb-for-gdb-users.txt file to respective .rst files
xgupta added a comment. I can confirm that it renders correctly, please commit it at your convenience. Thanks. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108807/new/ https://reviews.llvm.org/D108807 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [PATCH] D108812: [LLDB][Docs] Renew best-practices.txt
teemperor added inline comments. Comment at: lldb/docs/testsuite/best-practices.rst:53 + +Cleanup after yourself +-- This section here seems very outdated, can we just delete it? Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D108812/new/ https://reviews.llvm.org/D108812 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
