From 3d84a0d177f33c66d409a09faf6c0e4c55e6a98a Mon Sep 17 00:00:00 2001 From: Andres Freund Date: Sat, 27 Aug 2022 09:55:20 -0700 Subject: [PATCH v17 07/23] meson: Add docs for building with meson Author: Samay Sharma --- doc/src/sgml/installation.sgml | 1841 ++++++++++++++++++++++++++++++-- doc/src/sgml/monitoring.sgml | 2 +- doc/src/sgml/runtime.sgml | 2 +- doc/src/sgml/sourcerepo.sgml | 5 +- 4 files changed, 1743 insertions(+), 107 deletions(-) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 319c7e69660..3d4018badd3 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -31,7 +31,144 @@ documentation. See standalone-profile.xsl for details. C++, see instead. - + + Supported Platforms + + + A platform (that is, a CPU architecture and operating system combination) + is considered supported by the PostgreSQL development + community if the code contains provisions to work on that platform and + it has recently been verified to build and pass its regression tests + on that platform. Currently, most testing of platform compatibility + is done automatically by test machines in the + PostgreSQL Build Farm. + If you are interested in using PostgreSQL on a platform + that is not represented in the build farm, but on which the code works + or can be made to work, you are strongly encouraged to set up a build + farm member machine so that continued compatibility can be assured. + + + + In general, PostgreSQL can be expected to work on + these CPU architectures: x86, PowerPC, S/390, SPARC, ARM, MIPS, RISC-V, + and PA-RISC, including + big-endian, little-endian, 32-bit, and 64-bit variants where applicable. + It is often + possible to build on an unsupported CPU type by configuring with + , but performance will be poor. + + + + PostgreSQL can be expected to work on current + versions of these operating systems: Linux, Windows, + FreeBSD, OpenBSD, NetBSD, DragonFlyBSD, macOS, AIX, Solaris, and illumos. + Other Unix-like systems may also work but are not currently + being tested. In most cases, all CPU architectures supported by + a given operating system will work. Look in + below to see if + there is information + specific to your operating system, particularly if using an older system. + + + + If you have installation problems on a platform that is known + to be supported according to recent build farm results, please report + it to pgsql-bugs@lists.postgresql.org. If you are interested + in porting PostgreSQL to a new platform, + pgsql-hackers@lists.postgresql.org is the appropriate place + to discuss that. + + + + Historical versions of PostgreSQL or POSTGRES + also ran on CPU architectures including Alpha, Itanium, M32R, M68K, + M88K, NS32K, SuperH, and VAX, and operating systems including 4.3BSD, BEOS, + BSD/OS, DG/UX, Dynix, HP-UX, IRIX, NeXTSTEP, QNX, SCO, SINIX, Sprite, SunOS, + Tru64 UNIX, and ULTRIX. + + + + + Getting the Source + + + You can download the source code in two ways - via git or the source code + tarballs. + + + + Getting the Source via <productname>Git</productname> + + With Git, you can make a copy of the entire code repository + on your local machine, so you will have access to all history and branches + offline. This is the fastest and most flexible way to develop or test + patches. + + + + + + To begin using the Git repository, make a clone of the official mirror: + + +git clone https://git.postgresql.org/git/postgresql.git + + + This will copy the full repository to your local machine, so it may take + a while to complete, especially if you have a slow Internet connection. + The files will be placed in a new subdirectory postgresql of + your current directory. + + + + + + + Whenever you want to get the latest updates in the system, cd + into the repository, and run: + + +git pull + + + + + + + Git can do a lot more things than just fetch the source. + Our wiki, , + has some discussion on working with Git. For more information, consult the + Git man pages, or see the website at + . + + + + Getting the Source via Tarballs + + + The PostgreSQL source code for released versions + can also be obtained from the download section of our website: + . + Download the + postgresql-version.tar.gz + or postgresql-version.tar.bz2 + file you're interested in, then unpack it: + +tar xf postgresql-version.tar.bz2 + + This will create a directory + postgresql-version under + the current directory with the PostgreSQL sources. + Change into that directory for the rest of the installation procedure. + + + + + + Building and Installation with autoconf and make + + Short Version @@ -50,12 +187,12 @@ su - postgres /usr/local/pgsql/bin/psql test The long version is the rest of this - chapter. + section. - + - + Requirements @@ -343,45 +480,9 @@ su - postgres url="ftp://ftp.gnu.org/gnu/">. - - Also check that you have sufficient disk space. You will need about - 350 MB for the source tree during compilation and about 60 MB for - the installation directory. An empty database cluster takes about - 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 - 300 MB. Use the df command to check free disk - space. - - + - - Getting the Source - - - The PostgreSQL source code for released versions - can be obtained from the download section of our website: - . - Download the - postgresql-version.tar.gz - or postgresql-version.tar.bz2 - file you're interested in, then unpack it: - -tar xf postgresql-version.tar.bz2 - - This will create a directory - postgresql-version under - the current directory with the PostgreSQL sources. - Change into that directory for the rest of the installation procedure. - - - - Alternatively, you can use the Git version control system; see - for more information. - - - - + Installation Procedure @@ -630,6 +731,7 @@ build-postgresql: rebuilding. Without this, your changes in configuration choices might not propagate everywhere they need to. + <filename>configure</filename> Options @@ -844,7 +946,7 @@ build-postgresql: various PostgreSQL features that are not built by default. Most of these are non-default only because they require additional software, as described in - . + . @@ -1672,9 +1774,7 @@ build-postgresql: - - - + <filename>configure</filename> Environment Variables @@ -1955,9 +2055,1600 @@ build-postgresql: adjustments, while COPT might be kept set all the time. + + + Building and Installation with meson + + + Short Version + + + + +# create working directory +mkdir postgres +cd postgres + +# fetch source code +# git clone https://git.postgresql.org/git/postgresql.git src + +# current instructions for testing (to be removed when merging) +git clone -b meson https://github.com/anarazel/postgres.git src + +# setup and enter build directory (done only first time) +meson setup build src --prefix=$PWD/install +cd build + +# Compile source +ninja + +# Install to the prefix directory specified above +ninja install + +# Run all tests (optional, takes time) +meson test + +# Initialize a new database +../install/bin/initdb -D ../data + +# Start database +../install/bin/pg_ctl -D ../data/ -l logfile start + +# Connect to the database +../install/bin/psql -d postgres + + + The long version is the rest of this + section. + + + + + Requirements + + + In general, a modern Unix-compatible platform or Windows should be able + to build PostgreSQL with meson and run it. + The platforms which have received specific testing at the time of release are: + + + Linux + Windows + OpenBSD + NetBSD + FreeBSD + macOS + + + + + Required packages + + + The following software packages are required for building + PostgreSQL: + + + + + You can download the source code in two ways - via git or by downloading + the source code tarballs. For the former, you will need an installed version of + Git, which you can get from + . Many systems already + have a recent version of Git + installed by default, or available in their package distribution system. + If you download the source code tarballs, you will need + tar in addition to + gzip or bzip2. + + + + + + meson + + You need to install + meson version + 0.54 or later to be able to build PostgreSQL + with it. If your operating system provides a package manager, you can install + meson with that. If not, you + can download a meson release + from github and run ./meson.py from the git repository + itself. Lastly, Meson is also available in the python package index and can + be installed with pip. + + + + + You need an ISO/ANSI C compiler (at least + C99-compliant). Recent + versions of GCC are recommended, but + PostgreSQL is known to build using a wide variety + of compilers from different vendors. + + + + + + flex + + + lex + + + bison + + + yacc + + + Flex and Bison + are needed to build PostgreSQL using + meson. Be sure to get + Flex 2.5.31 or later and + Bison 1.875 or later from your package manager. + Other lex and yacc + programs cannot be used. + + + + + + perl + + Perl 5.8.3 or later is needed to build PostgreSQL + using meson and to run some test suites. + + + + + + + + Recommended packages + + + The following packages are not required to build + PostgreSQL but are strongly recommended: + + + + + + readline + + + libedit + + + The GNU Readline library + allows psql (the PostgreSQL command line + SQL interpreter) to remember each command you type, and allows you to + use arrow keys to recall and edit previous commands. This is very + helpful and is strongly recommended. As an alternative, you can often + use the BSD-licensed libedit library, originally + developed on NetBSD. The + libedit library is GNU + Readline-compatible and is used if + libreadline is not found, or if + is enabled as an + option to meson configure. If you are using a + package-based Linux distribution, be aware that you need both the + readline and readline-devel packages, if + those are separate in your distribution. + + + + + + zlib + + + The zlib compression library is + used to provide support for compressed archives in + pg_dump and + pg_restore and is recommended. + + + + + Various tests, particularly the client program tests under + src/bin, use the Perl TAP tools. Running + these tests is recommended for development. These TAP tests + require the Perl module IPC::Run which is + available from CPAN or an operating system package. + + + + + + + + Optional packages + + + The following packages are optional. They are not required in the + default configuration, but they are needed when certain build + options are enabled, as explained below: + + + + + You need OpenSSL, if you want to support + encrypted client connections. OpenSSL is + also required for random number generation on platforms that do not + have /dev/urandom (except Windows). The minimum + required version is 1.0.1. + + + + + + You need LZ4, if you want to support + compression of data with that method; see + and + . + + + + + + You need Zstandard, if you want to support + compression of data or backups with that method; see + . + The minimum required version is 1.4.0. + + + + + + You need Kerberos, OpenLDAP, + and/or PAM, if you want to support authentication + using those services. + + + + + + To build the server programming language + PL/Perl you need a full + Perl installation, including the + libperl library and the header files. + The minimum required version is Perl 5.8.3. + Since PL/Perl will be a shared + library, the libperl + libperl library must be a shared library + also on most platforms. This appears to be the default in + recent Perl versions, but it was not + in earlier versions, and in any case it is the choice of whomever + installed Perl at your site. configure will fail + if building PL/Perl is selected but it cannot + find a shared libperl. In that case, you will have + to rebuild and install Perl manually to be + able to build PL/Perl. During the + configuration process for Perl, request a + shared library. + + + + If you intend to make more than incidental use of + PL/Perl, you should ensure that the + Perl installation was built with the + usemultiplicity option enabled (perl -V + will show whether this is the case). + + + + + + To build the PL/Python server programming + language, you need a Python + installation with the header files and + the sysconfig module. The minimum + required version is Python 3.2. + + + + Since PL/Python will be a shared + library, the libpython + libpython library must be a shared library + also on most platforms. This is not the case in a default + Python installation built from source, but a + shared library is available in many operating system + distributions. configure will fail if + building PL/Python is selected but it cannot + find a shared libpython. That might mean that you + either have to install additional packages or rebuild (part of) your + Python installation to provide this shared + library. When building from source, run Python's + configure with the --enable-shared flag. + + + + + + To build the PL/Tcl + procedural language, you of course need a Tcl + installation. The minimum required version is + Tcl 8.4. + + + + + + To enable Native Language Support (NLS), that + is, the ability to display a program's messages in a language + other than English, you need an implementation of the + Gettext API. Some operating + systems have this built-in (e.g., Linux, NetBSD, + Solaris), for other systems you + can download an add-on package from . + If you are using the Gettext implementation in + the GNU C library then you will additionally + need the GNU Gettext package for some + utility programs. For any of the other implementations you will + not need it. + + + + + + To build the PostgreSQL documentation, + there is a separate set of requirements; see + . + + + + + + + + + + Configuring the build + + + The first step of the installation procedure is to configure the + source tree for your system and choose the options you would like. To + create and configure the build directory, you can start with the + meson setup command. + + + +meson setup build + + + + The setup command takes a builddir and a srcdir + argument. If no srcdir is given Meson will deduce the + srcdir based on the current directory and the location + of meson.build. The builddir is mandatory. + + + + Meson then loads the build configuration file and sets up the build directory. + Additionally, the invocation can pass options to Meson. The list of commonly + used options is in subsequent sections. A few examples of specifying different + build options are: + + +#Setup build directory with a different installation prefix +meson setup build --prefix=/home/user/pg-install + +#Setup build directory to generate a debug build +meson setup build --buildtype=debug + +#Setup build directory with ssl (Use -D for project specific options) +meson setup build -Dssl=openssl + + + Setting up the build directory is a one-time step. To reconfigure before a + new build, you can simply use the meson configure command + + + + +meson configure -Dcassert=true + + + + + meson configure's commonly used command line options + are explained below. This list is not exhaustive (use + meson configure --help to get one that is). + The options not covered here are meant for advanced use-cases, and are + documented in the standard meson + documentation. + These arguments can be used with meson setup as well. + + + + Installation Locations + + + These options control where ninja install (or meson install) will put + the files. The option is sufficient for + most cases. If you have special needs, you can customize the + installation 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 man and doc locations are + not affected by this restriction.) + + + + + + + + Install all files under the directory PREFIX + instead of /usr/local/pgsql. The actual + files will be installed into various subdirectories; no files + will ever be installed directly into the + PREFIX directory. + + + + + + + + + Specifies the directory for executable programs. The default + is PREFIX/bin, which + normally means /usr/local/pgsql/bin. + + + + + + + + + Sets the directory for various configuration files, + PREFIX/etc by default. + + + + + + + + + Sets the location to install libraries and dynamically loadable + modules. The default is + PREFIX/lib. + + + + + + + + + Sets the directory for installing C and C++ header files. The + default is PREFIX/include. + + + + + + + + + Sets the directory for read-only data files used by the + installed programs. The default is + PREFIX/share. Note that this has + nothing to do with where your database files will be placed. + + + + + + + + + Sets the directory for installing locale data, in particular + message translation catalog files. The default is + DATADIR/locale. + + + + + + + + + The man pages that come with PostgreSQL will be installed under + this directory, in their respective + manx subdirectories. + The default is DATADIR/man. + + + + + + + + + Care has been taken to make it possible to install + PostgreSQL into shared installation locations + (such as /usr/local/include) without + interfering with the namespace of the rest of the system. First, + the string /postgresql is + automatically appended to datadir, + sysconfdir, and docdir, + unless the fully expanded directory name already contains the + string postgres or + pgsql. For example, if you choose + /usr/local as prefix, the documentation will + be installed in /usr/local/doc/postgresql, + but if the prefix is /opt/postgres, then it + will be in /opt/postgres/doc. The public C + header files of the client interfaces are installed into + includedir and are namespace-clean. The + internal header files and the server header files are installed + into private directories under includedir. See + the documentation of each interface for information about how to + access its header files. Finally, a private subdirectory will + also be created, if appropriate, under libdir + for dynamically loadable modules. + + + + + + <productname>PostgreSQL</productname> Features + + + The options described in this section enable building of + various PostgreSQL features that are not + built by default. Most of these are non-default only because they + require additional software, as described in + . To specify PostgreSQL + specific options, the name of the option should be prefixed by -D. + + + + + + + + + Enables or disables Native Language Support (NLS), + that is, the ability to display a program's messages in a + language other than English. It defaults to auto, meaning that it + will be enabled automatically if the required packages are found. + + + + To use this option, you will need an implementation of the + Gettext API. + + + + + + + + + Build the PL/Perl server-side language. It + defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Build the PL/Python server-side language. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Build the PL/Tcl server-side language. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Specifies the TCL version to use when building PL/Tcl. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Build with support for + the ICUICU + library, enabling use of ICU collation + features (see + ). + This requires the ICU4C package + to be installed. The minimum required version + of ICU4C is currently 4.2. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + By default, + pkg-configpkg-config + will be used to find the required compilation options. This is + supported for ICU4C version 4.6 and later. + + + + + + + + + + Build with support for LLVM based + JIT compilation (see ). This + requires the LLVM library to be installed. + The minimum required version of LLVM is + currently 3.9. It is set to disabled by default. + + + llvm-configllvm-config + will be used to find the required compilation options. + llvm-config, and then + llvm-config-$major-$minor for all supported + versions, will be searched for in your PATH. + + + + + LLVM support requires a compatible + clang compiler (specified, if necessary, using the + CLANG environment variable), and a working C++ + compiler (specified, if necessary, using the CXX + environment variable). + + + + + + + + + Build with LZ4 compression support. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Build with Zstandard compression support. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + OpenSSL + SSL + + + + + Build with support for SSL (encrypted) + connections. The only LIBRARY + supported is . This requires the + OpenSSL package to be installed. + configure will check for the required + header files and libraries to make sure that your + OpenSSL installation is sufficient + before proceeding. The default for this option is none. + + + + + + + + + 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., /usr/include, + /usr/lib), so you must use the options + and in + addition to this option. meson configure will check + for the required header files and libraries to make sure that + your GSSAPI installation is sufficient before proceeding. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Build with LDAPLDAP + support for authentication and connection parameter lookup (see + and + for more information). On Unix, + this requires the OpenLDAP package to be + installed. On Windows, the default WinLDAP + library is used. configure will check for the required + header files and libraries to make sure that your + OpenLDAP installation is sufficient before + proceeding. It defaults to auto, meaning that it will be enabled automatically + if the required packages are found. + + + + + + + + + Build with PAMPAM + (Pluggable Authentication Modules) support. It defaults to auto, meaning that it + will be enabled automatically if the required packages are found. + + + + + + + + + Build with BSD Authentication support. (The BSD Authentication framework is + currently only available on OpenBSD.) It defaults to auto, meaning that it + will be enabled automatically if the required packages are found. + + + + + + + + + Build with support + for systemdsystemd + service notifications. This improves integration if the server + is started under systemd but has no impact + otherwise; see for more + information. libsystemd and the + associated header files need to be installed to use this option. + It defaults to auto, meaning that it will be enabled automatically if the + required packages are found. + + + + + + + + + Build with support for Bonjour automatic service discovery. + This requires Bonjour support in your operating system. + Recommended on macOS. It defaults to auto, meaning that it will be + enabled automatically if the required packages are found. + + + + + + + + + Build the module + (which provides functions to generate UUIDs), using the specified + UUID library.UUID + LIBRARY must be one of: + + + + + to not build the ussp module. This is the default. + + + + + to use the UUID functions found in FreeBSD, NetBSD, + and some other BSD-derived systems + + + + + to use the UUID library created by + the e2fsprogs project; this library is present in most + Linux systems and in macOS, and can be obtained for other + platforms as well + + + + + to use the OSSP UUID library + + + + + + + + + + + Build with libxml2, enabling SQL/XML support. Libxml2 version 2.6.23 or + later is required for this feature. It defaults to auto, meaning that it will be + enabled automatically if the required packages are found. + + + + To detect the required compiler and linker options, PostgreSQL will + query pkg-config, if that is installed and knows + about libxml2. Otherwise the program xml2-config, + which is installed by libxml2, will be used if it is found. Use + of pkg-config is preferred, because it can deal + with multi-architecture installations better. + + + + To use a libxml2 installation that is in an unusual location, you + can set pkg-config-related environment + variables (see its documentation). + + + + + + + + + Build with libxslt, enabling the + + module to perform XSL transformations of XML. + must be specified as well. + It defaults to auto, meaning that it will be + enabled automatically if the required packages are found. + + + + + + + + + Allows use of the Readline library + (and libedit as well). This option enables + command-line editing and history in + psql and is strongly recommended. + It defaults to auto, meaning that it will be + enabled automatically if the required packages are found. + + + + + + + + + Setting this to true favors the use of the BSD-licensed libedit library + rather than GPL-licensed Readline. This option + is significant only if you have both libraries installed; the + default is false that is to use Readline. + + + + + + + + + + zlib + + Enabls use of the Zlib library. + This enables + support for compressed archives in pg_dump + and pg_restore and is recommended. + It defaults to auto, meaning that it will be + enabled automatically if the required packages are found. + + + + + + + + + This option is set to true by default and + setting it to false will allow the build to succeed even if PostgreSQL + has no CPU spinlock support for the platform. The lack of + spinlock support will result in very poor performance; therefore, + this option should only be changed if the build aborts and + informs you that the platform lacks spinlock support. If setting this + option to false is required to build PostgreSQL on + your platform, please report the problem to the + PostgreSQL developers. + + + + + + + + + This option is set to true and setting it to false will + disable use of CPU atomic operations. The option does nothing on + platforms that lack such operations. On platforms that do have + them, disabling atomics will result in poor performance. Changing + this option is only useful for debugging or making performance comparisons. + + + + + + + + Build Process Details + + + + + + + + Setting this option allows you to override value of all 'auto' features. + This can be useful when you want to disable or enable all the "optional" + features at once without having to set each of them manually. The default + value for this parameter is auto. + + + + + + + + + The default backend meson uses is ninja and that should suffice for most use cases. + However, if you'd like to fully integrate with visual studio, you can set the + BACKEND to vs. + + + + + + + + + This option can be used to pass extra options to the C compiler. + + + + + + + + + This option can be used to pass extra options to the C linker. + + + + + + + + + DIRECTORIES 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 Readline) installed in a non-standard + location, + you have to use this option and probably also the corresponding + option. + + + Example: -Dextra_include_dirs=/opt/gnu/include:/usr/sup/include. + + + + + + + + + DIRECTORIES is a colon-separated list of + directories to search for libraries. You will probably have + to use this option (and the corresponding + option) if you have packages + installed in non-standard locations. + + + Example: -Dextra_lib_dirs=/opt/gnu/lib:/usr/sup/lib. + + + + + + + + time zone data + + + + + PostgreSQL includes its own time zone database, + which it requires for date and time operations. This time zone + database is in fact compatible with the IANA time zone + database provided by many operating systems such as FreeBSD, + Linux, and Solaris, so it would be redundant to install it again. + When this option is used, the system-supplied time zone database + in DIRECTORY is used instead of the one + included in the PostgreSQL source distribution. + DIRECTORY must be specified as an + absolute path. /usr/share/zoneinfo is a + likely directory on some operating systems. Note that the + installation routine will not detect mismatching or erroneous time + zone data. If you use this option, you are advised to run the + regression tests to verify that the time zone data you have + pointed to works correctly with PostgreSQL. + + + cross compilation + + + This option is mainly aimed at binary package distributors + who know their target operating system well. The main + advantage of using this option is that the PostgreSQL package + won't need to be upgraded whenever any of the many local + daylight-saving time rules change. Another advantage is that + PostgreSQL can be cross-compiled more straightforwardly if the + time zone database files do not need to be built during the + installation. + + + + + + + + + Append STRING 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 git describe identifier or a + distribution package release number. + + + + + + + + + If you have the binaries for certain by programs required to build + Postgres (with or without optional flags) stored at non-standard + paths, you could specify them manually to meson configure. The complete + list of programs for whom this is supported can be found by running + meson configure. An example is included below. +meson configure -DBISON=PATH_TO_BISON + + + + + + + + Data layout + + + These options affect how PostgreSQL lays out data on disk. + Note that changing these breaks on-disk database compatibility, + meaning you cannot use pg_upgrade to upgrade to + a build with a different value of these options. + + + + + + + + + Set the segment size, 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 + largefile 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 tar, could + also set limits on the usable file size. + It is recommended, though not absolutely required, that this value + be a power of 2. + + + + + + + + + Set the block size, 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). + + + + + + + + + Set the WAL block size, 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). + + + + + + + + + Developer Options + + + Most of the options in this section are only of interest for + developing or debugging PostgreSQL. + They are not recommended for production builds, except + for , which can be useful to enable + detailed bug reports in the unlucky event that you encounter a bug. + On platforms supporting DTrace, + may also be reasonable to use in production. + + + + When building an installation that will be used to develop code inside + the server, it is recommended to use at least the + and options. + + + + + + + + This option can be used to specify the buildtype to use; defaults + to release. If you'd like finer control on the debug symbols + and optimization levels than what this option provides, you can + refer to the --debug and --optimization flags. + + The following build types are generally used: + + + plain + + + No extra build flags are used, even for compiler warnings, + useful for distro packagers and other cases where you need to + specify all arguments by yourself. + + + + + + debug + + + Debug info is generated but the result is not optimized. + + + + + + debugoptimized + + + Debug info is generated and the code is optimized (on most compilers + this means -g -O2) + + + + + + release + + + This enables full optimization and no debug info is generated. This is + the default. + + + + + + + + + + + + + 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. + + + + + + =LEVEL + + + Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}. + + + + + + + + + Setting this option asks the compiler to treat warnings as errors. This can + be useful for code development purposes. + + + + + + + + + Enables assertion checks in the server, which test for + many cannot happen conditions. This is invaluable for + code development purposes, but the tests can slow down the + server significantly. + Also, having the tests turned on won't necessarily enhance the + stability of your server! The assertion checks are not categorized + for severity, and so what might be a relatively harmless bug will + still lead to server restarts if it triggers an assertion + failure. This option is not recommended for production use, but + you should have it on for development work or when running a beta + version. + + + + + + + + + Enable tests using the Perl TAP tools. This requires a Perl + installation and the Perl module IPC::Run. + See for more information. + + + + + + + + + Enable test suites which require special software to run. This option + accepts arguments via a whitespace-separated list. The following values + are currently supported: + + + kerberos + + + Runs the test suite under src/test/kerberos. This + requires an MIT Kerberos installation and opens TCP/IP listen sockets. + + + + + + ldap + + + Runs the test suite under src/test/ldap. This + requires an OpenLDAP installation and opens + TCP/IP listen sockets. + + + + + + ssl + + + Runs the test suite under src/test/ssl. This opens TCP/IP listen sockets. + + + + + + wal_consistency_checking + + + Uses wal_consistency_checking=all while running + certain tests under src/test/recovery. Not + enabled by default because it is resource intensive. + + + + + Tests for features that are not supported by the current build + configuration are not run even if they are mentioned in + PG_TEST_EXTRA. + + + + + + + + + This option can be used to print the logs from the failing tests + making debugging easier. + + + + + + + + + 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. + See + for more information. This option is for use only with GCC + and when doing development work. + + + + + + + + + + DTrace + + Enabling this compiles PostgreSQL with support for the + dynamic tracing tool DTrace. + See + for more information. + + + + To point to the dtrace program, the + environment variable DTRACE can be set. This + will often be necessary because dtrace is + typically installed under /usr/sbin, + which might not be in your PATH. + + + + + + + + + Miscellaneous + + + + + + + Set NUMBER 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 + PostgreSQL servers on the same machine. + + + + + + + + + The default name of the Kerberos service principal used + by GSSAPI. + postgres is the default. There's usually no + reason to change this unless you are building for a Windows + environment, in which case it must be set to upper case + POSTGRES. + + + + + + + + + + Building the source + + By default, Meson uses the + Ninja build system. + To build PostgreSQL from source using meson, you can + simply use the ninja command in the build directory. + +ninja + + Ninja will automatically detect the number of CPUs in your computer and + parallelize itself accordingly. You can override the amount of parallel + processes used with the command line argument -j. + + + + It should be noted that after the initial configure step + ninja is the only command you ever need to type to + compile. No matter how you alter your source tree (short of moving it to + a completely new location), Meson will detect the changes and regenerate + itself accordingly. This is especially handy if you have multiple build + directories. Often one of them is used for development (the "debug" build) + and others only every now and then (such as a "static analysis" build). + Any configuration can be built just by cd'ing to the corresponding directory + and running Ninja. + + + + If you'd like to build with a backend other that ninja, you can use configure + with the option to select the one you want to use and then + build using meson compile. To learn more about these + backends and other arguments you can provide to ninja, you can refer to the + meson + documentation. + + + + + Installing the files + + Once Postgres is built, you can install it by simply running the + ninja install command. + + +ninja install + + + + + This will install files into the directories that were specified + in . Make sure that you have appropriate + permissions to write into that area. You might need to do this + step as root. Alternatively, you can create the target directories + in advance and arrange for appropriate permissions to be granted. + 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. + + + + ninja install should work for most cases + but if you'd like to use more options, you could also use + meson install instead. You can learn more about + meson install + and it's options in the meson documentation. + + + + Depending on your platform and setup, you might have to perform a + few steps after installation. Those are outlined in + . + + + + Uninstallation: + + To undo the installation, you can use the ninja + uninstall command. + + + + + Cleaning: + + After the installation you can free disk space by removing the built + files from the source tree with the ninja clean + command. + + + + + + + Running tests + + If you want to test the newly built server, you can run the regression + tests. The regression tests are a collection of test suites to verify + that PostgreSQL runs on your machine in + the way the developers expected it to. To run them, simply type: + +meson test + + You can repeat this at any later time by issuing the same command. + + + Meson also allows you to list tests and run specific tests or suites. + +# List all tests +meson test --list + +# Run a specific test +meson test recovery/001_stream_rep + +# Run the main pg_regress and isolation tests +meson test --suite main + + + + + To learn more about running the tests and how to interpret the results + you can refer to the documentation for interpreting test results. + meson test also provides a number of additional + options you can use which can be found in the + meson test documentation. + + + + + + Post-Installation Setup @@ -2106,62 +3797,6 @@ export MANPATH - - Supported Platforms - - - A platform (that is, a CPU architecture and operating system combination) - is considered supported by the PostgreSQL development - community if the code contains provisions to work on that platform and - it has recently been verified to build and pass its regression tests - on that platform. Currently, most testing of platform compatibility - is done automatically by test machines in the - PostgreSQL Build Farm. - If you are interested in using PostgreSQL on a platform - that is not represented in the build farm, but on which the code works - or can be made to work, you are strongly encouraged to set up a build - farm member machine so that continued compatibility can be assured. - - - - In general, PostgreSQL can be expected to work on - these CPU architectures: x86, PowerPC, S/390, SPARC, ARM, MIPS, RISC-V, - and PA-RISC, including - big-endian, little-endian, 32-bit, and 64-bit variants where applicable. - It is often - possible to build on an unsupported CPU type by configuring with - , but performance will be poor. - - - - PostgreSQL can be expected to work on current - versions of these operating systems: Linux, Windows, - FreeBSD, OpenBSD, NetBSD, DragonFlyBSD, macOS, AIX, Solaris, and illumos. - Other Unix-like systems may also work but are not currently - being tested. In most cases, all CPU architectures supported by - a given operating system will work. Look in - below to see if - there is information - specific to your operating system, particularly if using an older system. - - - - If you have installation problems on a platform that is known - to be supported according to recent build farm results, please report - it to pgsql-bugs@lists.postgresql.org. If you are interested - in porting PostgreSQL to a new platform, - pgsql-hackers@lists.postgresql.org is the appropriate place - to discuss that. - - - - Historical versions of PostgreSQL or POSTGRES - also ran on CPU architectures including Alpha, Itanium, M32R, M68K, - M88K, NS32K, SuperH, and VAX, and operating systems including 4.3BSD, BEOS, - BSD/OS, DG/UX, Dynix, HP-UX, IRIX, NeXTSTEP, QNX, SCO, SINIX, Sprite, SunOS, - Tru64 UNIX, and ULTRIX. - - Platform-Specific Notes @@ -2170,7 +3805,7 @@ export MANPATH This section documents additional platform-specific issues regarding the installation and setup of PostgreSQL. Be sure to read the installation instructions, and in - particular as well. Also, + particular as well. Also, check regarding the interpretation of regression test results. diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 1d9509a2f66..214e1b1d551 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -7072,7 +7072,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, explicitly tell the configure script to make the probes available in PostgreSQL. To include DTrace support specify to configure. See for further information. + linkend="configure-options-devel"/> for further information. diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index f268265a838..7a1d220175b 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1855,7 +1855,7 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid` Install the new version of PostgreSQL as - outlined in . + outlined in . diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml index 0ed7f8a3fea..f16be29a61a 100644 --- a/doc/src/sgml/sourcerepo.sgml +++ b/doc/src/sgml/sourcerepo.sgml @@ -20,9 +20,10 @@ Note that building PostgreSQL from the source repository requires reasonably up-to-date versions of bison, flex, and Perl. These tools are not needed - to build from a distribution tarball, because the files that these tools + to build from a distribution tarball if building via make, because the files that these tools are used to build are included in the tarball. Other tool requirements - are the same as shown in . + are the same as shown in and + . -- 2.37.3.542.gdd3f6c4cae