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). - 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. - - - -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: setenv TZ PST8PDT date @@ -147,36 +147,15 @@ the following: like ps and tar vary wildly on what options you should use on each platform. Use common sense before typing in these commands. - - - <ProductName>Postgres</ProductName> Regression Configuration For a fresh install or upgrading from previous releases of Postgres: - - - - Build the regression test. Type - - cd /usr/src/pgsql/src/test/regress - gmake all - - - - - - - If you have prevously invoked the regression test, clean up the - working directory with: - - - cd /usr/src/pgsql/src/test/regress - make clean - - - + + + <ProductName>Postgres</ProductName> Regression Configuration + The file /usr/src/pgsql/src/test/regress/README has detailed @@ -210,21 +189,41 @@ the following: + + + If you have previously invoked the regression test, clean up the + working directory with: + + + cd /usr/src/pgsql/src/test/regress + gmake clean + + + + You do not need to type "gmake clean" if this is the first time you + are running the tests. + + + + + + + Build the regression test. Type + + cd /usr/src/pgsql/src/test/regress + gmake all + + + + Run the regression tests. Type - cd /usr/src/pgsql/src/test/regress gmake runtest - - - - You do not need to type "gmake clean" if this is the first time you - are running the tests. - @@ -245,12 +244,13 @@ the following: - After running the tests, type + After running the tests and examining the results, type destroydb regression cd /usr/src/pgsql/src/test/regress gmake clean + to recover the temporary disk space used by the tests. @@ -258,48 +258,30 @@ the following: Regression Analysis - - - Failed tests may have failed due to slightly different error messages, - math libraries, or output formatting. + + + 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.) + + + + 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 Postgres. - For a i686/Linux-ELF platform, no tests failed since this is the - v6.2.1 regression testing reference platform. + 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. - - For the SPARC/Linux-ELF platform, using the 970525 beta version of - Postgres 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. - - - - 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 Postgres. However, keep in mind that this is likely - to be the most solid release of Postgres to date, incorporating many - bug fixes from v6.1, and that previous versions of Postgres have been - in use successfully for some time now. - - - - Comparing expected/actual output - - - 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. - - - - Error message differences @@ -337,18 +319,24 @@ the following: Date and time differences - 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. + + + + 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. + + + + 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. @@ -357,17 +345,17 @@ the following: Floating point differences - Some of the tests involve computing 64-bit (float8) number from table + Some of the tests involve computing 64-bit (float8) numbers from table columns. Differences in results involving mathematical functions of - float8 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. - + float8 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. - + + + Some systems signal errors from pow() and exp() differently from the mechanism expected by the current Postgres code. @@ -403,7 +391,8 @@ the following: 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 diff results/random.out expected/random.out