Re: Can we bring some organization to the configure options list? - Mailing list pgsql-docs
| From | Tom Lane |
|---|---|
| Subject | Re: Can we bring some organization to the configure options list? |
| Date | |
| Msg-id | 11363.1567037768@sss.pgh.pa.us Whole thread Raw |
| In response to | Can we bring some organization to the configure options list? (Tom Lane <tgl@sss.pgh.pa.us>) |
| List | pgsql-docs |
I wrote: > I was just noticing, while answering a user question, the amount of > unorganized urban sprawl we've accumulated in > https://www.postgresql.org/docs/devel/install-procedure.html > We've got practically-essential options like --prefix and > --with-openssl intermixed with obscure portability flags > and options that only developers should take any interest in. > For bonus points, the ordering seems chosen largely by dartboard; > there's certainly no visible plan to it. > I think we should try to improve the situation by dividing the > configure options into categories and/or separating commonly > used options from obscure ones. I don't have any concrete > proposal to make right now, but I am hoping to kick off a > discussion about what such an organization would look like. Hearing nothing but crickets, I took a stab at this myself, ending up with a division into these categories: Installation Locations PostgreSQL Features PostgreSQL Anti-Features Build Process Details Miscellaneous Developer Options plus a separate section for environment variables. This seems to me to work fairly well, though surely it's not the only way things could have been divided. Except for the "Features" section which contains many commonly-used options, there's generally only one or two commonly-used options per section, which I put first. I also added a short para of advice about which options to use, where it seemed helpful. DocBook wasn't happy with putting <sectN> inside a <procedure>'s step list, so I had to move all this stuff out of the installation procedure's step list. I'm not sure whether I like that or not --- it does result in the step list being fairly short and comprehensible, but the info that you need to consult for the "configure" step is now some distance away. It's moot unless somebody knows another way to do the markup, though. Because of relocating and re-ordering the options, the diff is just about unreadable :-(. However, I mostly refrained from changing the descriptions of individual options. They're just ordered differently, and there is more text around them. I did yield to temptation in some small ways though. Comments? regards, tom lane diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 4493862..cdc743c 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -325,12 +325,12 @@ su - postgres <para> Also check that you have sufficient disk space. You will need about - 100 MB for the source tree during compilation and about 20 MB for + 350 MB for the source tree during compilation and about 60 MB for the installation directory. An empty database cluster takes about - 35 MB; databases take about five times the amount of space that a + 40 MB; databases take about five times the amount of space that a flat text file with the same data would take. If you are going to run the regression tests you will temporarily need up to an extra - 150 MB. Use the <command>df</command> command to check free disk + 300 MB. Use the <command>df</command> command to check free disk space. </para> </sect1> @@ -349,8 +349,11 @@ su - postgres <userinput>gunzip postgresql-&version;.tar.gz</userinput> <userinput>tar xf postgresql-&version;.tar</userinput> </screen> - (Use <command>bunzip2</command> instead of <command>gunzip</command> if you - have the <filename>.bz2</filename> file.) + (Use <command>bunzip2</command> instead of <command>gunzip</command> if + you have the <filename>.bz2</filename> file. Also, note that most + modern versions of <command>tar</command> can unpack compressed archives + directly, so you don't really need the + separate <command>gunzip</command> or <command>bunzip2</command> step.) This will create a directory <filename>postgresql-&version;</filename> under the current directory with the <productname>PostgreSQL</productname> sources. @@ -387,10 +390,14 @@ su - postgres This script will run a number of tests to determine values for various system dependent variables and detect any quirks of your operating system, and finally will create several files in the - build tree to record what it found. You can also run - <filename>configure</filename> in a directory outside the source - tree, if you want to keep the build directory separate. This - procedure is also called a + build tree to record what it found. + </para> + + <para> + You can also run <filename>configure</filename> in a directory outside + the source tree, and then build there, if you want to keep the build + directory separate from the original source files. This procedure is + called a <indexterm><primary>VPATH</primary></indexterm><firstterm>VPATH</firstterm> build. Here's how: <screen> @@ -410,8 +417,230 @@ su - postgres <para> You can customize the build and installation process by supplying one - or more of the following command line options to - <filename>configure</filename>: + or more command line options to <filename>configure</filename>. + Typically you would customize the install location, or the set of + optional features that are built. <filename>configure</filename> + has a large number of options, which are described in + <xref linkend="configure-options"/>. + </para> + + <para> + Also, <filename>configure</filename> responds to certain environment + variables, as described in <xref linkend="configure-envvars"/>. + These provide additional ways to customize the configuration. + </para> + </step> + + <step id="build"> + <title>Build</title> + + <para> + To start the build, type either of: +<screen> +<userinput>make</userinput> +<userinput>make all</userinput> +</screen> + (Remember to use <acronym>GNU</acronym> <application>make</application>.) + The build will take a few minutes depending on your + hardware. The last line displayed should be: +<screen> +All of PostgreSQL successfully made. Ready to install. +</screen> + </para> + + <para> + If you want to build everything that can be built, including the + documentation (HTML and man pages), and the additional modules + (<filename>contrib</filename>), type instead: +<screen> +<userinput>make world</userinput> +</screen> + The last line displayed should be: +<screen> +PostgreSQL, contrib, and documentation successfully made. Ready to install. +</screen> + </para> + + <para> + If you want to invoke the build from another makefile rather than + manually, you must unset <varname>MAKELEVEL</varname> or set it to zero, + for instance like this: +<programlisting> +build-postgresql: + $(MAKE) -C postgresql MAKELEVEL=0 all +</programlisting> + Failure to do that can lead to strange error messages, typically about + missing header files. + </para> + </step> + + <step> + <title>Regression Tests</title> + + <indexterm> + <primary>regression test</primary> + </indexterm> + + <para> + If you want to test the newly built server before you install it, + you can run the regression tests at this point. The regression + tests are a test suite to verify that <productname>PostgreSQL</productname> + runs on your machine in the way the developers expected it + to. Type: +<screen> +<userinput>make check</userinput> +</screen> + (This won't work as root; do it as an unprivileged user.) + See <xref linkend="regress"/> for + detailed information about interpreting the test results. You can + repeat this test at any later time by issuing the same command. + </para> + </step> + + <step id="install"> + <title>Installing the Files</title> + + <note> + <para> + If you are upgrading an existing system be sure to read + <xref linkend="upgrading"/>, + which has instructions about upgrading a + cluster. + </para> + </note> + + <para> + To install <productname>PostgreSQL</productname> enter: +<screen> +<userinput>make install</userinput> +</screen> + This will install files into the directories that were specified + in <xref linkend="configure"/>. Make sure that you have appropriate + permissions to write into that area. Normally you need to do this + step as root. Alternatively, you can create the target + directories in advance and arrange for appropriate permissions to + be granted. + </para> + + <para> + To install the documentation (HTML and man pages), enter: +<screen> +<userinput>make install-docs</userinput> +</screen> + </para> + + <para> + If you built the world above, type instead: +<screen> +<userinput>make install-world</userinput> +</screen> + This also installs the documentation. + </para> + + <para> + You can use <literal>make install-strip</literal> instead of + <literal>make install</literal> to strip the executable files and + libraries as they are installed. This will save some space. If + you built with debugging support, stripping will effectively + remove the debugging support, so it should only be done if + debugging is no longer needed. <literal>install-strip</literal> + tries to do a reasonable job saving space, but it does not have + perfect knowledge of how to strip every unneeded byte from an + executable file, so if you want to save all the disk space you + possibly can, you will have to do manual work. + </para> + + <para> + The standard installation provides all the header files needed for client + application development as well as for server-side program + development, such as custom functions or data types written in C. + (Prior to <productname>PostgreSQL</productname> 8.0, a separate <literal>make + install-all-headers</literal> command was needed for the latter, but this + step has been folded into the standard install.) + </para> + + <formalpara> + <title>Client-only installation:</title> + <para> + If you want to install only the client applications and + interface libraries, then you can use these commands: +<screen> +<userinput>make -C src/bin install</userinput> +<userinput>make -C src/include install</userinput> +<userinput>make -C src/interfaces install</userinput> +<userinput>make -C doc install</userinput> +</screen> + <filename>src/bin</filename> has a few binaries for server-only use, + but they are small. + </para> + </formalpara> + </step> + </procedure> + + <formalpara> + <title>Uninstallation:</title> + <para> + To undo the installation use the command <command>make + uninstall</command>. However, this will not remove any created directories. + </para> + </formalpara> + + <formalpara> + <title>Cleaning:</title> + + <para> + After the installation you can free disk space by removing the built + files from the source tree with the command <command>make + clean</command>. This will preserve the files made by the <command>configure</command> + program, so that you can rebuild everything with <command>make</command> + later on. To reset the source tree to the state in which it was + distributed, use <command>make distclean</command>. If you are going to + build for several platforms within the same source tree you must do + this and re-configure for each platform. (Alternatively, use + a separate build tree for each platform, so that the source tree + remains unmodified.) + </para> + </formalpara> + + <para> + If you perform a build and then discover that your <command>configure</command> + options were wrong, or if you change anything that <command>configure</command> + investigates (for example, software upgrades), then it's a good + idea to do <command>make distclean</command> before reconfiguring and + rebuilding. Without this, your changes in configuration choices + might not propagate everywhere they need to. + </para> + + <sect2 id="configure-options"> + <title><filename>configure</filename> Options</title> + + <indexterm zone="configure-options"> + <primary>configure options</primary> + </indexterm> + + <para> + <command>configure</command>'s command line options are explained below. + This list is not exhaustive (use <literal>./configure --help</literal> + to get one that is). The options not covered here are meant for + advanced use-cases such as cross-compilation, and are documented in + the standard Autoconf documentation. + </para> + + <sect3 id="configure-options-locations"> + <title>Installation Locations</title> + + <para> + The <option>--prefix</option> option is sufficient for most cases. + If you have special needs, you can customize the individual + subdirectories with the other options described in this section. + Beware however that changing the relative locations of the different + subdirectories may render the installation non-relocatable, meaning + you won't be able to move it after installation. + (The <literal>man</literal> and <literal>doc</literal> + locations are not affected by this restriction.) + For relocatable installs, you might want to use + the <literal>--disable-rpath</literal> option described later. + </para> <variablelist> <varlistentry> @@ -424,22 +653,6 @@ su - postgres will ever be installed directly into the <replaceable>PREFIX</replaceable> directory. </para> - - <para> - If you have special needs, you can also customize the - individual subdirectories with the following options. However, - if you leave these with their defaults, the installation will be - relocatable, meaning you can move the directory after - installation. (The <literal>man</literal> and <literal>doc</literal> - locations are not affected by this.) - </para> - - <para> - For relocatable installs, you might want to use - <filename>configure</filename>'s <literal>--disable-rpath</literal> - option. Also, you will need to tell the operating system how - to find the shared libraries. - </para> </listitem> </varlistentry> @@ -599,56 +812,21 @@ su - postgres for dynamically loadable modules. </para> </note> - </para> - <para> - <variablelist> - <varlistentry> - <term><option>--with-extra-version=<replaceable>STRING</replaceable></option></term> - <listitem> - <para> - Append <replaceable>STRING</replaceable> to the PostgreSQL version number. You - can use this, for example, to mark binaries built from unreleased Git - snapshots or containing custom patches with an extra version string - such as a <command>git describe</command> identifier or a - distribution package release number. - </para> - </listitem> - </varlistentry> + </sect3> - <varlistentry> - <term><option>--with-includes=<replaceable>DIRECTORIES</replaceable></option></term> - <listitem> - <para> - <replaceable>DIRECTORIES</replaceable> is a colon-separated list of - directories that will be added to the list the compiler - searches for header files. If you have optional packages - (such as GNU <application>Readline</application>) installed in a non-standard - location, - you have to use this option and probably also the corresponding - <option>--with-libraries</option> option. - </para> - <para> - Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</literal>. - </para> - </listitem> - </varlistentry> + <sect3 id="configure-options-features"> + <title><productname>PostgreSQL</productname> Features</title> - <varlistentry> - <term><option>--with-libraries=<replaceable>DIRECTORIES</replaceable></option></term> - <listitem> - <para> - <replaceable>DIRECTORIES</replaceable> is a colon-separated list of - directories to search for libraries. You will probably have - to use this option (and the corresponding - <option>--with-includes</option> option) if you have packages - installed in non-standard locations. - </para> - <para> - Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</literal>. - </para> - </listitem> - </varlistentry> + <para> + The options described in this section enable building of + various <productname>PostgreSQL</productname> features that are not + built by default. Most of them are non-default because they require + additional software, as described in + <xref linkend="install-requirements"/>. + </para> + + <variablelist> <varlistentry> <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term> @@ -668,22 +846,7 @@ su - postgres <para> To use this option, you will need an implementation of the - <application>Gettext</application> API; see above. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--with-pgport=<replaceable>NUMBER</replaceable></option></term> - <listitem> - <para> - Set <replaceable>NUMBER</replaceable> as the default port number for - server and clients. The default is 5432. The port can always - be changed later on, but if you specify it here then both - server and clients will have the same default compiled in, - which can be very convenient. Usually the only good reason - to select a non-default value is if you intend to run multiple - <productname>PostgreSQL</productname> servers on the same machine. + <application>Gettext</application> API. </para> </listitem> </varlistentry> @@ -730,32 +893,32 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--with-gssapi</option></term> + <term><option>--with-icu</option></term> <listitem> <para> - Build with support for GSSAPI authentication. On many - systems, the GSSAPI (usually a part of the Kerberos installation) - system is not installed in a location - that is searched by default (e.g., <filename>/usr/include</filename>, - <filename>/usr/lib</filename>), so you must use the options - <option>--with-includes</option> and <option>--with-libraries</option> in - addition to this option. <filename>configure</filename> will check - for the required header files and libraries to make sure that - your GSSAPI installation is sufficient before proceeding. + Build with support for + the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm> + library. This requires the <productname>ICU4C</productname> package + to be installed. The minimum required version + of <productname>ICU4C</productname> is currently 4.2. </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--with-krb-srvnam=<replaceable>NAME</replaceable></option></term> - <listitem> <para> - The default name of the Kerberos service principal used - by GSSAPI. - <literal>postgres</literal> is the default. There's usually no - reason to change this unless you have a Windows environment, - in which case it must be set to upper case - <literal>POSTGRES</literal>. + By default, + <productname>pkg-config</productname><indexterm><primary>pkg-config</primary></indexterm> + will be used to find the required compilation options. This is + supported for <productname>ICU4C</productname> version 4.6 and later. + For older versions, or if <productname>pkg-config</productname> is + not available, the variables <envar>ICU_CFLAGS</envar> + and <envar>ICU_LIBS</envar> can be specified + to <filename>configure</filename>, like in this example: +<programlisting> +./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata' +</programlisting> + (If <productname>ICU4C</productname> is in the default search path + for the compiler, then you still need to specify a nonempty string in + order to avoid use of <productname>pkg-config</productname>, for + example, <literal>ICU_CFLAGS=' '</literal>.) </para> </listitem> </varlistentry> @@ -796,37 +959,6 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--with-icu</option></term> - <listitem> - <para> - Build with support for - the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm> - library. This requires the <productname>ICU4C</productname> package - to be installed. The minimum required version - of <productname>ICU4C</productname> is currently 4.2. - </para> - - <para> - By default, - <productname>pkg-config</productname><indexterm><primary>pkg-config</primary></indexterm> - will be used to find the required compilation options. This is - supported for <productname>ICU4C</productname> version 4.6 and later. - For older versions, or if <productname>pkg-config</productname> is - not available, the variables <envar>ICU_CFLAGS</envar> - and <envar>ICU_LIBS</envar> can be specified - to <filename>configure</filename>, like in this example: -<programlisting> -./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata' -</programlisting> - (If <productname>ICU4C</productname> is in the default search path - for the compiler, then you still need to specify a nonempty string in - order to avoid use of <productname>pkg-config</productname>, for - example, <literal>ICU_CFLAGS=' '</literal>.) - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><option>--with-openssl</option> <indexterm> <primary>OpenSSL</primary> @@ -846,22 +978,18 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--with-pam</option></term> - <listitem> - <para> - Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm> - (Pluggable Authentication Modules) support. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--with-bsd-auth</option></term> + <term><option>--with-gssapi</option></term> <listitem> <para> - Build with BSD Authentication support. - (The BSD Authentication framework is - currently only available on OpenBSD.) + Build with support for GSSAPI authentication. On many systems, the + GSSAPI system (usually a part of the Kerberos installation) is not + installed in a location + that is searched by default (e.g., <filename>/usr/include</filename>, + <filename>/usr/lib</filename>), so you must use the options + <option>--with-includes</option> and <option>--with-libraries</option> in + addition to this option. <filename>configure</filename> will check + for the required header files and libraries to make sure that + your GSSAPI installation is sufficient before proceeding. </para> </listitem> </varlistentry> @@ -885,41 +1013,38 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--with-systemd</option></term> + <term><option>--with-pam</option></term> <listitem> <para> - Build with support - for <application>systemd</application><indexterm><primary>systemd</primary></indexterm> - service notifications. This improves integration if the server binary - is started under <application>systemd</application> but has no impact - otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more - information</phrase>. <application>libsystemd</application> and the - associated header files need to be installed to be able to use this - option. + Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm> + (Pluggable Authentication Modules) support. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--without-readline</option></term> + <term><option>--with-bsd-auth</option></term> <listitem> <para> - Prevents use of the <application>Readline</application> library - (and <application>libedit</application> as well). This option disables - command-line editing and history in - <application>psql</application>, so it is not recommended. + Build with BSD Authentication support. + (The BSD Authentication framework is + currently only available on OpenBSD.) </para> </listitem> </varlistentry> <varlistentry> - <term><option>--with-libedit-preferred</option></term> + <term><option>--with-systemd</option></term> <listitem> <para> - Favors the use of the BSD-licensed <application>libedit</application> library - rather than GPL-licensed <application>Readline</application>. This option - is significant only if you have both libraries installed; the - default in that case is to use <application>Readline</application>. + Build with support + for <application>systemd</application><indexterm><primary>systemd</primary></indexterm> + service notifications. This improves integration if the server binary + is started under <application>systemd</application> but has no impact + otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more + information</phrase>. <application>libsystemd</application> and the + associated header files need to be installed to be able to use this + option. </para> </listitem> </varlistentry> @@ -1012,6 +1137,64 @@ su - postgres </listitem> </varlistentry> + </variablelist> + + </sect3> + + <sect3 id="configure-options-anti-features"> + <title><productname>PostgreSQL</productname> Anti-Features</title> + + <para> + The options described in this section allow disabling + certain <productname>PostgreSQL</productname> features that are built + by default, but which might need to be turned off if the required + software or system features are not available. Using these options is + not recommended unless really necessary. + </para> + + <variablelist> + + <varlistentry> + <term><option>--without-readline</option></term> + <listitem> + <para> + Prevents use of the <application>Readline</application> library + (and <application>libedit</application> as well). This option disables + command-line editing and history in + <application>psql</application>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--with-libedit-preferred</option></term> + <listitem> + <para> + Favors the use of the + BSD-licensed <application>libedit</application> library rather + than GPL-licensed <application>Readline</application>. This + option is significant only if you have both libraries installed; + the default in that case is to + use <application>Readline</application>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--without-zlib</option></term> + <listitem> + <para> + <indexterm> + <primary>zlib</primary> + </indexterm> + Prevents use of the <application>Zlib</application> library. + This disables + support for compressed archives in <application>pg_dump</application> + and <application>pg_restore</application>. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><option>--disable-float4-byval</option></term> <listitem> @@ -1047,80 +1230,85 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term> + <term><option>--disable-spinlocks</option></term> <listitem> <para> - Set the <firstterm>segment size</firstterm>, in gigabytes. Large tables are - divided into multiple operating-system files, each of size equal - to the segment size. This avoids problems with file size limits - that exist on many platforms. The default segment size, 1 gigabyte, - is safe on all supported platforms. If your operating system has - <quote>largefile</quote> support (which most do, nowadays), you can use - a larger segment size. This can be helpful to reduce the number of - file descriptors consumed when working with very large tables. - But be careful not to select a value larger than is supported - by your platform and the file systems you intend to use. Other - tools you might wish to use, such as <application>tar</application>, could - also set limits on the usable file size. - It is recommended, though not absolutely required, that this value - be a power of 2. - Note that changing this value requires an initdb. + Allow the build to succeed even if <productname>PostgreSQL</productname> + has no CPU spinlock support for the platform. The lack of + spinlock support will result in poor performance; therefore, + this option should only be used if the build aborts and + informs you that the platform lacks spinlock support. If this + option is required to build <productname>PostgreSQL</productname> on + your platform, please report the problem to the + <productname>PostgreSQL</productname> developers. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term> + <term><option>--disable-atomics</option></term> <listitem> <para> - Set the <firstterm>block size</firstterm>, in kilobytes. This is the unit - of storage and I/O within tables. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 32 (kilobytes). - Note that changing this value requires an initdb. + Disable use of CPU atomic operations. This option does nothing on + platforms that lack such operations. On platforms that do have + them, this will result in poor performance. This option is only + useful for debugging or making performance comparisons. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term> + <term><option>--disable-thread-safety</option></term> <listitem> <para> - Set the <firstterm>WAL block size</firstterm>, in kilobytes. This is the unit - of storage and I/O within the WAL log. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 64 (kilobytes). - Note that changing this value requires an initdb. + Disable the thread-safety of client libraries. This prevents + concurrent threads in <application>libpq</application> and + <application>ECPG</application> programs from safely controlling + their private connection handles. Use this only on platforms + with deficient thread support. </para> </listitem> </varlistentry> + </variablelist> + + </sect3> + + <sect3 id="configure-options-build-process"> + <title>Build Process Details</title> + + <variablelist> + <varlistentry> - <term><option>--disable-spinlocks</option></term> + <term><option>--with-includes=<replaceable>DIRECTORIES</replaceable></option></term> <listitem> <para> - Allow the build to succeed even if <productname>PostgreSQL</productname> - has no CPU spinlock support for the platform. The lack of - spinlock support will result in poor performance; therefore, - this option should only be used if the build aborts and - informs you that the platform lacks spinlock support. If this - option is required to build <productname>PostgreSQL</productname> on - your platform, please report the problem to the - <productname>PostgreSQL</productname> developers. + <replaceable>DIRECTORIES</replaceable> is a colon-separated list of + directories that will be added to the list the compiler + searches for header files. If you have optional packages + (such as GNU <application>Readline</application>) installed in a non-standard + location, + you have to use this option and probably also the corresponding + <option>--with-libraries</option> option. + </para> + <para> + Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--disable-thread-safety</option></term> + <term><option>--with-libraries=<replaceable>DIRECTORIES</replaceable></option></term> <listitem> <para> - Disable the thread-safety of client libraries. This prevents - concurrent threads in <application>libpq</application> and - <application>ECPG</application> programs from safely controlling - their private connection handles. + <replaceable>DIRECTORIES</replaceable> is a colon-separated list of + directories to search for libraries. You will probably have + to use this option (and the corresponding + <option>--with-includes</option> option) if you have packages + installed in non-standard locations. + </para> + <para> + Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</literal>. </para> </listitem> </varlistentry> @@ -1166,62 +1354,171 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--without-zlib</option></term> + <term><option>--with-extra-version=<replaceable>STRING</replaceable></option></term> <listitem> <para> - <indexterm> - <primary>zlib</primary> - </indexterm> - Prevents use of the <application>Zlib</application> library. This disables - support for compressed archives in <application>pg_dump</application> - and <application>pg_restore</application>. - This option is only intended for those rare systems where this - library is not available. + Append <replaceable>STRING</replaceable> to the PostgreSQL version number. You + can use this, for example, to mark binaries built from unreleased Git + snapshots or containing custom patches with an extra version string + such as a <command>git describe</command> identifier or a + distribution package release number. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--enable-debug</option></term> + <term><option>--disable-rpath</option></term> <listitem> <para> - Compiles all programs and libraries with debugging symbols. - This means that you can run the programs in a debugger - to analyze problems. This enlarges the size of the installed - executables considerably, and on non-GCC compilers it usually - also disables compiler optimization, causing slowdowns. However, - having the symbols available is extremely helpful for dealing - with any problems that might arise. Currently, this option is - recommended for production installations only if you use GCC. - But you should always have it on if you are doing development work - or running a beta version. + Do not mark <productname>PostgreSQL</productname>'s executables + to indicate that they should search for shared libraries in the + installation's library directory (see <option>--libdir</option>). + On most platforms, this marking uses an absolute path to the + library directory, so that it will be unhelpful if you relocate + the installation later. However, you will then need to provide + some other way for the executables to find the shared libraries. + Typically this requires configuring the operating system's + dynamic linker to search the library directory. </para> </listitem> </varlistentry> + </variablelist> + + </sect3> + + <sect3 id="configure-options-misc"> + <title>Miscellaneous</title> + + <para> + It's fairly common, particularly for test builds, to adjust the + default port number with <option>--with-pgport</option>. + The other options in this section are recommended only for advanced + users. + </para> + + <variablelist> + <varlistentry> - <term><option>--enable-coverage</option></term> + <term><option>--with-pgport=<replaceable>NUMBER</replaceable></option></term> <listitem> <para> - If using GCC, all programs and libraries are compiled with - code coverage testing instrumentation. When run, they - generate files in the build directory with code coverage - metrics. - <phrase condition="standalone-ignore">See <xref linkend="regress-coverage"/> - for more information.</phrase> This option is for use only with GCC - and when doing development work. + Set <replaceable>NUMBER</replaceable> as the default port number for + server and clients. The default is 5432. The port can always + be changed later on, but if you specify it here then both + server and clients will have the same default compiled in, + which can be very convenient. Usually the only good reason + to select a non-default value is if you intend to run multiple + <productname>PostgreSQL</productname> servers on the same machine. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--enable-profiling</option></term> + <term><option>--with-krb-srvnam=<replaceable>NAME</replaceable></option></term> <listitem> <para> - If using GCC, all programs and libraries are compiled so they - can be profiled. On backend exit, a subdirectory will be created - that contains the <filename>gmon.out</filename> file for use in profiling. - This option is for use only with GCC and when doing development work. + The default name of the Kerberos service principal used + by GSSAPI. + <literal>postgres</literal> is the default. There's usually no + reason to change this unless you have a Windows environment, + in which case it must be set to upper case + <literal>POSTGRES</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term> + <listitem> + <para> + Set the <firstterm>segment size</firstterm>, in gigabytes. Large tables are + divided into multiple operating-system files, each of size equal + to the segment size. This avoids problems with file size limits + that exist on many platforms. The default segment size, 1 gigabyte, + is safe on all supported platforms. If your operating system has + <quote>largefile</quote> support (which most do, nowadays), you can use + a larger segment size. This can be helpful to reduce the number of + file descriptors consumed when working with very large tables. + But be careful not to select a value larger than is supported + by your platform and the file systems you intend to use. Other + tools you might wish to use, such as <application>tar</application>, could + also set limits on the usable file size. + It is recommended, though not absolutely required, that this value + be a power of 2. + Note that changing this value requires an initdb. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term> + <listitem> + <para> + Set the <firstterm>block size</firstterm>, in kilobytes. This is the unit + of storage and I/O within tables. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 32 (kilobytes). + Note that changing this value requires an initdb. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term> + <listitem> + <para> + Set the <firstterm>WAL block size</firstterm>, in kilobytes. This is the unit + of storage and I/O within the WAL log. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 64 (kilobytes). + Note that changing this value requires an initdb. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect3> + + <sect3 id="configure-options-devel"> + <title>Developer Options</title> + + <para> + Most of the options in this section are only of interest for + developing or debugging <productname>PostgreSQL</productname>. + They are not recommended for production builds, except + for <option>--enable-debug</option>, which can be useful to enable + more detailed bug reports in the unlucky event that you encounter a + bug. On platforms supporting DTrace, <option>--enable-dtrace</option> + may also be reasonable to use in production. + </para> + + <para> + When building an installation that will be used to develop code inside + the server, it is recommended to use at least the + options <option>--enable-debug</option> + and <option>--enable-cassert</option>. + </para> + + <variablelist> + + <varlistentry> + <term><option>--enable-debug</option></term> + <listitem> + <para> + Compiles all programs and libraries with debugging symbols. + This means that you can run the programs in a debugger + to analyze problems. This enlarges the size of the installed + executables considerably, and on non-GCC compilers it usually + also disables compiler optimization, causing slowdowns. However, + having the symbols available is extremely helpful for dealing + with any problems that might arise. Currently, this option is + recommended for production installations only if you use GCC. + But you should always have it on if you are doing development work + or running a beta version. </para> </listitem> </varlistentry> @@ -1246,6 +1543,17 @@ su - postgres </varlistentry> <varlistentry> + <term><option>--enable-tap-tests</option></term> + <listitem> + <para> + Enable tests using the Perl TAP tools. This requires a Perl + installation and the Perl module <literal>IPC::Run</literal>. + <phrase condition="standalone-ignore">See <xref linkend="regress-tap"/> for more information.</phrase> + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--enable-depend</option></term> <listitem> <para> @@ -1260,6 +1568,34 @@ su - postgres </varlistentry> <varlistentry> + <term><option>--enable-coverage</option></term> + <listitem> + <para> + If using GCC, all programs and libraries are compiled with + code coverage testing instrumentation. When run, they + generate files in the build directory with code coverage + metrics. + <phrase condition="standalone-ignore">See <xref linkend="regress-coverage"/> + for more information.</phrase> This option is for use only with GCC + and when doing development work. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--enable-profiling</option></term> + <listitem> + <para> + If using GCC, all programs and libraries are compiled so they + can be profiled. On backend exit, a subdirectory will be created + that contains the <filename>gmon.out</filename> file containing + profile data. + This option is for use only with GCC and when doing development work. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--enable-dtrace</option></term> <listitem> <para> @@ -1297,24 +1633,46 @@ su - postgres </para> </listitem> </varlistentry> - - <varlistentry> - <term><option>--enable-tap-tests</option></term> - <listitem> - <para> - Enable tests using the Perl TAP tools. This requires a Perl - installation and the Perl module <literal>IPC::Run</literal>. - <phrase condition="standalone-ignore">See <xref linkend="regress-tap"/> for more information.</phrase> - </para> - </listitem> - </varlistentry> </variablelist> + + </sect3> + + </sect2> + + <sect2 id="configure-envvars"> + <title><filename>configure</filename> Environment Variables</title> + + <indexterm zone="configure-envvars"> + <primary>configure environment variables</primary> + </indexterm> + + <para> + In addition to the ordinary command-line options described above, + <filename>configure</filename> responds to a number of environment + variables. + You can specify environment variables on the + <filename>configure</filename> command line, for example: +<screen> +<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</userinput> +</screen> + In this usage an environment variable is little different from a + command-line option. + You can also set such variables beforehand: +<screen> +<userinput>export CC=/opt/bin/gcc</userinput> +<userinput>export CFLAGS='-O2 -pipe'</userinput> +<userinput>./configure</userinput> +</screen> + This usage can be convenient because many programs' configuration + scripts respond to these variables in similar ways. </para> <para> + The most commonly used of these environment variables are + <envar>CC</envar> and <envar>CFLAGS</envar>. If you prefer a C compiler different from the one <filename>configure</filename> picks, you can set the - environment variable <envar>CC</envar> to the program of your choice. + variable <envar>CC</envar> to the program of your choice. By default, <filename>configure</filename> will pick <filename>gcc</filename> if available, else the platform's default (usually <filename>cc</filename>). Similarly, you can override the @@ -1322,14 +1680,6 @@ su - postgres </para> <para> - You can specify environment variables on the - <filename>configure</filename> command line, for example: -<screen> -<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</userinput> -</screen> - </para> - - <para> Here is a list of the significant variables that can be set in this manner: @@ -1552,13 +1902,6 @@ su - postgres <note> <para> - When developing code inside the server, it is recommended to - use the configure options <option>--enable-cassert</option> (which - turns on many run-time error checks) and <option>--enable-debug</option> - (which improves the usefulness of debugging tools). - </para> - - <para> If using GCC, it is best to build with an optimization level of at least <option>-O1</option>, because using no optimization (<option>-O0</option>) disables some important compiler warnings (such @@ -1579,187 +1922,8 @@ su - postgres adjustments, while <envar>COPT</envar> might be kept set all the time. </para> </note> - </step> - - <step id="build"> - <title>Build</title> - - <para> - To start the build, type either of: -<screen> -<userinput>make</userinput> -<userinput>make all</userinput> -</screen> - (Remember to use <acronym>GNU</acronym> <application>make</application>.) - The build will take a few minutes depending on your - hardware. The last line displayed should be: -<screen> -All of PostgreSQL successfully made. Ready to install. -</screen> - </para> - - <para> - If you want to build everything that can be built, including the - documentation (HTML and man pages), and the additional modules - (<filename>contrib</filename>), type instead: -<screen> -<userinput>make world</userinput> -</screen> - The last line displayed should be: -<screen> -PostgreSQL, contrib, and documentation successfully made. Ready to install. -</screen> - </para> - - <para> - If you want to invoke the build from another makefile rather than - manually, you must unset <varname>MAKELEVEL</varname> or set it to zero, - for instance like this: -<programlisting> -build-postgresql: - $(MAKE) -C postgresql MAKELEVEL=0 all -</programlisting> - Failure to do that can lead to strange error messages, typically about - missing header files. - </para> - </step> - - <step> - <title>Regression Tests</title> - - <indexterm> - <primary>regression test</primary> - </indexterm> - - <para> - If you want to test the newly built server before you install it, - you can run the regression tests at this point. The regression - tests are a test suite to verify that <productname>PostgreSQL</productname> - runs on your machine in the way the developers expected it - to. Type: -<screen> -<userinput>make check</userinput> -</screen> - (This won't work as root; do it as an unprivileged user.) - See <xref linkend="regress"/> for - detailed information about interpreting the test results. You can - repeat this test at any later time by issuing the same command. - </para> - </step> - - <step id="install"> - <title>Installing the Files</title> - - <note> - <para> - If you are upgrading an existing system be sure to read - <xref linkend="upgrading"/>, - which has instructions about upgrading a - cluster. - </para> - </note> - - <para> - To install <productname>PostgreSQL</productname> enter: -<screen> -<userinput>make install</userinput> -</screen> - This will install files into the directories that were specified - in <xref linkend="configure"/>. Make sure that you have appropriate - permissions to write into that area. Normally you need to do this - step as root. Alternatively, you can create the target - directories in advance and arrange for appropriate permissions to - be granted. - </para> - - <para> - To install the documentation (HTML and man pages), enter: -<screen> -<userinput>make install-docs</userinput> -</screen> - </para> - - <para> - If you built the world above, type instead: -<screen> -<userinput>make install-world</userinput> -</screen> - This also installs the documentation. - </para> - - <para> - You can use <literal>make install-strip</literal> instead of - <literal>make install</literal> to strip the executable files and - libraries as they are installed. This will save some space. If - you built with debugging support, stripping will effectively - remove the debugging support, so it should only be done if - debugging is no longer needed. <literal>install-strip</literal> - tries to do a reasonable job saving space, but it does not have - perfect knowledge of how to strip every unneeded byte from an - executable file, so if you want to save all the disk space you - possibly can, you will have to do manual work. - </para> - - <para> - The standard installation provides all the header files needed for client - application development as well as for server-side program - development, such as custom functions or data types written in C. - (Prior to <productname>PostgreSQL</productname> 8.0, a separate <literal>make - install-all-headers</literal> command was needed for the latter, but this - step has been folded into the standard install.) - </para> - - <formalpara> - <title>Client-only installation:</title> - <para> - If you want to install only the client applications and - interface libraries, then you can use these commands: -<screen> -<userinput>make -C src/bin install</userinput> -<userinput>make -C src/include install</userinput> -<userinput>make -C src/interfaces install</userinput> -<userinput>make -C doc install</userinput> -</screen> - <filename>src/bin</filename> has a few binaries for server-only use, - but they are small. - </para> - </formalpara> - </step> - </procedure> - - <formalpara> - <title>Uninstallation:</title> - <para> - To undo the installation use the command <command>make - uninstall</command>. However, this will not remove any created directories. - </para> - </formalpara> - - <formalpara> - <title>Cleaning:</title> - - <para> - After the installation you can free disk space by removing the built - files from the source tree with the command <command>make - clean</command>. This will preserve the files made by the <command>configure</command> - program, so that you can rebuild everything with <command>make</command> - later on. To reset the source tree to the state in which it was - distributed, use <command>make distclean</command>. If you are going to - build for several platforms within the same source tree you must do - this and re-configure for each platform. (Alternatively, use - a separate build tree for each platform, so that the source tree - remains unmodified.) - </para> - </formalpara> + </sect2> - <para> - If you perform a build and then discover that your <command>configure</command> - options were wrong, or if you change anything that <command>configure</command> - investigates (for example, software upgrades), then it's a good - idea to do <command>make distclean</command> before reconfiguring and - rebuilding. Without this, your changes in configuration choices - might not propagate everywhere they need to. - </para> </sect1> <sect1 id="install-post">
pgsql-docs by date: