Re: [PATCH v6 103/103] docs/devel/testing/: update documentation

On 8/12/2026 4:03 AM, Daniel P. Berrangé wrote:
> On Mon, Jul 27, 2026 at 09:42:47PM -0700, Pierrick Bouvier wrote:
>> We document how to build and run tcg tests with new framework.
>>
>> Reviewed-by: Manos Pitsidianakis <[email protected]>
>> Reviewed-by: Philippe Mathieu-Daudé <[email protected]>
>> Signed-off-by: Pierrick Bouvier <[email protected]>
>> ---
>>  docs/devel/build-system.rst |  4 ++--
>>  docs/devel/testing/main.rst | 33 ++++++++++++++++++++++-----------
>>  2 files changed, 24 insertions(+), 13 deletions(-)
>>
>> diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
>> index 71331e64ac8..c64d40b42af 100644
>> --- a/docs/devel/build-system.rst
>> +++ b/docs/devel/build-system.rst
>> @@ -447,8 +447,8 @@ these sub-Makefiles, the resulting build is largely non-recursive.
>>  Tests, whether defined in ``meson.build`` or not, are also ran by the
>>  Makefile with the traditional ``make check`` phony target, while benchmarks
>>  are run with ``make bench``.  Meson test suites such as ``unit`` can be ran
>> -with ``make check-unit``, and ``make check-tcg`` builds and runs "non-Meson"
>> -tests for all targets.
>> +with ``make check-unit``, and ``make check-tcg`` builds and runs tcg tests
>> +for all targets.
>>  
>>  If desired, it is also possible to use ``ninja`` and ``pyvenv/bin/meson test``,
>>  respectively to build emulators and run tests defined in meson.build.
>> diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
>> index c6821a36d99..9cbac144fdd 100644
>> --- a/docs/devel/testing/main.rst
>> +++ b/docs/devel/testing/main.rst
>> @@ -1035,29 +1035,40 @@ See :ref:`container-ref` for more details.
>>  Running subset of tests
>>  ~~~~~~~~~~~~~~~~~~~~~~~
>>  
>> -You can build the tests for one architecture::
>> +You can build the tcg tests using::
>>  
>> -  make build-tcg-tests-$TARGET
>> +  make tcg-tests
>>  
>> -And run with::
>> +And run them for one target with::
>>  
>> -  make run-tcg-tests-$TARGET
>> +  make check-tcg-$TARGET
>>  
>>  Adding ``V=1`` to the invocation will show the details of how to
>>  invoke QEMU for the test which is useful for debugging tests.
>>  
>> +Tests can also be run using directly meson test::
>> +
>> +  ./pyvenv/bin/meson test --suite tcg
>> +  ./pyvenv/bin/meson test --suite tcg-$TARGET
> 
> For any binary that lives within the build dir, it is sufficient
> to use the 'run' script which sets $PATH to search all build dir
> locations, including the python venv.
> 
> IOW, this command should be just
> 
>    ./run meson test .....
>

Good idea.

> Or probably slightly better as
> 
>   $BUILD-DIR/run meson test ...
> 
> to avoid the docs assumption that the user's CWD is at the root
> of the build dir.
>

This assumption is probably fair, given all the commands in doc we give
either are ran from src root or build root folder anyway.

>> +
>> +Tests can be listed using::
>> +
>> +  ./pyvenv/bin/meson test --suite tcg --list
>> +
>>  Running individual tests
>>  ~~~~~~~~~~~~~~~~~~~~~~~~
>>  
>> -Tests can also be run directly from the test build directory. If you
>> -run ``make help`` from the test build directory you will get a list of
>> -all the tests that can be run. Please note that same binaries are used
>> -in multiple tests, for example::
>> +Tests can also be run using directly meson test::
>>  
>> -  make run-plugin-test-mmap-with-libinline.so
>> +  ./pyvenv/bin/meson test $TARGET-$TEST
>>  
>> -will run the mmap test with the ``libinline.so`` TCG plugin. The
>> -gdbstub tests also re-use the test binaries but while exercising gdb.
>> +For instance::
>> +
>> +  ./pyvenv/bin/meson test aarch64-softmmu-hello
>> +
>> +Test command and output can be accessed by using verbose flag::
>> +
>> +  ./pyvenv/bin/meson test aarch64-softmmu-hello --verbose
>>  
>>  TCG test dependencies
>>  ~~~~~~~~~~~~~~~~~~~~~
>> -- 
>> 2.47.3
>>
> 
> With regards,
> Daniel