[Lldb-commits] [lldb] [lldb] Correct documentation of LLDB_TEST_USER_ARGS (PR #89042)

[David Spickett via lldb-commits]

https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/89042

https://discourse.llvm.org/t/running-lldb-in-a-container/76801/4 found that the obvious way to use this variable doesn't work, despite what our docs and examples say.

Perhaps in the past it did but now you need to use ";" as a separator to make sure the final command line works properly.

For example "-A foo" becomes "-A foo" when python goes to run the runner script. The script sees this as one command line element, not two. What you actually want is "-A;foo" which we convert to "-A" "foo" which the script sees as one option and one value for that option.

The "Script:" printout from dotest is misleading here because it does `" ".join(cmd)` so it looks like it's ok but in fact it's not.

I'm not changing that format though because printing the command as a Python list is not useful outside of this specific situation.

>From 424c48e1b53ebfe1119ad09b39f6730d127b254e Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 17 Apr 2024 09:49:37 +0000
Subject: [PATCH] [lldb] Correct documentation of LLDB_TEST_USER_ARGS

https://discourse.llvm.org/t/running-lldb-in-a-container/76801/4 found
that the obvious way to use this variable doesn't work, despite
what our docs and examples say.

Perhaps in the past it did but now you need to use ";" as a separator
to make sure the final command line works properly.

For example "-A foo" becomes "-A foo" when python goes to run the
runner script. The script sees this as one command line element,
not two. What you actually want is "-A;foo" which we convert
to "-A" "foo" which the script sees as one option and one value
for that option.

The "Script:" printout from dotest is misleading here because
it does `" ".join(cmd)` so it looks like it's ok but in fact it's not.

I'm not changing that format though because printing the command as a
Python list is not useful outside of this specific situation.
---
 lldb/docs/resources/test.rst | 25 +++++++++++++++++++++----
 lldb/test/API/CMakeLists.txt |  3 ++-
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/lldb/docs/resources/test.rst b/lldb/docs/resources/test.rst
index 2b0e9010fe280a..094fde8b1b5a0a 100644
--- a/lldb/docs/resources/test.rst
+++ b/lldb/docs/resources/test.rst
@@ -441,23 +441,40 @@ Running the Full Test Suite
 The easiest way to run the LLDB test suite is to use the ``check-lldb`` build
 target.
 
+::
+
+   $ ninja check-lldb
+
+Changing Test Suite Options
+```````````````````````````
+
 By default, the ``check-lldb`` target builds the test programs with the same
 compiler that was used to build LLDB. To build the tests with a different
 compiler, you can set the ``LLDB_TEST_COMPILER`` CMake variable.
 
+You can also add to the test runner options by setting the
+``LLDB_TEST_USER_ARGS`` CMake variable. This variable uses ``;`` to separate
+items which must be separate parts of the runner's command line.
+
 It is possible to customize the architecture of the test binaries and compiler
-used by appending ``-A`` and ``-C`` options respectively to the CMake variable
-``LLDB_TEST_USER_ARGS``. For example, to test LLDB against 32-bit binaries
-built with a custom version of clang, do:
+used by appending ``-A`` and ``-C`` options respectively. For example, to test
+LLDB against 32-bit binaries built with a custom version of clang, do:
 
 ::
 
-   $ cmake -DLLDB_TEST_USER_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja
+   $ cmake -DLLDB_TEST_USER_ARGS="-A;i386;-C;/path/to/custom/clang" -G Ninja
    $ ninja check-lldb
 
 Note that multiple ``-A`` and ``-C`` flags can be specified to
 ``LLDB_TEST_USER_ARGS``.
 
+If you want to change the LLDB settings that tests run with then you can set
+the ``--setting`` option of the test runner via this same variable. For example
+``--setting;target.disable-aslr=true``.
+
+For a full list of test runner options, see
+``<build-dir>/bin/lldb-dotest --help``.
+
 Running a Single Test Suite
 ```````````````````````````
 
diff --git a/lldb/test/API/CMakeLists.txt b/lldb/test/API/CMakeLists.txt
index 4e02112c29e4cd..9196f54ce1ae32 100644
--- a/lldb/test/API/CMakeLists.txt
+++ b/lldb/test/API/CMakeLists.txt
@@ -35,7 +35,8 @@ set(LLDB_TEST_ARCH
 # Users can override LLDB_TEST_USER_ARGS to specify arbitrary arguments to pass to the script
 set(LLDB_TEST_USER_ARGS
   ""
-  CACHE STRING "Specify additional arguments to pass to test runner. For example: '-C gcc -C clang -A i386 -A x86_64'")
+  CACHE STRING "Specify additional arguments to pass to test runner. Seperate \
+items with \";\". For example: '-C;gcc;-C;clang;-A;i386;-A;x86_64'")
 
 set(LLDB_TEST_COMMON_ARGS_VAR
   -u CXXFLAGS