From e68abfbeff8f79ca7ec92fdafe94d43f825505b4 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 20 May 1999 02:46:40 +0000
Subject: [PATCH] Update SGML docs with some changes I made to
test/regress/README many moons ago, but forgot to put here.
---
doc/src/sgml/regress.sgml | 181 ++++++++++++++++++--------------------
1 file changed, 85 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index a5a9c8aa9cb..62843345a43 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -82,15 +82,15 @@ The runtime path is /usr/local/pgsql (other paths are possible).
</Para>
<Para>
- The postmaster should be invoked with the system time zone set for
- Berkeley, California. This is done automatically by the regression
-test script. However, it does require machine support for the PST8PDT
-time zone.
-</Para>
-
-<Para>
-To verify that your machine does have this support, type
-the following:
+ It was formerly necessary to run the postmaster with system time zone
+ set to PST, but this is no longer required. You can run the regression
+ tests under your normal postmaster configuration. The test script will
+ set the PGTZ environment variable to ensure that timezone-dependent tests
+ produce the expected results. However, your system must provide
+ library support for the PST8PDT time zone, or the timezone-dependent
+ tests will fail.
+ To verify that your machine does have this support, type
+ the following:
<ProgramListing>
setenv TZ PST8PDT
date
@@ -147,36 +147,15 @@ the following:
like <FileName>ps</FileName> and <FileName>tar</FileName> vary wildly on what options you should use on each
platform. <Emphasis>Use common sense</Emphasis> before typing in these commands.
</Para>
-
- <Procedure>
- <Title><ProductName>Postgres</ProductName> Regression Configuration</Title>
<Para>
For a fresh install or upgrading from previous releases of
<ProductName>Postgres</ProductName>:
</Para>
-
- <Step Performance="required">
- <Para>
- Build the regression test. Type
- <ProgramListing>
- cd /usr/src/pgsql/src/test/regress
- gmake all
- </ProgramListing>
- </Para>
- </Step>
-
- <Step Performance="optional">
- <Para>
- If you have prevously invoked the regression test, clean up the
- working directory with:
-
- <ProgramListing>
- cd /usr/src/pgsql/src/test/regress
- make clean
- </ProgramListing>
- </para>
- </step>
+
+ <Procedure>
+ <Title><ProductName>Postgres</ProductName> Regression Configuration</Title>
+
<Step Performance="required">
<Para>
The file /usr/src/pgsql/src/test/regress/README has detailed
@@ -210,21 +189,41 @@ the following:
</Para>
</Step>
- <Step Performance="required">
+ <Step Performance="optional">
<Para>
- Run the regression tests. Type
+ If you have previously invoked the regression test, clean up the
+ working directory with:
<ProgramListing>
cd /usr/src/pgsql/src/test/regress
- gmake runtest
+ gmake clean
</ProgramListing>
- </Para>
-
+ </para>
<Para>
-
You do not need to type "gmake clean" if this is the first time you
are running the tests.
</Para>
+ </step>
+
+
+ <Step Performance="required">
+ <Para>
+ Build the regression test. Type
+ <ProgramListing>
+ cd /usr/src/pgsql/src/test/regress
+ gmake all
+ </ProgramListing>
+ </Para>
+ </Step>
+
+ <Step Performance="required">
+ <Para>
+ Run the regression tests. Type
+ <ProgramListing>
+ cd /usr/src/pgsql/src/test/regress
+ gmake runtest
+ </ProgramListing>
+ </Para>
</Step>
<Step Performance="required">
@@ -245,12 +244,13 @@ the following:
<Step Performance="required">
<Para>
- After running the tests, type
+ After running the tests and examining the results, type
<ProgramListing>
destroydb regression
cd /usr/src/pgsql/src/test/regress
gmake clean
</ProgramListing>
+ to recover the temporary disk space used by the tests.
</Para>
</Step>
</procedure>
@@ -258,48 +258,30 @@ the following:
<Sect1>
<Title>Regression Analysis</Title>
-
- <Para>
- <Quote>Failed</Quote> tests may have failed due to slightly different error messages,
- math libraries, or output formatting.
+
+ <Para>
+ The results are in files in the ./results directory. These results
+ can be compared with results in the ./expected directory using 'diff'.
+ (The test script does this for you, and leaves the differences
+ in ./regression.diffs.)
+ </Para>
+
+ <Para>
+ The files might not compare exactly. The test script will report
+ any difference as a "failure", but the difference might be due
+ to small cross-system differences in error message wording,
+ math library behavior, etc.
"Failures" of this type do not indicate a problem with
<ProductName>Postgres</ProductName>.
</Para>
<Para>
- For a i686/Linux-ELF platform, no tests failed since this is the
- v6.2.1 regression testing reference platform.
- </Para>
-
- <Para>
- For the SPARC/Linux-ELF platform, using the 970525 beta version of
- <ProductName>Postgres</ProductName> v6.2 the following tests "failed":
- float8 and geometry "failed" due to minor precision differences in
- floating point numbers. select_views produces massively different output,
- but the differences are due to minor floating point differences.
- </Para>
-
- <Para>
- Conclusion? If you do see failures, try to understand the nature of
- the differences and then decide if those differences will affect your
- intended use of <ProductName>Postgres</ProductName>. However, keep in mind that this is likely
- to be the most solid release of <ProductName>Postgres</ProductName> to date, incorporating many
- bug fixes from v6.1, and that previous versions of <ProductName>Postgres</ProductName> have been
- in use successfully for some time now.
+ Thus, it is necessary to examine the actual differences for each
+ "failed" test to determine whether there is really a problem.
+ The following paragraphs attempt to provide some guidance in
+ determining whether a difference is significant or not.
</Para>
- <Sect2>
- <Title>Comparing expected/actual output</Title>
-
- <Para>
- The results are in files in the ./results directory. These results
- can be compared with results in the ./expected directory using 'diff'.
- The files might not compare exactly. The following paragraphs attempt
- to explain the differences.
- </Para>
-
- </Sect2>
-
<Sect2>
<Title>Error message differences</Title>
@@ -337,18 +319,24 @@ the following:
<Title>Date and time differences</Title>
<Para>
- On many supported platforms, you can force PostgreSQL to believe that it
- is running in the same time zone as Berkeley, California. See details in
- the section on how to run the regression tests.
-
- If you do not explicitly set your time zone environment to PST8PDT, then
- most of the date and time results will reflect your local time zone and
- will fail the regression testing.
-
- There appears to be some systems which do not accept the recommended syntax
- for explicitly setting the local time zone rules. Some systems using the
- public domain time zone package exhibit minor problems with pre-1970 PDT
- times, representing them in PST instead.
+ Most of the date and time results are dependent on timezone environment.
+ The reference files are generated for timezone PST8PDT (Berkeley,
+ California) and there will be apparent failures if the tests are not
+ run with that timezone setting. The regression test driver sets
+ environment variable PGTZ to PST8PDT to ensure proper results.
+ </Para>
+
+ <Para>
+ There appear to be some systems which do not accept the recommended syntax
+ for explicitly setting the local time zone rules; you may need to use
+ a different PGTZ setting on such machines.
+ </Para>
+
+ <Para>
+ Some systems using older timezone libraries fail to apply daylight-savings
+ corrections to pre-1970 dates, causing pre-1970 PDT times to be displayed
+ in PST instead. This will result in localized differences in the test
+ results.
</Para>
</Sect2>
@@ -357,17 +345,17 @@ the following:
<Title>Floating point differences</Title>
<Para>
- Some of the tests involve computing 64-bit (<Type>float8</Type>) number from table
+ Some of the tests involve computing 64-bit (<Type>float8</Type>) numbers from table
columns. Differences in results involving mathematical functions of
- <Type>float8</Type> columns have been observed. These differences occur where
- different operating systems are used on the same platform ie:
- BSDI and SOLARIS on Intel/86, and where the same operating system is
- used used on different platforms, ie: SOLARIS on SPARC and Intel/86.
-
+ <Type>float8</Type> columns have been observed. The float8
+ and geometry tests are particularly prone to small differences
+ across platforms.
Human eyeball comparison is needed to determine the real significance
of these differences which are usually 10 places to the right of
the decimal point.
-
+ </Para>
+
+ <Para>
Some systems signal errors from pow() and exp() differently from
the mechanism expected by the current Postgres code.
</Para>
@@ -403,7 +391,8 @@ the following:
<Para>
There is at least one test case in random.out which is intended to produce
- random results. This causes random to fail the regression testing.
+ random results. This causes random to fail the regression testing
+ once in a while.
Typing
<ProgramListing>
diff results/random.out expected/random.out
--
GitLab