RFR: 7903683 Document how to run individual self-tests [v2]

[Jaikiran Pai]

On Mon, 11 Mar 2024 14:56:18 GMT, Ludvig Janiuk <lujaniuk at openjdk.org> wrote:

>> doc/building.md line 113:
>> 
>>> 111: ```
>>> 112: bash build/make.sh -- $(pwd)/build/test/ControlTest.ok
>>> 113: ```
>> 
>> Hello Ludvig, I think the idea of documenting this is a good one. I myself struggled to find a way to run individual tests until I saw your PR.
>> 
>> As for the proposed text, I think it will still leave open a lot of questions - like, how does one find the right `.ok` target to pass to this command. The answer to that already resides in https://github.com/openjdk/jtreg/blob/master/test/README.md#makefiles. I think as part of the current proposed change, we may have to include a pointer to that other file to provide context about the `.ok` target or maybe just migrate that README.md file contents into this building.md file.
>
> Thanks for the suggestion, I didn't know about that file! I've added a pointer and also borrowed the formulation from there, it sounded better IMO.

Hello Ludvig, this looks better to me. To make it much more clear, I was thinking of something like this:


diff --git a/doc/building.md b/doc/building.md
index 931a519..846b955 100644
--- a/doc/building.md
+++ b/doc/building.md
@@ -107,7 +107,15 @@ of the `legal` directory in the generated image.
 ## Running `jtreg` Self-Tests
 
 The tests can be invoked with individual make targets, or collectively via the
-`test` target.
+`test` target. Individual make targets for self-tests are explained
+[here](../test/README.md#makefiles). For example, the
+[ControlTest.gmk](../test/ctrl/ControlTest.gmk) makefile has a `$(BUILDTESTDIR)/ControlTest.ok`
+target which runs one of the self-tests. In order to run that individual test, use the following
+command:
+
+```shell
+bash build/make.sh -- $(pwd)/build/test/ControlTest.ok
+```


If you prefer to use your current version, that's fine too.

-------------

PR Review Comment: https://git.openjdk.org/jtreg/pull/184#discussion_r1524930748