From: Tom Lane Date: Sat, 24 Oct 1998 22:05:01 +0000 (+0000) Subject: Update instructions for running configure (the old ones X-Git-Tag: REL6_4_2~150 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=82f54c9d2c68298818f750a8b1fa8743cad8b1ef;p=postgresql Update instructions for running configure (the old ones seem to date from some pre-autoconf interactive configure script). Revise sequence of instructions to allow you to start the regular postmaster run before running regression tests; there's no need to start and kill a special postmaster for regression tests. Update the description of interpreting regression test results. --- diff --git a/doc/src/sgml/install.sgml b/doc/src/sgml/install.sgml index 2a938ee708..fde80ebdc0 100644 --- a/doc/src/sgml/install.sgml +++ b/doc/src/sgml/install.sgml @@ -3,17 +3,15 @@ -Complete installation instructions for Postgres v6.3. +Complete installation instructions for Postgres +v6.4. - This procedure is -This is based on the installation instructions -for Postgres v6.3 -found in $PGROOT/INSTALL. - Up to date information on Postgres may be found at -www.postgresql.org. +Before installing Postgres, you may wish to visit +www.postgresql.org +for up to date information, patches, etc. @@ -54,19 +52,19 @@ platform. Use common sense before typing in these commands. -Our Makefiles require GNU make (called gmake in this document) and -also assume that install accepts BSD options. The INSTALL -variable in the Makefiles is set to the BSD-compatible version of -install. On some systems, you will have to find a BSD-compatible -install (eg. bsdinst, which comes with the MIT X Window System -distribution). +Our Makefiles require GNU make (called +gmake in this document). They will not +work with non-GNU make programs. If you +have GNU make installed under the name +make instead of gmake, that's OK, but +you need to have it. Requirements to Run <ProductName>Postgres</ProductName> -Information on supported platforms is another chapter. In general, most Unix-compatible +Information on supported platforms is in another chapter. In general, most Unix-compatible platforms with modern libraries should be able to run Postgres. @@ -155,7 +153,7 @@ Check that you have sufficient disk space. You will need about -Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.3.tar.gz from the +Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz from the Internet. Store it in your home directory. @@ -217,7 +215,7 @@ If you are upgrading an existing system then back up your database. and the following line typed as one line): cd - gunzip -c postgresql-v6.3.tar.gz | + gunzip -c postgresql-v6.4.tar.gz | tar xvf - src/bin/pg_dump/pg_dumpall chmod a+x src/bin/pg_dump/pg_dumpall src/bin/pg_dump/pg_dumpall > db.out @@ -316,7 +314,7 @@ If you are upgrading an existing system then move the old directories Unzip and untar the new source file. Type cd /usr/src/pgsql - gunzip -c ~/postgresql-v6.3.tar.gz | tar xvf - + gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf - @@ -324,59 +322,71 @@ If you are upgrading an existing system then move the old directories Configure the source code for your system. It is this step at which - you can specify your actual source path and installation paths for + you can specify your actual installation path for the build process (see the --prefix option below). Type cd /usr/src/pgsql/src - ./configure + ./configure [ options as described below ] - The configure program will list the template files available and - ask you to choose one. A lot of times, an appropriate template - file is chosen for you, and you can just press Enter to accept the - default. If the default is not appropriate, then type in the - appropriate template file and press Enter. (If you do this, then + Among other chores, the configure script selects a system-specific + "template" file from the files provided in the template subdirectory. + If it cannot guess which one to use for your system, it will say so and + exit. In that case you'll need to figure out which one to use and run + configure again, this time giving the --with-template=TEMPLATE option to + make the right file be chosen. (If you have to do this, please send email to scrappy@hub.org stating the output of the program './config.guess' and what the template file should be.) - Once you have entered the template file, you will be asked a - number of questions about your particular configuration. These - can be skipped by adding parameters to the configure command above. - The following parameters can be tagged onto the end of the configure - command: - + The configure script accepts many additional options that you can use + if you don't like the default configuration. To see them all, type + + ./configure --help + + Some of the more commonly used ones are: --prefix=BASEDIR Selects a different base directory for the installation of the Postgres configuration. The default is /usr/local/pgsql. + --with-template=TEMPLATE + Use template file TEMPLATE - the template + files are assumed to be in the directory + src/template, so look there for proper values. + + --with-pgport=PORT Sets the port that the postmaster process + listens for incoming connections on. The + default is port 5432. + + --with-tcl Build interface libraries and programs requiring + Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh. + + --with-perl Build the Perl interface library. + + --with-odbc Build the ODBC driver package. + --enable-hba Enables Host Based Authentication (DEFAULT) --disable-hba Disables Host Based Authentication --enable-locale Enables USE_LOCALE - --disable-locale Disables USE_LOCALE (DEFAULT) - --enable-cassert Enables ASSERT_CHECKING - --disable-cassert Disables ASSERT_CHECKING (DEFAULT) - - --with-template=TEMPLATE - Use template file TEMPLATE - the template - files are assumed to be in the directory - src/template, so look there for proper values. - (If the configure script cannot find the - specified template file, it will ask you for - one). + --with-CC=compiler + Use a specific C compiler that the configure + script cannot find. - --with-pgport=PORT Sets the port that the postmaster process - listens for incoming connections on. The - default for this is port 5432. + --with-CXX=compiler + --without-CXX + Use a specific C++ compiler that the configure + script cannot find, or exclude C++ compilation + altogether. (This only affects libpq++ at + present.) @@ -547,35 +557,22 @@ Compile the program. Type included in the file. (If your database is not located in the default location, i.e. if PGDATA is set to point elsewhere, then the location of this file will change accordingly.) This file should be - made read only again once you are finsihed. + made read only again once you are finished. - If you are upgrading from v6.0 you can copy file pg_hba.conf from + If you are upgrading from v6.0 or later you can copy file pg_hba.conf from your old database on top of the one in your new database, rather than - redoing this from scratch. + redoing the file from scratch. -You may wish to skip the regression tests. - However, we think skipping the tests is a BAD idea! - - - - The file /usr/src/pgsql/src/test/regress/README has detailed - instructions for running and interpreting the regression tests. - A short version follows here: - - - Start the postmaster daemon running in the background by typing + Start the postmaster daemon running. Type cd - nohup postmaster > regress.log 2>&1 & + nohup postmaster > server.log 2>&1 & - - - Run postmaster from your Postgres super user account (typically account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT. @@ -583,11 +580,21 @@ You may wish to skip the regression tests. + Run the regression tests. + (You can skip this step if you wish, but + we think skipping the tests is a BAD idea!) + - Run the regression tests. Type + + The file /usr/src/pgsql/src/test/regress/README has detailed + instructions for running and interpreting the regression tests. + A short version follows here: + + + + Type - cd cd /usr/src/pgsql/src/test/regress gmake clean gmake all runtest @@ -595,37 +602,31 @@ You may wish to skip the regression tests. - You do not need to type "gmake clean" if this is the first time you are running the tests. - 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". For the failed tests, use diff to compare the files in - directories ./results and ./expected. If float8 failed, type - something like: - - cd /usr/src/pgsql/src/test/regress - diff -w expected/float8.out results - - - - - - "Failed" tests may have failed due to slightly different error messages, - output formatting, failure to set the timezone correctly for your - platform, etc. "Failures" of this type do not indicate a problem with + "fail". The script says a test has failed if there is any difference + at all between the actual output of the test and the expected output. + Thus, tests may "fail" due to minor differences in wording of error + messages, small differences in floating-point roundoff, etc, between + your system and the regression test reference platform. + "Failures" of this type do not indicate a problem with Postgres. + The file ./regression.diffs contains the textual differences between + the actual test output on your machine and the "expected" output + (which is simply what the reference system produced). You should + carefully examine each difference listed to see whether it appears to + be a significant issue. - For a i686/Linux-ELF platform, no tests failed since this is the - v6.3 regression testing reference platform. + v6.4 regression testing reference platform. @@ -636,45 +637,31 @@ You may wish to skip the regression tests. but the differences are due to minor floating point differences. + + Even if a test result clearly indicates a real failure, it may be a + localized problem that will not affect you. An example is that the + int8 test will fail, producing obviously incorrect output, if your + machine and C compiler do not provide a 64-bit integer data type + (or if they do but configure didn't discover it). This is not + something to worry about unless you need to store 64-bit integers. + + 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.2.1, and that previous versions of Postgres have been - in use successfully for some time now. + intended use of Postgres. The regression + tests are a helpful tool, but they require some study to be useful. - After running the tests, type + After running the regression tests, type destroydb regression cd /usr/src/pgsql/src/test/regress gmake clean - - - - - - - Stop the postmaster as described in step 7. Then restore the - timezone to it's normal setting. If you changed the timezone by - modifying environment variable TZ then one way to do this is to - log out of, then back into, account postgres. - - - - - - - Start the postmaster daemon running. Type - - cd - nohup postmaster > server.log 2>&1 & - - Run postmaster from your Postgres super user account (typically - account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT. + to recover the disk space used for the tests. (You may want to save + the regression.diffs file in another place before doing this.) @@ -715,11 +702,11 @@ You may wish to skip the regression tests. the postmaster process so the parent is init. Note: Unlike most other examples, this one has been tested. - c) In RedHat v4.0 Linux edit file /etc/inittab to contain the + c) In RedHat v4.0 Linux edit file /etc/inittab to add the following single line: pg:2345:respawn:/bin/su - postgres -c "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data - >> /usr/local/pgsql/server.log 2>&1" /dev/null + >> /usr/local/pgsql/server.log 2>&1 - If you are upgrading an existing system then install your old database. + If you are upgrading an existing system then reinstall your old database. Type cd