mirror of
https://github.com/postgres/postgres.git
synced 2025-07-28 23:42:10 +03:00
* doc/src/sgml/regress.sgml: Update for new driver script.
* doc/src/sgml/installation.sgml: ditto. * src/test/regress/README: Regenerate. * doc/src/sgml/docguide.sgml: Explain how it was done. Explain how INSTALL and HISTORY are (now) generated. * doc/src/sgml/Makefile: Implement HISTORY generation to be analoguous to INSTALL.
This commit is contained in:
@ -8,7 +8,7 @@
|
|||||||
#
|
#
|
||||||
#
|
#
|
||||||
# IDENTIFICATION
|
# IDENTIFICATION
|
||||||
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.23 2000/10/10 22:01:50 momjian Exp $
|
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.24 2000/10/17 15:26:39 petere Exp $
|
||||||
#
|
#
|
||||||
#----------------------------------------------------------------------------
|
#----------------------------------------------------------------------------
|
||||||
|
|
||||||
@ -201,21 +201,30 @@ distclean:
|
|||||||
cp -p ../graphics/$@ .
|
cp -p ../graphics/$@ .
|
||||||
|
|
||||||
|
|
||||||
# Generation of the INSTALL text file. Not fully automated, but better
|
#
|
||||||
# than nothing.
|
# Semi-automatic generation of some text files.
|
||||||
.PHONY: INSTALL
|
#
|
||||||
INSTALL: INSTALL.html
|
|
||||||
|
INSTALL HISTORY: % : %.html
|
||||||
@echo "|";\
|
@echo "|";\
|
||||||
echo "| You should now take \`$<', save it as a text file in Netscape,";\
|
echo "| You should now take \`$<', save it as a text file in Netscape,";\
|
||||||
echo "| and put it in place of the existing \`INSTALL' file.";\
|
echo "| and put it in place of the existing \`$@' file.";\
|
||||||
echo "|"
|
echo "|"
|
||||||
@rm -f tempfile.html tempfile.sgml
|
|
||||||
|
|
||||||
INSTALL.html: tempfile.html
|
|
||||||
sed -e 's/Chapter 1. *//g' < $< > $@
|
|
||||||
|
|
||||||
tempfile.html: tempfile.sgml
|
INSTALL.html HISTORY.html: %.html : tempfile_%.html
|
||||||
jade -d $(HDSL) -V nochunks -t sgml $< > $@
|
sed 's/Chapter 1. *//g' $< >$@
|
||||||
|
|
||||||
tempfile.sgml: standalone-install.sgml installation.sgml
|
tempfile_INSTALL.html tempfile_HISTORY.html: tempfile_%.html : tempfile_%.sgml
|
||||||
cat $+ > $@
|
jade -d $(HDSL) -V nochunks -t sgml $< >$@
|
||||||
|
|
||||||
|
|
||||||
|
tempfile_INSTALL.sgml: standalone-install.sgml installation.sgml
|
||||||
|
cat $+ >$@
|
||||||
|
|
||||||
|
tempfile_HISTORY.sgml: release.sgml
|
||||||
|
( echo '<!doctype chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">'; \
|
||||||
|
cat $< ) >$@
|
||||||
|
|
||||||
|
|
||||||
|
.INTERMEDIATE: tempfile_INSTALL.html tempfile_HISTORY.html tempfile_INSTALL.sgml tempfile_HISTORY.sgml
|
||||||
|
@ -1,5 +1,5 @@
|
|||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.27 2000/09/29 20:21:33 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.28 2000/10/17 15:26:40 petere Exp $
|
||||||
Documentation Guide
|
Documentation Guide
|
||||||
Thomas Lockhart
|
Thomas Lockhart
|
||||||
-->
|
-->
|
||||||
@ -83,7 +83,7 @@ Thomas Lockhart
|
|||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry>./INSTALL</entry>
|
<entry>./INSTALL</entry>
|
||||||
<entry>Installation instructions (text from sgml->rtf->text)</entry>
|
<entry>Installation instructions</entry>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry>./README</entry>
|
<entry>./README</entry>
|
||||||
@ -848,6 +848,7 @@ End:
|
|||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
|
||||||
<sect1 id="doc-build">
|
<sect1 id="doc-build">
|
||||||
<title>Building Documentation</title>
|
<title>Building Documentation</title>
|
||||||
|
|
||||||
@ -911,9 +912,8 @@ PSTYLE= /home/lockhart/SGML/db143.d/docbook/print
|
|||||||
% make install
|
% make install
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="doc-manpages">
|
<sect2 id="doc-manpages">
|
||||||
<title>Manpages</title>
|
<title>Manpages</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
@ -966,9 +966,9 @@ $ make man
|
|||||||
</para>
|
</para>
|
||||||
</step>
|
</step>
|
||||||
</procedure>
|
</procedure>
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="doc-hardcopy">
|
<sect2 id="doc-hardcopy">
|
||||||
<title>Hardcopy Generation for v7.0</title>
|
<title>Hardcopy Generation for v7.0</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
@ -995,99 +995,6 @@ $ make man
|
|||||||
</para>
|
</para>
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>Text Hardcopy</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<filename>INSTALL</filename> and <filename>HISTORY</filename> are
|
|
||||||
updated for each release. For historical reasons, these files are
|
|
||||||
in plain text, but are derived from the newer
|
|
||||||
<acronym>SGML</acronym> sources.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<procedure>
|
|
||||||
<title>Plain Text Generation</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Both <filename>INSTALL</filename> and
|
|
||||||
<filename>HISTORY</filename> are generated from existing
|
|
||||||
<acronym>SGML</acronym> sources. They are extracted from the same
|
|
||||||
intermediate <acronym>RTF</acronym> file.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Generate <acronym>RTF</acronym> by typing:
|
|
||||||
<programlisting>
|
|
||||||
% cd doc/src/sgml
|
|
||||||
% make installation.rtf
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Import <filename>installation.rtf</filename> into
|
|
||||||
<productname>Applix Words</productname>.
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Set the page width and margins.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<substeps>
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Adjust the page width in File.PageSetup to 10 inches.
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Select all text.
|
|
||||||
Adjust the right margin using the ruler to 9.5 inches. This
|
|
||||||
will give a maximum column width of 79 characters, within the
|
|
||||||
80 columns upper limit goal.
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
</substeps>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Lop off the parts of the document which are not needed.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
For <filename>INSTALL</filename>, remove all release notes from
|
|
||||||
the end of the text, except for those from the current release.
|
|
||||||
For <filename>HISTORY</filename>, remove all text up to the
|
|
||||||
release notes, preserving and modifying the title and ToC.
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Export the result as "ASCII Layout".
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Using emacs or vi, clean up the tabular information in
|
|
||||||
<filename>INSTALL</filename>. Remove the "mailto"
|
|
||||||
<acronym>URLs</acronym> for the porting contributors to shrink
|
|
||||||
the column heights.
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
</procedure>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>Postscript Hardcopy</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Several areas are addressed while generating Postscript
|
Several areas are addressed while generating Postscript
|
||||||
hardcopy, including RTF repair, ToC generation, and page break
|
hardcopy, including RTF repair, ToC generation, and page break
|
||||||
@ -1321,10 +1228,134 @@ exit
|
|||||||
</para>
|
</para>
|
||||||
</step>
|
</step>
|
||||||
</procedure>
|
</procedure>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Plain Text Files</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Several files are distributed as plain text, for reading during
|
||||||
|
the installation process. The <filename>INSTALL</filename> file
|
||||||
|
corresponds to the chapter in the <citetitle>Administrator's
|
||||||
|
Guide</citetitle>, with some minor changes to account for the
|
||||||
|
different context. To recreate the file, change to the directory
|
||||||
|
<filename>doc/src/sgml</filename> and enter <userinput>gmake
|
||||||
|
INSTALL</userinput>. This will create a file
|
||||||
|
<filename>INSTALL.html</filename> that can be saved as text with
|
||||||
|
<productname>Netscape Navigator</productname> and put into the
|
||||||
|
place of the existing file. <productname>Netscape</productname>
|
||||||
|
seems to offer the best quality for <acronym>HTML</acronym> to
|
||||||
|
text conversions (over <application>lynx</application> and
|
||||||
|
<application>w3m</application>).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The file <filename>HISTORY</filename> can be created similarly,
|
||||||
|
using the command <userinput>gmake HISTORY</userinput>. The table
|
||||||
|
of contents should be removed manually from the resulting text
|
||||||
|
file.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Since it does not change very often, the generation of the file
|
||||||
|
<filename>src/test/regress/README</filename> is not fully
|
||||||
|
automated. After building the <acronym>HTML</acronym> version of
|
||||||
|
the <citetitle>Administrator's Guide</citetitle>, convert the
|
||||||
|
resulting files <filename>regress.htm</filename> and
|
||||||
|
<filename>regress-platform.htm</filename> to text, using
|
||||||
|
<productname>Netscape</productname>. Then paste the text files
|
||||||
|
together and edit them to taste (e.g., remove the navigation
|
||||||
|
bars, remove the references to other chapters).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
* This is how you can create text files via RTF and ApplixWare,
|
||||||
|
* for historical reference.
|
||||||
|
|
||||||
|
<procedure>
|
||||||
|
<title>Plain Text Generation</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Both <filename>INSTALL</filename> and
|
||||||
|
<filename>HISTORY</filename> are generated from existing
|
||||||
|
<acronym>SGML</acronym> sources. They are extracted from the same
|
||||||
|
intermediate <acronym>RTF</acronym> file.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Generate <acronym>RTF</acronym> by typing:
|
||||||
|
<programlisting>
|
||||||
|
% cd doc/src/sgml
|
||||||
|
% make installation.rtf
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Import <filename>installation.rtf</filename> into
|
||||||
|
<productname>Applix Words</productname>.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Set the page width and margins.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<substeps>
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Adjust the page width in File.PageSetup to 10 inches.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Select all text.
|
||||||
|
Adjust the right margin using the ruler to 9.5 inches. This
|
||||||
|
will give a maximum column width of 79 characters, within the
|
||||||
|
80 columns upper limit goal.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
</substeps>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Lop off the parts of the document which are not needed.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For <filename>INSTALL</filename>, remove all release notes from
|
||||||
|
the end of the text, except for those from the current release.
|
||||||
|
For <filename>HISTORY</filename>, remove all text up to the
|
||||||
|
release notes, preserving and modifying the title and ToC.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Export the result as "ASCII Layout".
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step performance="required">
|
||||||
|
<para>
|
||||||
|
Using emacs or vi, clean up the tabular information in
|
||||||
|
<filename>INSTALL</filename>. Remove the "mailto"
|
||||||
|
<acronym>URLs</acronym> for the porting contributors to shrink
|
||||||
|
the column heights.
|
||||||
|
</para>
|
||||||
|
</step>
|
||||||
|
</procedure>
|
||||||
|
-->
|
||||||
|
|
||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
|
||||||
<sect1 id="doc-toolsets">
|
<sect1 id="doc-toolsets">
|
||||||
<title>Toolsets</title>
|
<title>Toolsets</title>
|
||||||
|
|
||||||
|
@ -1,4 +1,4 @@
|
|||||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.24 2000/10/16 03:25:16 momjian Exp $ -->
|
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.25 2000/10/17 15:26:40 petere Exp $ -->
|
||||||
|
|
||||||
<chapter id="installation">
|
<chapter id="installation">
|
||||||
<title><![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions</title>
|
<title><![%flattext-install-include[<productname>PostgreSQL</> ]]>Installation Instructions</title>
|
||||||
@ -744,20 +744,20 @@ All of PostgreSQL is successfully made. Ready to install.
|
|||||||
<para>
|
<para>
|
||||||
If you want to test the newly built server before you install it,
|
If you want to test the newly built server before you install it,
|
||||||
you can run the regression tests at this point. The regression
|
you can run the regression tests at this point. The regression
|
||||||
tests are a test suite to verify that <productname>PostgreSQL</> runs on your machine
|
tests are a test suite to verify that <productname>PostgreSQL</>
|
||||||
in the way the developers expected it to. Type
|
runs on your machine in the way the developers expected it
|
||||||
|
to. Type
|
||||||
<screen>
|
<screen>
|
||||||
<userinput>gmake -C src/test/regress all runcheck</userinput>
|
<userinput>gmake check</userinput>
|
||||||
<!-- XXX How about just `gmake check'? -->
|
|
||||||
</screen>
|
</screen>
|
||||||
It is possible that some tests fail, due to differences in error
|
It is possible that some tests fail, due to differences in error
|
||||||
message wording or floating point results. The file
|
message wording or floating point results.
|
||||||
<filename>src/test/regress/README</> and
|
<![%flattext-install-include[The file
|
||||||
<![%flattext-install-include[the <citetitle>Administrator's Guide</citetitle>]]>
|
<filename>src/test/regress/README</> and the
|
||||||
<![%flattext-install-ignore[<xref linkend="regress">]]>
|
<citetitle>Administrator's Guide</citetitle> contain]]>
|
||||||
contain detailed
|
<![%flattext-install-ignore[<xref linkend="regress"> contains]]>
|
||||||
information about interpreting the test results. You can repeat
|
detailed information about interpreting the test results. You can
|
||||||
this test at any later time by issuing the same command.
|
repeat this test at any later time by issuing the same command.
|
||||||
</para>
|
</para>
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
|
@ -1,481 +1,277 @@
|
|||||||
|
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.11 2000/10/17 15:26:40 petere Exp $ -->
|
||||||
|
|
||||||
<chapter id="regress">
|
<chapter id="regress">
|
||||||
<title id="regress-title">Regression Test</title>
|
<title id="regress-title">Regression Tests</title>
|
||||||
|
|
||||||
<abstract>
|
<abstract>
|
||||||
<para>
|
<para>
|
||||||
Regression test instructions and analysis.
|
Regression test instructions and analysis
|
||||||
</para>
|
</para>
|
||||||
</abstract>
|
</abstract>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The PostgreSQL regression tests are a comprehensive set of tests for the
|
The regression tests are a comprehensive set of tests for the SQL
|
||||||
SQL implementation embedded in PostgreSQL. They test standard SQL
|
implementation in <productname>PostgreSQL</productname>. They test
|
||||||
operations as well as the extended capabilities of PostgreSQL.
|
standard SQL operations as well as the extended capabilities of
|
||||||
</para>
|
<productname>PostgreSQL</productname>. The test suite was
|
||||||
|
originally developed by Jolly Chen and Andrew Yu, and was
|
||||||
<para>
|
extensively revised and repackaged by Marc Fournier and Thomas
|
||||||
There are two different ways in which the regression tests can be run:
|
Lockhart. From <productname>PostgreSQL</productname> 6.1 onward
|
||||||
the "sequential" method and the "parallel" method. The sequential method
|
|
||||||
runs each test script in turn, whereas the parallel method starts up
|
|
||||||
multiple server processes to run groups of tests in parallel. Parallel
|
|
||||||
testing gives confidence that interprocess communication and locking
|
|
||||||
are working correctly. Another key difference is that the sequential
|
|
||||||
test procedure uses an already-installed postmaster, whereas the
|
|
||||||
parallel test procedure tests a system that has been built but not yet
|
|
||||||
installed. (The parallel test script actually does an installation into
|
|
||||||
a temporary directory and fires up a private postmaster therein.)
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Some properly installed and fully functional PostgreSQL installations
|
|
||||||
can "fail" some of these regression tests due to artifacts of floating point
|
|
||||||
representation and time zone support. The tests are currently evaluated
|
|
||||||
using a simple <application>diff</application> comparison against the
|
|
||||||
outputs generated on a reference system, so the results are sensitive to
|
|
||||||
small system differences.
|
|
||||||
When a test is reported as "failed", always examine the differences
|
|
||||||
between expected and actual results; you may well find that the differences
|
|
||||||
are not significant.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The regression tests were originally developed by Jolly Chen and Andrew Yu,
|
|
||||||
and were extensively revised/repackaged by Marc Fournier and Thomas Lockhart.
|
|
||||||
From <productname>PostgreSQL</productname> v6.1 onward
|
|
||||||
the regression tests are current for every official release.
|
the regression tests are current for every official release.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<sect1 id="regress-environment">
|
<para>
|
||||||
<title>Regression Environment</title>
|
The regression test can be run against an already installed and
|
||||||
|
running server, or using a temporary installation within the build
|
||||||
|
tree. Furthermore, there is a <quote>parallel</quote> and a
|
||||||
|
<quote>sequential</quote> mode for running the tests. The
|
||||||
|
sequential method runs each test script in turn, whereas the
|
||||||
|
parallel method starts up multiple server processes to run groups
|
||||||
|
of tests in parallel. Parallel testing gives confidence that
|
||||||
|
interprocess communication and locking are working correctly. For
|
||||||
|
historical reasons, the sequential test is usually run against an
|
||||||
|
existing installation and the parallel method
|
||||||
|
<quote>stand-alone</quote>, but there are technical reasons for
|
||||||
|
this.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
To run the regression tests after building but before installation,
|
||||||
|
type
|
||||||
|
<screen>
|
||||||
|
<prompt>$ </prompt><userinput>gmake check</userinput>
|
||||||
|
</screen>
|
||||||
|
in the top-level directory. (Or you can change to
|
||||||
|
<filename>src/test/regress</filename> and run the command there.)
|
||||||
|
This will first build several auxiliary files, such as
|
||||||
|
platform-dependent <quote>expected</quote> files and some sample
|
||||||
|
user-defined trigger functions, and then run the test driver
|
||||||
|
script. At the end you should see something like
|
||||||
|
<screen>
|
||||||
|
<computeroutput>
|
||||||
|
======================
|
||||||
|
All 75 tests passed.
|
||||||
|
======================
|
||||||
|
</computeroutput>
|
||||||
|
</screen>
|
||||||
|
or otherwise a note about what tests failed. See <xref
|
||||||
|
linkend="regress-evaluation"> below for more.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
Because this test method runs a temporary server, it will not work
|
||||||
|
when you are the root user (the server will not start as root).
|
||||||
|
If you already did the build as root, you do not have to start all
|
||||||
|
over. Instead, make the regression test directory writable by
|
||||||
|
some other user, log in as that user, and restart the tests.
|
||||||
|
<screen>
|
||||||
|
<prompt>root# </prompt><userinput>chmod -R a+w src/test/regress</userinput>
|
||||||
|
<prompt>root# </prompt><userinput>su - joeuser</userinput>
|
||||||
|
<prompt>joeuser$ </prompt><userinput>gmake check</userinput>
|
||||||
|
</screen>
|
||||||
|
(The only possible <quote>security risk</quote> here is that other
|
||||||
|
users might be able to alter the regression test results behind
|
||||||
|
your back. Use common sense when managing user permissions.)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Alternatively, run the tests after installation.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<tip>
|
||||||
|
<para>
|
||||||
|
On some systems, the default Bourne-compatible shell
|
||||||
|
(<filename>/bin/sh</filename>) gets confused when it has to manage
|
||||||
|
too many child processes in parallel. This may cause the parallel
|
||||||
|
test run to lock up or fail. In such cases, specify a different
|
||||||
|
Bourne-compatible shell on the command line, for example:
|
||||||
|
<informalexample>
|
||||||
|
<screen>
|
||||||
|
<prompt>$ </prompt><userinput>gmake SHELL=/bin/ksh check</userinput>
|
||||||
|
</screen>
|
||||||
|
</informalexample>
|
||||||
|
</para>
|
||||||
|
</tip>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
To run the tests after installation (see <xref
|
||||||
|
linkend="installation">), initialize a data area and start the
|
||||||
|
server, as explained in <xref linkend="runtime">, then type
|
||||||
|
<screen>
|
||||||
|
<prompt>$ </prompt><userinput>gmake installcheck</userinput>
|
||||||
|
</screen>
|
||||||
|
The server is expected to be running on the local host with the
|
||||||
|
default port number.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect1 id="regress-evaluation">
|
||||||
|
<title>Test Evaluation</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The regression testing notes below assume the following (except where noted):
|
Some properly installed and fully functional
|
||||||
<itemizedlist spacing="compact" mark="bullet">
|
<productname>PostgreSQL</productname> installations can
|
||||||
<listitem>
|
<quote>fail</quote> some of these regression tests due to
|
||||||
<para>
|
artifacts of floating point representation and time zone
|
||||||
Commands are Unix-compatible. See note below.
|
support. The tests are currently evaluated using a simple
|
||||||
</para>
|
<application>diff</application> comparison against the outputs
|
||||||
</listitem>
|
generated on a reference system, so the results are sensitive to
|
||||||
<listitem>
|
small system differences. When a test is reported as
|
||||||
<para>
|
<quote>failed</quote>, always examine the differences between
|
||||||
Defaults are used except where noted.
|
expected and actual results; you may well find that the
|
||||||
</para>
|
differences are not significant. Nonetheless, we still strive to
|
||||||
</listitem>
|
maintain accurate reference files across all supported platforms,
|
||||||
<listitem>
|
so it can be expected that all tests pass.
|
||||||
<para>
|
|
||||||
User postgres is the <productname>Postgres</productname> superuser.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The source path is /usr/src/pgsql (other paths are possible).
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The runtime path is /usr/local/pgsql (other paths are possible).
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Normally, the regression tests should be run as the postgres user since
|
The actual outputs of the regression tests are in files in the
|
||||||
the 'src/test/regress' directory and sub-directories are owned by the
|
<filename>src/test/regress/results</filename> directory. The test
|
||||||
postgres user. If you run the regression test as another user the
|
script uses <application>diff</application> to compare each output
|
||||||
'src/test/regress' directory tree must be writeable by that user.
|
file against the reference outputs stored in the
|
||||||
|
<filename>src/test/regress/expected</filename> directory. Any
|
||||||
|
differences are saved for your inspection in
|
||||||
|
<filename>src/test/regress/regression.diffs</filename>. (Or you
|
||||||
|
can run <application>diff</application> yourself, if you prefer.)
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<sect2>
|
||||||
It was formerly necessary to run the postmaster with system time zone
|
<title>Error message differences</title>
|
||||||
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
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The "date" command above should have returned the current system time
|
|
||||||
in the PST8PDT time zone. If the PST8PDT database is not available, then
|
|
||||||
your system may have returned the time in GMT. If the PST8PDT time zone
|
|
||||||
is not available, you can set the time zone rules explicitly:
|
|
||||||
<programlisting>
|
|
||||||
setenv PGTZ PST8PDT7,M04.01.0,M10.05.03
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The directory layout for the regression test area is:
|
|
||||||
|
|
||||||
<table tocentry="1">
|
|
||||||
<title>Directory Layout</title>
|
|
||||||
|
|
||||||
<titleabbrev>Kerberos</titleabbrev>
|
|
||||||
|
|
||||||
<tgroup cols="2">
|
|
||||||
<thead>
|
|
||||||
<row>
|
|
||||||
<entry>Directory</entry>
|
|
||||||
<entry>Description</entry>
|
|
||||||
</row>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<row>
|
|
||||||
<entry>Directory</entry>
|
|
||||||
<entry>Description</entry>
|
|
||||||
</row>
|
|
||||||
<row>
|
|
||||||
<entry>input</entry>
|
|
||||||
<entry>
|
|
||||||
Source files that are converted using
|
|
||||||
<command>make all</command> into
|
|
||||||
some of the <filename>.sql</filename> files in the
|
|
||||||
<filename>sql</filename> subdirectory.
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>output</entry>
|
|
||||||
<entry>
|
|
||||||
Source files that are converted using
|
|
||||||
<command>make all</command> into
|
|
||||||
<filename>.out</filename> files in the
|
|
||||||
<filename>expected</filename> subdirectory.
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>sql</entry>
|
|
||||||
<entry>
|
|
||||||
<filename>.sql</filename> files used to perform the
|
|
||||||
regression tests.
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>expected</entry>
|
|
||||||
<entry>
|
|
||||||
<filename>.out</filename> files that represent what we
|
|
||||||
<emphasis>expect</emphasis> the results to
|
|
||||||
look like.
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>results</entry>
|
|
||||||
<entry>
|
|
||||||
<filename>.out</filename> files that contain what the results
|
|
||||||
<emphasis>actually</emphasis> look
|
|
||||||
like. Also used as temporary storage for table copy testing.
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>tmp_check</entry>
|
|
||||||
<entry>
|
|
||||||
Temporary installation created by parallel testing script.
|
|
||||||
</entry>
|
|
||||||
</row>
|
|
||||||
</tbody>
|
|
||||||
</tgroup>
|
|
||||||
</table>
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="regress-procedure">
|
|
||||||
<title>Regression Test Procedure</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Commands were tested on RedHat Linux version 4.2 using the bash shell.
|
Some of the regression tests involve intentional invalid input
|
||||||
Except where noted, they will probably work on most systems. Commands
|
values. Error messages can come from either the
|
||||||
like <filename>ps</filename> and <filename>tar</filename> vary
|
<productname>PostgreSQL</productname> code or from the host
|
||||||
wildly on what options you should use on each
|
platform system routines. In the latter case, the messages may
|
||||||
platform. <emphasis>Use common sense</emphasis> before typing in these commands.
|
vary between platforms, but should reflect similar
|
||||||
|
information. These differences in messages will result in a
|
||||||
|
<quote>failed</quote> regression test which can be validated by
|
||||||
|
inspection.
|
||||||
</para>
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
<procedure>
|
<sect2>
|
||||||
<title><productname>Postgres</productname> Regression Test</title>
|
<title>Date and time differences</title>
|
||||||
|
|
||||||
<step performance="required">
|
<para>
|
||||||
<para>
|
Most of the date and time results are dependent on the time zone
|
||||||
Prepare the files needed for the regression test with:
|
environment. The reference files are generated for time zone
|
||||||
<programlisting>
|
PST8PDT (Berkeley, California) and there will be apparent
|
||||||
cd /usr/src/pgsql/src/test/regress
|
failures if the tests are not run with that time zone setting.
|
||||||
gmake clean
|
The regression test driver sets environment variable
|
||||||
gmake all
|
<envar>PGTZ</envar> to <literal>PST8PDT</literal> to ensure
|
||||||
</programlisting>
|
proper results. However, your system must provide library
|
||||||
You can skip "gmake clean" if this is the first time you
|
support for the PST8PDT time zone, or the time zone-dependent
|
||||||
are running the tests.
|
tests will fail. To verify that your machine does have this
|
||||||
</para>
|
support, type the following:
|
||||||
<para>
|
<screen>
|
||||||
This step compiles a <acronym>C</acronym>
|
<prompt>$ </prompt><userinput>env TZ=PST8PDT date</userinput>
|
||||||
program with PostgreSQL extension functions into a shared library.
|
</screen>
|
||||||
Localized SQL scripts and output-comparison files are also created
|
The command above should have returned the current system time in
|
||||||
for the tests that need them. The localization replaces macros in
|
the PST8PDT time zone. If the PST8PDT database is not available,
|
||||||
the source files with absolute pathnames and user names.
|
then your system may have returned the time in GMT. If the
|
||||||
</para>
|
PST8PDT time zone is not available, you can set the time zone
|
||||||
</step>
|
rules explicitly:
|
||||||
|
<programlisting>
|
||||||
<step performance="optional">
|
PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ
|
||||||
<para>
|
</programlisting>
|
||||||
If you intend to use the "sequential" test procedure, which tests
|
|
||||||
an already-installed postmaster, be sure that the postmaster
|
|
||||||
is running. If it isn't already running,
|
|
||||||
start the postmaster in an available window by typing
|
|
||||||
<programlisting>
|
|
||||||
postmaster
|
|
||||||
</programlisting>
|
|
||||||
or start the postmaster daemon running in the background by typing
|
|
||||||
<programlisting>
|
|
||||||
cd
|
|
||||||
nohup postmaster > regress.log 2>&1 &
|
|
||||||
</programlisting>
|
|
||||||
The latter is probably preferable, since the regression test log
|
|
||||||
will be quite lengthy (60K or so, in
|
|
||||||
<productname>Postgres</productname> 7.0) and you might want to
|
|
||||||
review it for clues if things go wrong.
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
Do not run <filename>postmaster</filename> from the root account.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
Run the regression tests. For a sequential test, type
|
|
||||||
<programlisting>
|
|
||||||
cd /usr/src/pgsql/src/test/regress
|
|
||||||
gmake runtest
|
|
||||||
</programlisting>
|
|
||||||
For a parallel test, type
|
|
||||||
<programlisting>
|
|
||||||
cd /usr/src/pgsql/src/test/regress
|
|
||||||
gmake runcheck
|
|
||||||
</programlisting>
|
|
||||||
The sequential test just runs the test scripts using your
|
|
||||||
already-running postmaster.
|
|
||||||
The parallel test will perform a complete installation of
|
|
||||||
<productname>Postgres</productname> into a temporary directory,
|
|
||||||
start a private postmaster therein, and then run the test scripts.
|
|
||||||
Finally it will kill the private postmaster (but the temporary
|
|
||||||
directory isn't removed automatically).
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
You should get on the screen (and also written to file ./regress.out)
|
|
||||||
a series of statements stating which tests passed and which tests
|
|
||||||
failed. Please note that it can be normal for some of the tests to
|
|
||||||
"fail" due to platform-specific variations. See the next section
|
|
||||||
for details on determining whether a "failure" is significant.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Some of the tests, notably "numeric", can take a while, especially
|
|
||||||
on slower platforms. Have patience.
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step performance="required">
|
|
||||||
<para>
|
|
||||||
After running the tests and examining the results, type
|
|
||||||
<programlisting>
|
|
||||||
cd /usr/src/pgsql/src/test/regress
|
|
||||||
gmake clean
|
|
||||||
</programlisting>
|
|
||||||
to recover the temporary disk space used by the tests.
|
|
||||||
If you ran a sequential test, also type
|
|
||||||
<programlisting>
|
|
||||||
dropdb regression
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</step>
|
|
||||||
</procedure>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="regress-analysis">
|
|
||||||
<title>Regression Analysis</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The actual outputs of the regression tests are in files in the
|
|
||||||
<filename>./results</filename> directory. The test script
|
|
||||||
uses <application>diff</application> to compare each output file
|
|
||||||
against the reference outputs stored in the
|
|
||||||
<filename>./expected</filename> directory. Any differences are
|
|
||||||
saved for your inspection in
|
|
||||||
<filename>./regression.diffs</filename>. (Or you can run
|
|
||||||
<application>diff</application> yourself, if you prefer.)
|
|
||||||
</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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Thus, it is necessary to examine the actual differences for each
|
There appear to be some systems which do not accept the
|
||||||
"failed" test to determine whether there is really a problem.
|
recommended syntax for explicitly setting the local time zone
|
||||||
The following paragraphs attempt to provide some guidance in
|
rules; you may need to use a different <envar>PGTZ</envar>
|
||||||
determining whether a difference is significant or not.
|
setting on such machines.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<sect2>
|
<para>
|
||||||
<title>Error message differences</title>
|
Some systems using older time zone libraries fail to apply
|
||||||
|
daylight-savings corrections to dates before 1970, causing
|
||||||
|
pre-1970 PDT times to be displayed in PST instead. This will
|
||||||
|
result in localized differences in the test results.
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Some of the regression tests involve intentional invalid input values.
|
Some of the queries in the <quote>timestamp</quote> test will
|
||||||
Error messages can come from either the Postgres code or from the host
|
fail if you run the test on the day of a daylight-savings time
|
||||||
platform system routines. In the latter case, the messages may vary
|
changeover, or the day before or after one. These queries assume
|
||||||
between platforms, but should reflect similar information. These
|
that the intervals between midnight yesterday, midnight today and
|
||||||
differences in messages will result in a "failed" regression test which
|
midnight tomorrow are exactly twenty-four hours -- which is wrong
|
||||||
can be validated by inspection.
|
if daylight-savings time went into or out of effect meanwhile.
|
||||||
</para>
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
</sect2>
|
<sect2>
|
||||||
|
<title>Floating point differences</title>
|
||||||
|
|
||||||
<sect2>
|
<para>
|
||||||
<title>Date and time differences</title>
|
Some of the tests involve computing 64-bit (<type>double
|
||||||
|
precision</type>) numbers from table columns. Differences in
|
||||||
|
results involving mathematical functions of <type>double
|
||||||
|
precision</type> columns have been observed. The float8 and
|
||||||
|
geometry tests are particularly prone to small differences across
|
||||||
|
platforms, or even with different compiler optimization options.
|
||||||
|
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>
|
<para>
|
||||||
Most of the date and time results are dependent on timezone environment.
|
Some systems signal errors from <function>pow()</function> and
|
||||||
The reference files are generated for timezone PST8PDT (Berkeley,
|
<function>exp()</function> differently from the mechanism
|
||||||
California) and there will be apparent failures if the tests are not
|
expected by the current <productname>PostgreSQL</productname>
|
||||||
run with that timezone setting. The regression test driver sets
|
code.
|
||||||
environment variable PGTZ to PST8PDT to ensure proper results.
|
</para>
|
||||||
</para>
|
</sect2>
|
||||||
|
|
||||||
<para>
|
<sect2>
|
||||||
Some of the queries in the "timestamp" test will fail if you run
|
<title>Polygon differences</title>
|
||||||
the test on the day of a daylight-savings time changeover, or the
|
|
||||||
day before or after one. These queries assume that the intervals
|
|
||||||
between midnight yesterday, midnight today and midnight tomorrow are
|
|
||||||
exactly twenty-four hours ... which is wrong if daylight-savings time
|
|
||||||
went into or out of effect meanwhile.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There appear to be some systems which do not accept the recommended syntax
|
Several of the tests involve operations on geographic data about
|
||||||
for explicitly setting the local time zone rules; you may need to use
|
the Oakland/Berkeley, CA street map. The map data is expressed as
|
||||||
a different PGTZ setting on such machines.
|
polygons whose vertices are represented as pairs of <type>double
|
||||||
</para>
|
precision</type> numbers (decimal latitude and
|
||||||
|
longitude). Initially, some tables are created and loaded with
|
||||||
|
geographic data, then some views are created which join two
|
||||||
|
tables using the polygon intersection operator
|
||||||
|
(<literal>##</literal>), then a select is done on the view.
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Some systems using older timezone libraries fail to apply daylight-savings
|
When comparing the results from different platforms, differences
|
||||||
corrections to pre-1970 dates, causing pre-1970 PDT times to be displayed
|
occur in the 2nd or 3rd place to the right of the decimal
|
||||||
in PST instead. This will result in localized differences in the test
|
point. The SQL statements where these problems occur are the
|
||||||
results.
|
following:
|
||||||
</para>
|
<programlisting>
|
||||||
|
SELECT * from street;
|
||||||
|
SELECT * from iexit;
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
</sect2>
|
<sect2>
|
||||||
|
<title>The <quote>random</quote> test</title>
|
||||||
<sect2>
|
|
||||||
<title>Floating point differences</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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. 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>
|
|
||||||
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>Polygon differences</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Several of the tests involve operations on geographic date about the
|
|
||||||
Oakland/Berkley CA street map. The map data is expressed as polygons
|
|
||||||
whose vertices are represented as pairs of <type>float8</type> numbers (decimal
|
|
||||||
latitude and longitude). Initially, some tables are created and
|
|
||||||
loaded with geographic data, then some views are created which join
|
|
||||||
two tables using the polygon intersection operator (##), then a select
|
|
||||||
is done on the view.
|
|
||||||
|
|
||||||
When comparing the results from different platforms, differences occur
|
|
||||||
in the 2nd or 3rd place to the right of the decimal point. The SQL
|
|
||||||
statements where these problems occur are the following:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
QUERY: SELECT * from street;
|
|
||||||
QUERY: SELECT * from iexit;
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>Random differences</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
There is at least one case in the "random" test script that is
|
|
||||||
intended to produce
|
|
||||||
random results. This causes random to fail the regression test
|
|
||||||
once in a while (perhaps once in every five to ten trials).
|
|
||||||
Typing
|
|
||||||
<programlisting>
|
|
||||||
diff results/random.out expected/random.out
|
|
||||||
</programlisting>
|
|
||||||
should produce only one or a few lines of differences. You need
|
|
||||||
not worry unless the random test always fails in repeated attempts.
|
|
||||||
(On the other hand, if the random test is <emphasis>never</emphasis>
|
|
||||||
reported to fail even in many trials of the regress tests, you
|
|
||||||
probably <emphasis>should</emphasis> worry.)
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>The "expected" files</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <filename>./expected/*.out</filename> files were adapted from the original monolithic
|
|
||||||
<filename>expected.input</filename> file provided by Jolly Chen et al. Newer versions of these
|
|
||||||
files generated on various development machines have been substituted after
|
|
||||||
careful (?) inspection. Many of the development machines are running a
|
|
||||||
Unix OS variant (FreeBSD, Linux, etc) on Ix86 hardware.
|
|
||||||
|
|
||||||
The original <filename>expected.input</filename> file was created on a SPARC Solaris 2.4
|
|
||||||
system using the <filename>postgres5-1.02a5.tar.gz</filename> source tree. It was compared
|
|
||||||
with a file created on an I386 Solaris 2.4 system and the differences
|
|
||||||
were only in the floating point polygons in the 3rd digit to the right
|
|
||||||
of the decimal point.
|
|
||||||
|
|
||||||
The original <filename>sample.regress.out</filename> file was from the postgres-1.01 release
|
|
||||||
constructed by Jolly Chen. It may
|
|
||||||
have been created on a DEC ALPHA machine as the <filename>Makefile.global</filename>
|
|
||||||
in the postgres-1.01 release has PORTNAME=alpha.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There is at least one case in the <quote>random</quote> test
|
||||||
|
script that is intended to produce random results. This causes
|
||||||
|
random to fail the regression test once in a while (perhaps once
|
||||||
|
in every five to ten trials). Typing
|
||||||
|
<programlisting>
|
||||||
|
diff results/random.out expected/random.out
|
||||||
|
</programlisting>
|
||||||
|
should produce only one or a few lines of differences. You need
|
||||||
|
not worry unless the random test always fails in repeated
|
||||||
|
attempts. (On the other hand, if the random test is
|
||||||
|
<emphasis>never</emphasis> reported to fail even in many trials
|
||||||
|
of the regress tests, you probably <emphasis>should</emphasis>
|
||||||
|
worry.)
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
<!-- We might want to move the following section into the developer's guide. -->
|
||||||
<sect1 id="regress-platform">
|
<sect1 id="regress-platform">
|
||||||
<title>Platform-specific comparison files</title>
|
<title>Platform-specific comparison files</title>
|
||||||
|
|
||||||
|
@ -1,241 +1,223 @@
|
|||||||
|
REGRESSION TESTS
|
||||||
|
|
||||||
Introduction
|
The regression tests are a comprehensive set of tests for the SQL
|
||||||
|
implementation in PostgreSQL. They test standard SQL operations as
|
||||||
|
well as the extended capabilities of PostgreSQL. The test suite was
|
||||||
|
originally developed by Jolly Chen and Andrew Yu, and was extensively
|
||||||
|
revised and repackaged by Marc Fournier and Thomas Lockhart. From
|
||||||
|
PostgreSQL 6.1 onward the regression tests are current for every
|
||||||
|
official release.
|
||||||
|
|
||||||
The PostgreSQL regression tests are a comprehensive set of tests for the
|
The regression test can be run against an already installed and
|
||||||
SQL implementation embedded in PostgreSQL. They test standard SQL
|
running server, or using a temporary installation within the build
|
||||||
operations as well as the extended capabilities of PostgreSQL.
|
tree. Furthermore, there is a "parallel" and a "sequential" mode for
|
||||||
|
running the tests. The sequential method runs each test script in
|
||||||
|
turn, whereas the parallel method starts up multiple server processes
|
||||||
|
to run groups of tests in parallel. Parallel testing gives confidence
|
||||||
|
that interprocess communication and locking are working correctly. For
|
||||||
|
historical reasons, the sequential test is usually run against an
|
||||||
|
existing installation and the parallel method "stand-alone", but there
|
||||||
|
are technical reasons for this.
|
||||||
|
|
||||||
The regression tests were originally developed by Jolly Chen and Andrew Yu,
|
To run the regression tests after building but before installation,
|
||||||
and were extensively revised/repackaged by Marc Fournier and Thomas Lockhart.
|
type
|
||||||
From PostgreSQL v6.1 onward the regression tests are current for every
|
|
||||||
official release.
|
|
||||||
|
|
||||||
Some properly installed and fully functional PostgreSQL installations
|
$ gmake check
|
||||||
can fail some of these regression tests due to artifacts of floating point
|
|
||||||
representation and time zone support. The current tests are evaluated
|
|
||||||
using a simple "diff" algorithm, and are sensitive to small system
|
|
||||||
differences. For apparently failed tests, examining the differences
|
|
||||||
may reveal that the differences are not significant.
|
|
||||||
|
|
||||||
Preparation
|
in the top-level directory. (Or you can change to src/test/regress and
|
||||||
|
run the command there.) This will first build several auxiliary files,
|
||||||
|
such as platform-dependent "expected" files and some sample
|
||||||
|
user-defined trigger functions, and then run the test driver
|
||||||
|
script. At the end you should see something like
|
||||||
|
|
||||||
To prepare for regression testing, do "make all" in the regression test
|
======================
|
||||||
directory. This compiles a 'C' program with PostgreSQL extension functions
|
All 75 tests passed.
|
||||||
into a shared library. Localized SQL scripts and output-comparison
|
======================
|
||||||
files are also created for the tests that need them. The localization
|
|
||||||
replaces macros in the source files with absolute pathnames and user names.
|
|
||||||
|
|
||||||
Normally, the regression tests should be run as the postgres user since
|
or otherwise a note about what tests failed. See the section called
|
||||||
the 'src/test/regress' directory and sub-directories are owned by the
|
Test Evaluation below for more.
|
||||||
postgres user. If you run the regression test as another user the
|
|
||||||
'src/test/regress' directory tree must be writeable to that user.
|
|
||||||
|
|
||||||
It was formerly necessary to run the postmaster with system time zone
|
Note: Because this test method runs a temporary server, it will
|
||||||
set to PST, but this is no longer required. You can run the regression
|
not work when you are the root user (the server will not start as
|
||||||
tests under your normal postmaster configuration. The test script will
|
root). If you already did the build as root, you do not have to
|
||||||
set the PGTZ environment variable to ensure that timezone-dependent tests
|
start all over. Instead, make the regression test directory
|
||||||
produce the expected results.
|
writable by some other user, log in as that user, and restart the
|
||||||
|
tests.
|
||||||
|
|
||||||
Directory Layout
|
root# chmod -R a+w src/test/regress
|
||||||
|
root# su - joeuser
|
||||||
|
joeuser$ gmake check
|
||||||
|
|
||||||
input/ .... .source files that are converted using 'make all' into
|
(The only possible "security risk" here is that other users might
|
||||||
some of the .sql files in the 'sql' subdirectory
|
be able to alter the regression test results behind your back. Use
|
||||||
|
common sense when managing user permissions.)
|
||||||
|
|
||||||
output/ ... .source files that are converted using 'make all' into
|
Alternatively, run the tests after installation.
|
||||||
.out files in the 'expected' subdirectory
|
|
||||||
|
|
||||||
sql/ ...... .sql files used to perform the regression tests
|
Tip: On some systems, the default Bourne-compatible shell
|
||||||
|
(/bin/sh) gets confused when it has to manage too many child
|
||||||
|
processes in parallel. This may cause the parallel test run to
|
||||||
|
lock up or fail. In such cases, specify a different
|
||||||
|
Bourne-compatible shell on the command line, for example:
|
||||||
|
|
||||||
expected/ . .out files that represent what we *expect* the results to
|
$ gmake SHELL=/bin/ksh check
|
||||||
look like
|
|
||||||
|
|
||||||
results/ .. .out files that contain what the results *actually* look
|
To run the tests after installation, initialize a data area and start
|
||||||
like. Also used as temporary storage for table copy testing.
|
the server, then type
|
||||||
|
|
||||||
Running the regression test
|
$ gmake installcheck
|
||||||
|
|
||||||
If you have previously run the regression test for a different Postgres
|
The server is expected to be running on the local host with the
|
||||||
release, make sure you have up-to-date comparison files by doing
|
default port number.
|
||||||
|
|
||||||
make clean all
|
Test Evaluation
|
||||||
|
|
||||||
The regression test is invoked with the command:
|
Some properly installed and fully functional PostgreSQL installations
|
||||||
|
can "fail" some of these regression tests due to artifacts of floating
|
||||||
|
point representation and time zone support. The tests are currently
|
||||||
|
evaluated using a simple diff comparison against the outputs generated
|
||||||
|
on a reference system, so the results are sensitive to small system
|
||||||
|
differences. When a test is reported as "failed", always examine the
|
||||||
|
differences between expected and actual results; you may well find
|
||||||
|
that the differences are not significant. Nonetheless, we still strive
|
||||||
|
to maintain accurate reference files across all supported platforms,
|
||||||
|
so it can be expected that all tests pass.
|
||||||
|
|
||||||
make runtest
|
The actual outputs of the regression tests are in files in the
|
||||||
|
src/test/regress/results directory. The test script uses diff to
|
||||||
or you can do
|
compare each output file against the reference outputs stored in the
|
||||||
|
src/test/regress/expected directory. Any differences are saved for
|
||||||
make runcheck
|
your inspection in src/test/regress/regression.diffs. (Or you can run
|
||||||
|
diff yourself, if you prefer.)
|
||||||
which invokes a parallel form of the regress tests, and does not
|
|
||||||
need an already-installed postmaster. Instead, runcheck creates
|
|
||||||
a temporary installation under the regress directory.
|
|
||||||
|
|
||||||
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 test script now does this for you, and leaves the differences
|
|
||||||
in ./regression.diffs.)
|
|
||||||
|
|
||||||
The files might not compare exactly. The following paragraphs attempt
|
|
||||||
to explain the differences.
|
|
||||||
|
|
||||||
Once the output files have been verified for a particular platform,
|
|
||||||
it is possible to provide new platform-specific comparison files,
|
|
||||||
so that future test runs won't report bogus "failures". See
|
|
||||||
'Platform-specific comparison files', below.
|
|
||||||
|
|
||||||
Error message differences
|
Error message differences
|
||||||
|
|
||||||
Some of the regression tests involve intentional invalid input values.
|
Some of the regression tests involve intentional invalid input
|
||||||
Error messages can come from either the Postgres code or from the host
|
values. Error messages can come from either the PostgreSQL code or
|
||||||
platform system routines. In the latter case, the messages may vary
|
from the host platform system routines. In the latter case, the
|
||||||
between platforms, but should reflect similar information. These
|
messages may vary between platforms, but should reflect similar
|
||||||
differences in messages will result in a "failed" regression test which
|
information. These differences in messages will result in a "failed"
|
||||||
can be validated by inspection.
|
regression test which can be validated by inspection.
|
||||||
|
|
||||||
DATE/TIME differences
|
Date and time differences
|
||||||
|
|
||||||
Most of the date and time results are dependent on timezone environment.
|
Most of the date and time results are dependent on the time zone
|
||||||
The reference files are generated for timezone PST8PDT (Berkeley,
|
environment. The reference files are generated for time zone PST8PDT
|
||||||
California) and there will be apparent failures if the tests are not
|
(Berkeley, California) and there will be apparent failures if the
|
||||||
run with that timezone setting. The regression test driver sets
|
tests are not run with that time zone setting. The regression test
|
||||||
environment variable PGTZ to PST8PDT to ensure proper results.
|
driver sets environment variable PGTZ to PST8PDT to ensure proper
|
||||||
|
results. However, your system must provide library support for the
|
||||||
|
PST8PDT time zone, or the time zone-dependent tests will fail. To
|
||||||
|
verify that your machine does have this support, type the following:
|
||||||
|
|
||||||
There appear to be some systems which do not accept the recommended syntax
|
$ env TZ=PST8PDT date
|
||||||
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
|
The command above should have returned the current system time in the
|
||||||
corrections to pre-1970 dates, causing pre-1970 PDT times to be displayed
|
PST8PDT time zone. If the PST8PDT database is not available, then your
|
||||||
in PST instead. This will result in localized differences in the test
|
system may have returned the time in GMT. If the PST8PDT time zone is
|
||||||
results.
|
not available, you can set the time zone rules explicitly:
|
||||||
|
|
||||||
FLOATING POINT differences
|
PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ
|
||||||
|
|
||||||
Some of the tests involve computing 64-bit (FLOAT8) numbers from table
|
There appear to be some systems which do not accept the recommended
|
||||||
columns. Differences in results involving mathematical functions of
|
syntax for explicitly setting the local time zone rules; you may need
|
||||||
FLOAT8 columns have been observed. These differences occur where
|
to use a different PGTZ setting on such machines.
|
||||||
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.
|
|
||||||
|
|
||||||
Human eyeball comparison is needed to determine the real significance
|
Some systems using older time zone libraries fail to apply
|
||||||
of these differences which are usually 10 places to the right of
|
daylight-savings corrections to dates before 1970, causing pre-1970
|
||||||
the decimal point.
|
PDT times to be displayed in PST instead. This will result in
|
||||||
|
localized differences in the test results.
|
||||||
|
|
||||||
Some systems signal errors from pow() and exp() differently from
|
Some of the queries in the "timestamp" test will fail if you run the
|
||||||
the mechanism expected by the current Postgres code.
|
test on the day of a daylight-savings time changeover, or the day
|
||||||
|
before or after one. These queries assume that the intervals between
|
||||||
|
midnight yesterday, midnight today and midnight tomorrow are exactly
|
||||||
|
twenty-four hours -- which is wrong if daylight-savings time went into
|
||||||
|
or out of effect meanwhile.
|
||||||
|
|
||||||
POLYGON differences
|
Floating point differences
|
||||||
|
|
||||||
Several of the tests involve operations on geographic data about the
|
Some of the tests involve computing 64-bit (double precision) numbers
|
||||||
Oakland/Berkley CA street map. The map data is expressed as polygons
|
from table columns. Differences in results involving mathematical
|
||||||
whose vertices are represented as pairs of FLOAT8 numbers (decimal
|
functions of double precision columns have been observed. The float8
|
||||||
latitude and longitude). Initially, some tables are created and
|
and geometry tests are particularly prone to small differences across
|
||||||
loaded with geographic data, then some views are created which join
|
platforms, or even with different compiler optimization options. Human
|
||||||
two tables using the polygon intersection operator (##), then a select
|
eyeball comparison is needed to determine the real significance of
|
||||||
is done on the view.
|
these differences which are usually 10 places to the right of the
|
||||||
|
decimal point.
|
||||||
|
|
||||||
When comparing the results from different platforms, differences occur
|
Some systems signal errors from pow() and exp() differently from the
|
||||||
in the 2nd or 3rd place to the right of the decimal point. The SQL
|
mechanism expected by the current PostgreSQL code.
|
||||||
statements where these problems occur are the following:
|
|
||||||
|
|
||||||
QUERY: SELECT * from street;
|
Polygon differences
|
||||||
QUERY: SELECT * from iexit;
|
|
||||||
|
|
||||||
Random differences
|
Several of the tests involve operations on geographic data about the
|
||||||
|
Oakland/Berkeley, CA street map. The map data is expressed as polygons
|
||||||
|
whose vertices are represented as pairs of double precision numbers
|
||||||
|
(decimal latitude and longitude). Initially, some tables are created
|
||||||
|
and loaded with geographic data, then some views are created which
|
||||||
|
join two tables using the polygon intersection operator (##), then a
|
||||||
|
select is done on the view.
|
||||||
|
|
||||||
There is at least one test case in random.out which is intended to produce
|
When comparing the results from different platforms, differences occur
|
||||||
random results. This causes random to fail the regression testing.
|
in the 2nd or 3rd place to the right of the decimal point. The SQL
|
||||||
Typing "diff results/random.out expected/random.out" should produce only
|
statements where these problems occur are the following:
|
||||||
one or a few lines of differences for this reason, but other floating
|
|
||||||
point differences on dissimilar architectures might cause many more
|
|
||||||
differences. See the release notes below.
|
|
||||||
|
|
||||||
The 'expected' files
|
SELECT * from street;
|
||||||
|
SELECT * from iexit;
|
||||||
|
|
||||||
The ./expected/*.out files were adapted from the original monolithic
|
The "random" test
|
||||||
'expected.input' file provided by Jolly Chen et al. Newer versions of these
|
|
||||||
files generated on various development machines have been substituted after
|
There is at least one case in the "random" test script that is
|
||||||
careful (?) inspection. Many of the development machines are running a
|
intended to produce random results. This causes random to fail the
|
||||||
Unix OS variant (FreeBSD, Linux, etc) on Ix86 hardware.
|
regression test once in a while (perhaps once in every five to ten
|
||||||
|
trials). Typing
|
||||||
|
|
||||||
|
diff results/random.out expected/random.out
|
||||||
|
|
||||||
|
should produce only one or a few lines of differences. You need not
|
||||||
|
worry unless the random test always fails in repeated attempts. (On
|
||||||
|
the other hand, if the random test is never reported to fail even in
|
||||||
|
many trials of the regress tests, you probably should worry.)
|
||||||
|
|
||||||
Platform-specific comparison files
|
Platform-specific comparison files
|
||||||
|
|
||||||
Since some of the tests inherently produce platform-specific results,
|
Since some of the tests inherently produce platform-specific results,
|
||||||
we have provided a way to supply platform-specific result comparison
|
we have provided a way to supply platform-specific result comparison
|
||||||
files. Frequently, the same variation applies to multiple platforms;
|
files. Frequently, the same variation applies to multiple platforms;
|
||||||
rather than supplying a separate comparison file for every platform,
|
rather than supplying a separate comparison file for every platform,
|
||||||
there is a mapping file that defines which comparison file to use.
|
there is a mapping file that defines which comparison file to use. So,
|
||||||
So, to eliminate bogus test "failures" for a particular platform,
|
to eliminate bogus test "failures" for a particular platform, you must
|
||||||
you must choose or make a variant result file, and then add a line
|
choose or make a variant result file, and then add a line to the
|
||||||
to the mapping file, which is "resultmap".
|
mapping file, which is "resultmap".
|
||||||
|
|
||||||
Each line in the mapping file is of the form
|
Each line in the mapping file is of the form
|
||||||
testname/platformnamepattern=comparisonfilename
|
|
||||||
The test name is just the name of the particular regression test module.
|
testname/platformnamepattern=comparisonfilename
|
||||||
The platform name pattern is a pattern in the style of expr(1) (that is,
|
|
||||||
a regular expression with an implicit ^ anchor at the start). It is matched
|
The test name is just the name of the particular regression test
|
||||||
against the platform name as printed by config.guess. The comparison
|
module. The platform name pattern is a pattern in the style of expr(1)
|
||||||
file name is the name of the substitute result comparison file.
|
(that is, a regular expression with an implicit ^ anchor at the
|
||||||
|
start). It is matched against the platform name as printed by
|
||||||
|
config.guess. The comparison file name is the name of the substitute
|
||||||
|
result comparison file.
|
||||||
|
|
||||||
|
For example: the int2 regress test includes a deliberate entry of a
|
||||||
|
value that is too large to fit in int2. The specific error message
|
||||||
|
that is produced is platform-dependent; our reference platform emits
|
||||||
|
|
||||||
For example: the int2 regress test includes a deliberate entry of a value
|
|
||||||
that is too large to fit in int2. The specific error message that is
|
|
||||||
produced is platform-dependent; our reference platform emits
|
|
||||||
ERROR: pg_atoi: error reading "100000": Numerical result out of range
|
ERROR: pg_atoi: error reading "100000": Numerical result out of range
|
||||||
but a fair number of other Unix platforms emit
|
|
||||||
|
but a fair number of other Unix platforms emit
|
||||||
|
|
||||||
ERROR: pg_atoi: error reading "100000": Result too large
|
ERROR: pg_atoi: error reading "100000": Result too large
|
||||||
Therefore, we provide a variant comparison file, int2-too-large.out,
|
|
||||||
that includes this spelling of the error message. To silence the
|
|
||||||
bogus "failure" message on HPPA platforms, resultmap includes
|
|
||||||
int2/hppa=int2-too-large
|
|
||||||
which will trigger on any machine for which config.guess's output
|
|
||||||
begins with 'hppa'. Other lines in resultmap select the variant
|
|
||||||
comparison file for other platforms where it's appropriate.
|
|
||||||
|
|
||||||
Current release notes (Thomas.Lockhart@jpl.nasa.gov)
|
Therefore, we provide a variant comparison file, int2-too-large.out,
|
||||||
|
that includes this spelling of the error message. To silence the bogus
|
||||||
|
"failure" message on HPPA platforms, resultmap includes
|
||||||
|
|
||||||
The regression tests have been adapted and extensively modified for the
|
int2/hppa=int2-too-large
|
||||||
v6.1 release of PostgreSQL.
|
|
||||||
|
|
||||||
Three new data types (datetime, timespan, and circle) have been added to
|
which will trigger on any machine for which config.guess's output
|
||||||
the native set of PostgreSQL types. Points, boxes, paths, and polygons
|
begins with 'hppa'. Other lines in resultmap select the variant
|
||||||
have had their output formats made consistant across the data types.
|
comparison file for other platforms where it's appropriate.
|
||||||
The polygon output in misc.out has only been spot-checked for correctness
|
|
||||||
relative to the original regression output.
|
|
||||||
|
|
||||||
PostgreSQL v6.1 introduces a new, alternate optimizer which uses "genetic"
|
|
||||||
algorithms. These algorithms introduce a random behavior in the ordering
|
|
||||||
of query results when the query contains multiple qualifiers or multiple
|
|
||||||
tables (giving the optimizer a choice on order of evaluation). Several
|
|
||||||
regression tests have been modified to explicitly order the results, and
|
|
||||||
hence are insensitive to optimizer choices. A few regression tests are
|
|
||||||
for data types which are inherently unordered (e.g. points and time
|
|
||||||
intervals) and tests involving those types are explicitly bracketed with
|
|
||||||
"set geqo to 'off'" and "reset geqo".
|
|
||||||
|
|
||||||
The interpretation of array specifiers (the curly braces around atomic
|
|
||||||
values) appears to have changed sometime after the original regression
|
|
||||||
tests were generated. The current ./expected/*.out files reflect this
|
|
||||||
new interpretation, which may not be correct!
|
|
||||||
|
|
||||||
The float8 regression test fails on at least some platforms. This is due
|
|
||||||
to differences in implementations of pow() and exp() and the signaling
|
|
||||||
mechanisms used for overflow and underflow conditions.
|
|
||||||
|
|
||||||
The "random" results in the random test should cause the "random" test
|
|
||||||
to be "failed", since the regression tests are evaluated using a simple
|
|
||||||
diff. However, "random" does not seem to produce random results on my
|
|
||||||
test machine (Linux/gcc/i686).
|
|
||||||
|
|
||||||
Sample timing results
|
|
||||||
|
|
||||||
Timing under Linux 2.0.27 seems to have a roughly 5% variation from run
|
|
||||||
to run, presumably due to the timing vagaries of multitasking systems.
|
|
||||||
|
|
||||||
Time System
|
|
||||||
06:12 Pentium Pro 180, 32MB, Linux 2.0.30, gcc 2.7.2 -O2 -m486
|
|
||||||
12:06 P-100, 48MB, Linux 2.0.29, gcc
|
|
||||||
39:58 Sparc IPC 32MB, Solaris 2.5, gcc 2.7.2.1 -O -g
|
|
||||||
|
Reference in New Issue
Block a user