From: Dimitar Dimitrov <dimitar@dinux.eu>
Date: Fri, 6 Sep 2024 19:49:50 +0000 (+0300)
Subject: doc: Document struct-layout-1.exp for ABI checks
X-Git-Tag: basepoints/gcc-16~5608
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a30a9d5da144d87bdfd60cfc485b46bb3a74842f;p=thirdparty%2Fgcc.git

doc: Document struct-layout-1.exp for ABI checks

This test helped discover PR116621, so it is worth being documented.

gcc/ChangeLog:

	* doc/sourcebuild.texi: Document struct-layout-1.exp.

Signed-off-by: Dimitar Dimitrov <dimitar@dinux.eu>
---

diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index a21a97fd6d6..38275fd0fee 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -4165,7 +4165,7 @@ compiler options from @env{COMPAT_OPTIONS}.  When
 the compiler under test but with combinations of the options from
 @env{COMPAT_OPTIONS}.
 
-To run only the C++ compatibility suite using the compiler under test
+To run only the basic C++ compatibility suite using the compiler under test
 and another version of GCC using specific compiler options, do the
 following from @file{@var{objdir}/gcc}:
 
@@ -4178,6 +4178,22 @@ make -k \
   RUNTESTFLAGS="compat.exp"
 @end smallexample
 
+The file @file{struct-layout-1.exp} provides a few more test cases
+exercising pseudo-randomly generated structure layouts.
+Defining @env{RUN_ALL_COMPAT_TESTS} would increase the number of
+generated tests to yield even more coverage.  As an example, to modify
+the above test command to run the maximum number of ABI tests for C++, do:
+
+@smallexample
+rm site.exp
+make -k \
+  ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
+  COMPAT_OPTIONS="@var{lists as shown above}" \
+  check-c++ \
+  RUNTESTFLAGS="compat.exp struct-layout-1.exp" \
+  RUN_ALL_COMPAT_TESTS=1
+@end smallexample
+
 A test that fails when the source files are compiled with different
 compilers, but passes when the files are compiled with the same
 compiler, demonstrates incompatibility of the generated code or