[newlib-cygwin/main] Cygwin: testsuite: Update README

[newlib-cygwin/main] Cygwin: testsuite: Update README

[Jon Turney]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=718f37823dc8f5a738dcc8ee49e4e7b17671da56

commit 718f37823dc8f5a738dcc8ee49e4e7b17671da56
Author: Jon Turney <jon.turney@dronecode.org.uk>
Date:   Mon Jul 10 16:37:41 2023 +0100

    Cygwin: testsuite: Update README
    
    v2:
    Polish instructions on adding a test
    
    Signed-off-by: Jon Turney <jon.turney@dronecode.org.uk>

Diff:
---
 winsup/testsuite/README | 82 ++++++++++++++++++++++++++++++++++---------------
 1 file changed, 58 insertions(+), 24 deletions(-)

diff --git a/winsup/testsuite/README b/winsup/testsuite/README
index ff2df4119..511133e4d 100644
--- a/winsup/testsuite/README
+++ b/winsup/testsuite/README
@@ -1,35 +1,69 @@
-Here are some notes about adding and using this testsuite.
+Here are some notes about adding to and using this testsuite.
 
-The testsuite adds a directory containing the just built cygwin1.dll to the PATH
-(during the run step) so that it can be found by the Windows loader during
-testing.
+The testsuite adds a directory containing the just-built cygwin1.dll to the PATH
+so that it can be found by the Windows loader during testing.
 
-Because we'll probably run into complaints about using two DLLs, we
-run cygrun.exe for each test.  All this does is run the test with
-CreateProcess() so that we don't attempt to do the special code for
-when a cygwin program calls another cygwin program, as this might be a
-"multiple cygwins" problem.
+Because we'll probably run into complaints about using two DLLs, we use
+cygrun.exe to run each test.  All this does is run the test with CreateProcess()
+so that we don't attempt to do the special code for when a cygwin program calls
+another cygwin program, as this might be a "multiple cygwins" problem.
 
-Any test that needs to test command line args or redirection needs to
-run such a child program itself, as the testsuite will not do any
-arguments or redirection for it.  Same for fork, signals, etc.
+The testsuite/winsup.api subdirectory is for testing the API to cygwin1.dll
+ONLY.  Create other subdirs under testsuite/ for other classes of testing.
 
-The testsuite/winsup.api subdirectory is for testing the API to
-cygwin1.dll ONLY.  Create other subdirs under testsuite/ for other
-classes of testing.
+Tests in testsuite/winsup.api/pthread/ are derived from the pthread-win32
+testsuite.
 
-Tests under winsup.api/ either run successfully and exit(0), exit(77) to
-indicate a skipped test, or any other exit status to indicate a failure.
+Tests in testsuite/winsup.api/ltp/ are derived from (a very old version of) the
+ltp testsuite.
 
 Don't print anything to the screen if you can avoid it (except for failure
-reasons, of course).  One .c file per test, no compile options are allowed
-(we're testing the api, not the compiler).
+reasons, of course).
 
-Tests whose filename is mentioned in XFAIL_TESTS are expected to fail,
-effectively reversing the result of those.
+"make check" will only work if you run it *on* an NT machine.  Cross-checking is
+not supported.
 
-"make check" will only work if you run it *on* an NT machine.
-Cross-checking is not supported.
+Tests whose name is mentioned in XFAIL_TESTS are expected to fail, effectively
+reversing the result of those.
+
+Adding a test
+=============
+
+Add the source for the test under testsuite/winsup.api/.
+
+Add the additional tests program to check_PROGRAMS in testsuite/Makefile.am.
+
+(Note that if the test 'foo' has a single source file, foo.c, there's no need to
+write a foo_SOURCES as that's the default Automake assumes.)
+
+Tests can use libltp, but's that not required.
+
+The Cygwin 'installation' that the tests are run in is minimal, so don't assume
+anything is present.
+
+Any test that needs to test command line args or redirection needs to run such a
+child program itself, as the testsuite will not do any arguments or redirection
+for it.  Same for fork, signals, etc.
+
+Tests should either run successfully and exit(0), exit(77) to indicate a skipped
+test, or any other exit status to indicate a failure.
+
+Tips
+====
+
+* To run selected tests, use e.g:
 
-To run selected tests, use e.g:
 $ make check TESTS="winsup.api/ltp/umask03 winsup.api/ltp/stat06"
+
+* To build the tests without running them, use the check_programs target, e.g:
+
+$ make -C winsup/testsuite/ check_programs
+
+* To run an individual test program directly (against the installed, rather than
+  just built DLL), e.g.:
+
+$ winsup/testsuite/winsup.api/pthread/cancel1
+
+* To run an individual test program against the test DLL under gdb, e.g.:
+
+$ PATH="<build_tooldir>/winsup/testsuite/testinst/bin/:$PATH" cygrun -notimeout "gdb winsup.api/systemcall"