From 4c72102e1d45f787db958204a6f7097c1e2a435e Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 1 Dec 2022 15:32:38 +0100 Subject: [PATCH] doc: Add installation instructions for building with meson Author: samay sharma Reviewed-by: Justin Pryzby Reviewed-by: Andres Freund Reviewed-by: Nazir Bilal Yavuz Reviewed-by: Peter Eisentraut Discussion: https://www.postgresql.org/message-id/flat/CAJxrbywFPcgC4nP_v+HHPhaYSWX2JL8FZXY2aFOZxXxTkTJJPw@mail.gmail.com --- doc/src/sgml/installation.sgml | 1199 ++++++++++++++++++++++++++- doc/src/sgml/monitoring.sgml | 2 +- doc/src/sgml/regress.sgml | 2 +- doc/src/sgml/runtime.sgml | 2 +- doc/src/sgml/standalone-install.xml | 3 +- 5 files changed, 1178 insertions(+), 30 deletions(-) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 15cac7dce7..9c7f019392 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -31,30 +31,6 @@ documentation. See standalone-profile.xsl for details. C++, see instead. - - Short Version - - - -./configure -make -su -make install -adduser postgres -mkdir -p /usr/local/pgsql/data -chown postgres /usr/local/pgsql/data -su - postgres -/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data -/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start -/usr/local/pgsql/bin/createdb test -/usr/local/pgsql/bin/psql test - - The long version is the rest of this - chapter. - - - - Requirements @@ -88,6 +64,26 @@ su - postgres + + + + Meson + + + Alternatively, PostgreSQL can be built using + Meson. This is currently + experimental and only works when building from a Git checkout (not from + a distribution tarball). If you choose to use + Meson, then you don't need + GNU make, but the other + requirements below still apply. + + + + The minimum required version of Meson is 0.54. + + + You need an ISO/ANSI C compiler (at least @@ -370,7 +366,34 @@ su - postgres - + + Building and Installation with Autoconf and Make + + + Short Version + + + +./configure +make +su +make install +adduser postgres +mkdir -p /usr/local/pgsql/data +chown postgres /usr/local/pgsql/data +su - postgres +/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start +/usr/local/pgsql/bin/createdb test +/usr/local/pgsql/bin/psql test + + The long version is the rest of this + section. + + + + + Installation Procedure @@ -619,6 +642,7 @@ build-postgresql: rebuilding. Without this, your changes in configuration choices might not propagate everywhere they need to. + <filename>configure</filename> Options @@ -1947,6 +1971,1131 @@ build-postgresql: + + Building and Installation with Meson + + + Short Version + + + +meson setup build --prefix=/usr/local/pgsql +cd build +ninja +su +ninja install +adduser postgres +mkdir -p /usr/local/pgsql/data +chown postgres /usr/local/pgsql/data +su - postgres +/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start +/usr/local/pgsql/bin/createdb test +/usr/local/pgsql/bin/psql test + + The long version is the rest of this + section. + + + + + Installation Procedure + + + + + Configuration + + + The first step of the installation procedure is to configure the + build 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. + + + + Running meson setup loads the build configuration file and sets up the build directory. + Additionally, you can also pass several build options to Meson. Some commonly + used options are mentioned in the subsequent sections. For example: + + +# configure with a different installation prefix +meson setup build --prefix=/home/user/pg-install + +# configure to generate a debug build +meson setup build --buildtype=debug + +# configure to build with OpenSSL support +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 in . + + + + + Build + + + By default, Meson uses the Ninja build tool. 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 number 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 than 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. + + + + + Regression Tests + + + regression test + + + + 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 PostgreSQL + runs on your machine in the way the developers expected it + to. Type: + +meson test + + (This won't work as root; do it as an unprivileged user.) + See for + detailed information about interpreting the test results. You can + repeat this test at any later time by issuing the same command. + + + + + Installing the Files + + + + If you are upgrading an existing system be sure to read + , + which has instructions about upgrading a + cluster. + + + + + Once PostgreSQL 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 (such as to suppress + extra output), you could also use meson install + instead. You can learn more about meson install + and its options in the Meson documentation. + + + + + + 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. + + + + + + <literal>meson setup</literal> Options + + + meson setup's 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 (example + ) 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 (on Unix based systems) or + current drive letter:/usr/local/pgsql (on Windows). + 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. + + + + + + + + + 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 optional PostgreSQL features. + Most of these require additional software, as described in + , and will be automatically enabled if the + required software is found. You can change this behavior by manually + setting these features to enabled to require them + or disabled to not build with them. + + + + To specify PostgreSQL-specific options, the name of the option + must 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. Defaults to auto and will be enabled + automatically if an implementation of the Gettext + API is found. + + + + + + + + + Build the PL/Perl server-side language. + Defaults to auto. + + + + + + + + + Build the PL/Python server-side language. + Defaults to auto. + + + + + + + + + Build the PL/Tcl server-side language. + Defaults to auto. + + + + + + + + + Specifies the Tcl version to use when building PL/Tcl. + + + + + + + + + Build with support for the + ICUICU + library, enabling use of ICU collation features (see ). Defaults to auto and requires the + ICU4C package to be installed. The minimum + required version of ICU4C is currently 4.2. + + + + + + + + + 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. Disabled by + default. + + + + llvm-configllvm-config + will be used to find the required compilation options. + llvm-config, and then + llvm-config-$version for all supported versions, + will be searched for in your PATH. If that would not + yield the desired program, use LLVM_CONFIG to specify a + path to the correct llvm-config. + + + + + + + + + Build with LZ4 compression support. + Defaults to auto. + + + + + + + + + Build with Zstandard compression support. + Defaults to auto. + + + + + + + + OpenSSL + SSL + + + + + Build with support for SSL (encrypted) connections. + The only LIBRARY supported is + . This requires the + OpenSSL package to be installed. Building + with this 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). In + those cases, PostgreSQL will query pkg-config to + detect the required compiler and linker options. Defaults to auto. + meson configure will check for the required + header files and libraries to make sure that your GSSAPI installation + is sufficient before proceeding. + + + + + + + + + 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. Defaults to auto. meson + configure will check for the required header files and + libraries to make sure that your OpenLDAP + installation is sufficient before proceeding. + + + + + + + + + Build with + PAMPAM + (Pluggable Authentication Modules) support. Defaults to auto. + + + + + + + + + Build with BSD Authentication support. (The BSD Authentication + framework is currently only available on OpenBSD.) Defaults to auto. + + + + + + + + + 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. Defaults to + auto. libsystemd and the associated header + files need to be installed to use this option. + + + + + + + + + Build with support for Bonjour automatic service discovery. Defaults + to auto and requires Bonjour support in your operating system. + Recommended on macOS. + + + + + + + + + Build the module + (which provides functions to generate UUIDs), using the specified + UUID library.UUID + LIBRARY must be one of: + + + + + to not build the uuid module. This is the default. + + + + + to use the UUID functions found in FreeBSD, + 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. Defaults to + auto. Libxml2 version 2.6.23 or later is required for this feature. + + + + 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. Defaults to + auto. + + + + + + + + Anti-Features + + + + + + + Allows use of the Readline library (and + libedit as well). This option defaults to + auto and enables command-line editing and history in + psql and is strongly recommended. + + + + + + + + + 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 + + Enables use of the Zlib library. + It defaults to auto and enables + support for compressed archives in pg_dump, + pg_restore and pg_basebackup and is recommended. + + + + + + + + + This option is set to true by default; 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 by default; 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 the value of all + auto features (features that are enabled automatically + if the required software is found). 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 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 comma-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 comma-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 a program required to build PostgreSQL (with or without optional + flags) is stored at a non-standard path, you can specify it manually + to meson configure. The complete list of programs + for which this is supported can be found by running meson + configure. Example: +meson configure -DBISON=PATH_TO_BISON + + + + + + + + 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. + + + + + + + + + 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 + . If you'd like finer control on the debug + symbols and optimization levels than what this option provides, you + can refer to the and + flags. + + + + The following build types are generally used: , + , and + . More information about them can be found in + the Meson + documentation. + + + + + + + + + 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. 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. + + + + + + + + + Enables assertion checks in the server, which + test for many cannot happen conditions. This is + invaluable for code development purposes, but the tests 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. Defaults to auto and 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. See for details. + + + + + + + + + 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 + option can be set. This + will often be necessary because dtrace is + typically installed under /usr/sbin, + which might not be in your PATH. + + + + + + + + Post-Installation Setup diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index b41b4e2a90..11a8ebe5ec 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -7120,7 +7120,7 @@ FROM pg_stat_get_backend_idset() AS backendid; 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/regress.sgml b/doc/src/sgml/regress.sgml index 23ea93a387..2eb27f71d8 100644 --- a/doc/src/sgml/regress.sgml +++ b/doc/src/sgml/regress.sgml @@ -123,7 +123,7 @@ make installcheck-parallel - + Additional Test Suites diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 66367587b2..bb51cab3ea 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1857,7 +1857,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/standalone-install.xml b/doc/src/sgml/standalone-install.xml index afab502be2..b29e90daf9 100644 --- a/doc/src/sgml/standalone-install.xml +++ b/doc/src/sgml/standalone-install.xml @@ -22,9 +22,8 @@ in the stand-alone version. C++, see the main documentation instead. - - +