Author: David Spickett Date: 2025-02-03T09:10:20Z New Revision: 5d738b2be051bf800445fb21df6de163af35695f
URL: https://github.com/llvm/llvm-project/commit/5d738b2be051bf800445fb21df6de163af35695f DIFF: https://github.com/llvm/llvm-project/commit/5d738b2be051bf800445fb21df6de163af35695f.diff LOG: [lldb][Docs] Expand remote testing instructions (#122694) There's a lot of fiddly bits to get right here, so I've added a more complete example and explained why you might choose one method over another. I thought about adding this to the qemu testing page, as that's what we (Linaro) use this for mostly, but it applies to any remote system whether hardware or simulator. Added: Modified: lldb/docs/resources/test.rst Removed: ################################################################################ diff --git a/lldb/docs/resources/test.rst b/lldb/docs/resources/test.rst index 5f1bd0d5738305..1272aeeeb969e3 100644 --- a/lldb/docs/resources/test.rst +++ b/lldb/docs/resources/test.rst @@ -586,24 +586,60 @@ To run a specific test, pass a filter, for example: Running the Test Suite Remotely ``````````````````````````````` -Running the test-suite remotely is similar to the process of running a local -test suite, but there are two things to have in mind: - -1. You must have the lldb-server running on the remote system, ready to accept - multiple connections. For more information on how to setup remote debugging - see the Remote debugging page. -2. You must tell the test-suite how to connect to the remote system. This is - achieved using the ``LLDB_TEST_PLATFORM_URL``, ``LLDB_TEST_PLATFORM_WORKING_DIR`` - flags to cmake, and ``--platform-name`` parameter to ``dotest.py``. - These parameters correspond to the platform select and platform connect - LLDB commands. You will usually also need to specify the compiler and - architecture for the remote system. -3. Remote Shell tests execution is currently supported only for Linux target - platform. It's triggered when ``LLDB_TEST_SYSROOT`` is provided for building - test sources. It can be disabled by setting ``LLDB_TEST_SHELL_DISABLE_REMOTE=On``. - Shell tests are not guaranteed to pass against remote target if the compiler - being used is other than Clang. +1. Run lldb-server on the remote system, so that it can accept multiple connections. + This is called "platform" mode: + :: + + lldb-server platform --server --listen 0.0.0.0:<port A> --gdbserver-port <port B> + + Assuming that ``port A`` and ``port B`` on the remote system can be reached + from your host system. If your remote system is a simulator on your host machine, + you may need to forward these ports to the host when you start the simulator. + + For more information on how to setup remote debugging see :doc:`/use/remote`. + +2. Tell the test-suite how to connect to the remote system. This is done using the + ``LLDB_TEST_PLATFORM_URL`` and ``LLDB_TEST_PLATFORM_WORKING_DIR`` flags of CMake, + or the ``--platform-name``, ``--platform-url`` and ``--platform-working-dir`` + parameters of ``dotest.py``. These parameters are passed on to the ``platform select`` + and ``platform connect`` LLDB commands when the tests are run. + + You will usually need to specify the compiler and architecture for the + remote system. This is done with CMake options ``LLDB_TEST_COMPILER`` and + ``LLDB_TEST_ARCH``, or the ``dotest.py`` options ``--compiler`` and ``--arch``. + + .. note:: + Even in cases where the two systems are the same architecture and run the + same operating system, there may be version diff erences between the two + which require you to use a diff erent compiler version for remote testing. + + For example, to run tests using ``dotest.py`` on a remote AArch64 Linux system + you might run: + + :: + + ./bin/lldb-dotest --platform-name remote-linux --arch aarch64 --compiler aarch64-none-linux-gnu-gcc --platform-url connect://<remote-ip>:<port A> --platform-working-dir /tmp/test_lldb -p <test-name>.py + + This is the equivalent of: + + * ``LLDB_TEST_ARCH`` = ``aarch64`` + * ``LLDB_TEST_COMPILER`` = ``aarch64-none-linux-gnu-gcc`` + * ``LLDB_TEST_PLATFORM_URL`` = ``connect://<remote-ip>:<port A>`` + * ``LLDB_TEST_PLATFORM_WORKING_DIR`` = ``/tmp/test_lldb`` + + Setting these values using CMake allows you to run ``ninja check-lldb`` to run + tests on the remote system. + + If you have a host build that you sometimes check on a remote system, but otherwise + test on the host, adding arguments to ``dotest.py`` manually is easier. + +.. note:: + Remote Shell test execution is currently supported only for Linux targets. + It is enabled when ``LLDB_TEST_SYSROOT`` is set. Remote Shell testing can + be disabled by setting ``LLDB_TEST_SHELL_DISABLE_REMOTE=On``. Shell tests + are not guaranteed to pass against remote target if the test compiler is not + Clang. Running tests in QEMU System Emulation Environment `````````````````````````````````````````````````` _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
