Documentation for building with meson
Started by samay sharmaabout 3 years ago32 messages
Hi,
Creating a new thread focussed on adding docs for building Postgres with
meson. This is a spinoff from the original thread [1]/messages/by-id/28de92b5-a514-fe1b-1637-ba228aa2cccf@enterprisedb.com and I've attempted to
address all the feedback provided there in the attached patch.
Please let me know your thoughts.
[1]: /messages/by-id/28de92b5-a514-fe1b-1637-ba228aa2cccf@enterprisedb.com
/messages/by-id/28de92b5-a514-fe1b-1637-ba228aa2cccf@enterprisedb.com
Regards,
Samay
Attachments:
v1-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v1-0001-Add-docs-for-building-with-meson.patchDownload
From 95cc50eb93678b54cc6e71850cdaa166afd49076 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v1] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1669 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1630 insertions(+), 48 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..7eacae519d 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the Git version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1593 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <literal>pip</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.31 or later and
+ <application>Bison</application> 1.875 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application> and
+ <application>pg_restore</application> and is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>LZ4</productname>, if you want to support
+ compression of data with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>Zstandard</productname>, if you want to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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:
+
+<screen>
+#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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename>. The actual
+ files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>, which
+ normally means <filename>/usr/local/pgsql/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various <productname>PostgreSQL</productname> features that are not
+ built by default. Most of these are non-default only because they
+ require additional software, as described in
+ <xref linkend="install-requirements-meson"/>. To specify PostgreSQL
+ specific options, the name of the option should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ 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.
+ </para>
+
+ <para>
+ To use this option, you will need an implementation of the
+ <application>Gettext</application> API.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ This requires the <productname>ICU4C</productname> package
+ to be installed. The minimum required version
+ of <productname>ICU4C</productname> is currently 4.2.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </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.
+ <!-- Add description for older ICU4C versions and when pkg-config isn't available-->
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$major-$minor</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>.
+ <!--Add substitute fo LLVM_CONFIG when llvm-config is not in PATH-->
+ </para>
+
+ <para>
+ <productname>LLVM</productname> support requires a compatible
+ <command>clang</command> compiler (specified, if necessary, using the
+ <envar>CLANG</envar> environment variable), and a working C++
+ compiler (specified, if necessary, using the <envar>CXX</envar>
+ environment variable).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ <filename>configure</filename> will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>-Dextra_include_dirs</option> and <option>-Dextra_lib_dirs</option> in
+ addition to this option. <filename>meson configure</filename> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. <filename>configure</filename> will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding. It defaults to auto, meaning that it will be enabled automatically
+ if the required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto, meaning that it
+ will be enabled automatically if the required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ 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 use this option.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the ussp module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD, NetBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ To detect the required compiler and linker options, PostgreSQL will
+ query <command>pkg-config</command>, if that is installed and knows
+ about libxml2. Otherwise the program <command>xml2-config</command>,
+ which is installed by libxml2, will be used if it is found. Use
+ of <command>pkg-config</command> is preferred, because it can deal
+ with multi-architecture installations better.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option enables
+ command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enabls use of the <application>Zlib</application> library.
+ This enables
+ support for compressed archives in <application>pg_dump</application>
+ and <application>pg_restore</application> and is recommended.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required packages are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default and
+ setting it to false will 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<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>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include:/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<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>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib:/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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>
+
+ <varlistentry>
+ <term><option>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ 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
+ <literal>meson configure</literal>. An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with a different value of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 atleast the <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ 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:
+ <variablelist>
+ <varlistentry>
+ <term><literal>plain</literal></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>debug</literal></term>
+ <listitem>
+ <para>
+ Debug info is generated but the result is not optimized.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>debugoptimized</literal></term>
+ <listitem>
+ <para>
+ Debug info is generated and the code is optimized (on most compilers
+ this means <literal>-g -O2</literal>)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>release</literal></term>
+ <listitem>
+ <para>
+ This enables full optimization and no debug info is generated. This is
+ the default.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--errorlogs</option></term>
+ <listitem>
+ <para>
+ This option can be used to print the logs from the failing tests
+ making debugging easier.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ environment variable <envar>DTRACE</envar> can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other that ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once Postgres is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases
+ but if you'd like to use more options, you could also use
+ <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and it's options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run a specific test
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+# Run the main pg_regress and isolation tests
+<userinput>meson test --suite main</userinput>
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results
+ you can refer to the documentation for interpreting test results.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3751,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e5d622d514..bfd52e7b23 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7115,7 +7115,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
On Wed, Oct 19, 2022 at 11:35:10AM -0700, samay sharma wrote:
Creating a new thread focussed on adding docs for building Postgres with
meson. This is a spinoff from the original thread [1] and I've attempted to
address all the feedback provided there in the attached patch.Please let me know your thoughts.
It's easier to review rendered documentation.
I made a rendered copy available here:
https://api.cirrus-ci.com/v1/artifact/task/6084297781149696/html_docs/html_docs/install-meson.html
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.31 or later and
+ <application>Bison</application> 1.875 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.These versions need to be updated, see also: 57bab3330:
- b086a47a270 "Bump minimum version of Bison to 2.3"
- 8b878bffa8d "Bump minimum version of Flex to 2.5.35"
+ will be enabled automatically if the required packages are found.
should refer to files/libraries/headers/dependencies rather than
"packages" ?
+ default is false that is to use <application>Readline</application>.
"that is to use" should be parenthesized or separate with commas, like
| default is false, that is to use <application>Readline</application>.
zlib is mentioned twice, the first being "strongly recommended".
Is that intended? Also, basebackup can use zlib, too.
+ If you have the binaries for certain by programs required to build
remove "by" ?
+ 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 runningfor *which
Actually, I suggest to say:
|If a program required to build Postgres (with or without optional flags)
|is stored in a non-standard path, ...
+ a build with a different value of these options.
.. with different values ..
+ the server, it is recommended to use atleast the <option>--buildtype=debug</option>
at least
+ and it's options in the meson documentation.
its
Maybe other things should have <productname> ?
Git
Libxml2
libxslt
visual studio
DTrace
ninja
+ <application>Flex</application> and <application>Bison</application>
Maybe these should use <productname> ?
+ be installed with <literal>pip</literal>.
Should be <application> ?
This part is redundant with prior text:
" To use this option, you will need an implementation of the Gettext API. "
+ Enabls use of the Zlib library
typo: Enabls
+ This option is set to true by default and setting it to false will
change "and" to ";" for spinlocks and atomics?
+ Debug info is generated but the result is not optimized.
Maybe say the "code" is not optimized ?
+ the tests can slow down the server significantly
remove "can"
+ You can override the amount of parallel processes used with
s/amount/number/
+ If you'd like to build with a backend other that ninja
other *than
+ the <acronym>GNU</acronym> C library then you will additionally
library comma
+ argument. If no <literal>srcdir</literal> is given Meson will deduce the
given comma
+ It should be noted that after the initial configure step
step comma
+ After the installation you can free disk space by removing the built
installation comma
+ To learn more about running the tests and how to interpret the results
+ you can refer to the documentation for interpreting test results.interpret the results comma
"for interpreting test results" seems redundant.
+ ninja install should work for most cases but if you'd like to use more options
cases comma
Starting with "Developer Options", this intermixes postgres
project-specific options like cassert and tap-tests with meson's stuff
like buildtype and werror. IMO there's too much detail about meson's
options, which I think is better left to that project's own
documentation, and postgres docs should include only a brief mention and
a reference to their docs.
+ 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. too much detail for my taste..
--
Justin
Re: Documentation for building with meson
Hi,
On Wed, Oct 19, 2022 at 7:43 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
On Wed, Oct 19, 2022 at 11:35:10AM -0700, samay sharma wrote:
Creating a new thread focussed on adding docs for building Postgres with
meson. This is a spinoff from the original thread [1] and I've attemptedto
address all the feedback provided there in the attached patch.
Please let me know your thoughts.
It's easier to review rendered documentation.
I made a rendered copy available here:https://api.cirrus-ci.com/v1/artifact/task/6084297781149696/html_docs/html_docs/install-meson.html
Thanks for your for review. Attached v2 of the patch here.
+ <application>Flex</application> and <application>Bison</application> + are needed to build <productname>PostgreSQL</productname> using + <application>meson</application>. Be sure to get + <application>Flex</application> 2.5.31 or later and + <application>Bison</application> 1.875 or later from your package manager. + Other <application>lex</application> and <application>yacc</application> + programs cannot be used.These versions need to be updated, see also: 57bab3330:
- b086a47a270 "Bump minimum version of Bison to 2.3"
- 8b878bffa8d "Bump minimum version of Flex to 2.5.35"
Changed
+ will be enabled automatically if the required packages are found.
should refer to files/libraries/headers/dependencies rather than
"packages" ?
Changed to dependencies
+ default is false that is to use
<application>Readline</application>."that is to use" should be parenthesized or separate with commas, like
| default is false, that is to use <application>Readline</application>.zlib is mentioned twice, the first being "strongly recommended".
Is that intended? Also, basebackup can use zlib, too.
Yes, the first is in the requirements section where we just list packages
required / recommended. The other mention is in the list of configure
options. This is similar to how the documentation looks today for make /
autoconf. Added pg_basebackup as a use case too.
+ If you have the binaries for certain by programs required to
buildremove "by" ?
Done
+ 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 runningfor *which
Actually, I suggest to say:
|If a program required to build Postgres (with or without optional flags)
|is stored in a non-standard path, ...
Liked this framing better. Changed.
+ a build with a different value of these options.
.. with different values ..
Done
+ the server, it is recommended to use atleast the
<option>--buildtype=debug</option>at least
Done
+ and it's options in the meson documentation.
its
Done
Maybe other things should have <productname> ?
Git
Libxml2
libxslt
visual studio
DTrace
ninja+ <application>Flex</application> and <application>Bison</application>
Maybe these should use <productname> ?
I'm unsure of the right protocol for this. I tried to follow the precedent
set in the make / autoconf part of the documentation, which uses
<productname> at certain places and <application> at others. Is there a
reference or guidance on which to use where or is it mostly a case by case
decision?
+ be installed with <literal>pip</literal>.
Should be <application> ?
Changed.
This part is redundant with prior text:
" To use this option, you will need an implementation of the Gettext API. "
Modified.
+ Enabls use of the Zlib library
typo: Enabls
Fixed.
+ This option is set to true by default and setting it to false will
change "and" to ";" for spinlocks and atomics?
Done
+ Debug info is generated but the result is not optimized.
Maybe say the "code" is not optimized ?
Changed
+ the tests can slow down the server significantly
remove "can"
Done.
+ You can override the amount of parallel processes used with
s/amount/number/
Done
+ If you'd like to build with a backend other that ninja
other *than
Fixed.
+ the <acronym>GNU</acronym> C library then you will additionally
library comma
Added
+ argument. If no <literal>srcdir</literal> is given Meson will deduce
thegiven comma
Added
+ It should be noted that after the initial configure step
step comma
Added
+ After the installation you can free disk space by removing the built
installation comma
Added
+ To learn more about running the tests and how to interpret the results + you can refer to the documentation for interpreting test results.interpret the results comma
"for interpreting test results" seems redundant.
Changed.
+ ninja install should work for most cases but if you'd like to use more
optionscases comma
Added
Starting with "Developer Options", this intermixes postgres
project-specific options like cassert and tap-tests with meson's stuff
like buildtype and werror. IMO there's too much detail about meson's
options, which I think is better left to that project's own
documentation, and postgres docs should include only a brief mention and
a reference to their docs.
The meson specific options I've chosen to document are: auto_features,
backend, c_args, c_link_args, buildtype, optimization, werror,
errorlogs and b_coverage as I felt they might be used often and are useful
to know. But, it's very possible that some of them might be obvious and
others may not be as useful as I thought. Are there specific ones you'd
suggest we can remove? Also, if you're curious, this is the list I picked
from: https://mesonbuild.com/Commands.html#configure.
In terms of detail about individual options, I think the descriptions about
most of them are brief but buildtype was pretty verbose. I have shortened
it.
+ 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.too much detail for my taste..
I added this as make / autoconf doesn't do something like this. So, it
might be useful to know for people switching over.
Regards,
Samay
Show quoted text
--
Justin
Attachments:
v2-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v2-0001-Add-docs-for-building-with-meson.patchDownload
From d43857b5222f121a772887763e06a06d8d796d91 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v2] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1631 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1591 insertions(+), 49 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..867ee212b1 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the <productname>Git</productname> version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -237,7 +266,7 @@ su - postgres
can download an add-on package from <ulink
url="https://www.gnu.org/software/gettext/"></ulink>.
If you are using the <application>Gettext</application> implementation in
- the <acronym>GNU</acronym> C library then you will additionally
+ the <acronym>GNU</acronym> C library, then you will additionally
need the <productname>GNU Gettext</productname> package for some
utility programs. For any of the other implementations you will
not need it.
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1553 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <application>pip</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.35 or later and
+ <application>Bison</application> 2.3 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and
+ is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>LZ4</productname>, if you want to support
+ compression of data with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>Zstandard</productname>, if you want to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library, then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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:
+
+<screen>
+#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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename>. The actual
+ files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>, which
+ normally means <filename>/usr/local/pgsql/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various <productname>PostgreSQL</productname> features that are not
+ built by default. Most of these are non-default only because they
+ require additional software, as described in
+ <xref linkend="install-requirements-meson"/>. To specify PostgreSQL
+ specific options, the name of the option should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ 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 an implementation of the
+ <application>Gettext API</application> is found.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the TCL version to use when building PL/Tcl.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ This requires the <productname>ICU4C</productname> package
+ to be installed. The minimum required version
+ of <productname>ICU4C</productname> is currently 4.2.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </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.
+ <!-- Add description for older ICU4C versions and when pkg-config isn't available-->
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$major-$minor</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>.
+ <!--Add substitute fo LLVM_CONFIG when llvm-config is not in PATH-->
+ </para>
+
+ <para>
+ <productname>LLVM</productname> support requires a compatible
+ <command>clang</command> compiler (specified, if necessary, using the
+ <envar>CLANG</envar> environment variable), and a working C++
+ compiler (specified, if necessary, using the <envar>CXX</envar>
+ environment variable).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ <filename>configure</filename> will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>-Dextra_include_dirs</option> and <option>-Dextra_lib_dirs</option> in
+ addition to this option. <filename>meson configure</filename> 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 dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. <filename>configure</filename> will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding. It defaults to auto, meaning that it will be enabled automatically
+ if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto, meaning that it
+ will be enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ 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 use this option.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the ussp module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD, NetBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 dependencies are found.
+ </para>
+
+ <para>
+ To detect the required compiler and linker options, PostgreSQL will
+ query <command>pkg-config</command>, if that is installed and knows
+ about libxml2. Otherwise the program <command>xml2-config</command>,
+ which is installed by libxml2, will be used if it is found. Use
+ of <command>pkg-config</command> is preferred, because it can deal
+ with multi-architecture installations better.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option enables
+ command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false, that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enables use of the <application>Zlib</application> library.
+ This enables
+ support for compressed archives in <application>pg_dump</application>
+ ,<application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<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>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include:/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<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>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib:/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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 <productname>Git</productname>
+ 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>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ If a program required to build Postgres (with or without optional
+ flags) is stored at a non-standard path, you could specify it
+ manually to meson configure. The complete list of programs for which
+ this is supported can be found by running <literal>meson configure</literal>.
+ An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ 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, debug, debugoptimized
+ and release. More information about them can be found in the
+ <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">
+ meson documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--errorlogs</option></term>
+ <listitem>
+ <para>
+ This option can be used to print the logs from the failing tests
+ making debugging easier.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ environment variable <envar>DTRACE</envar> can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step,
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other than ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once Postgres is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases,
+ but if you'd like to use more options, you could also use
+ <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and its options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run a specific test
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+# Run the main pg_regress and isolation tests
+<userinput>meson test --suite main</userinput>
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results,
+ you can refer to the documentation.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3711,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e5d622d514..bfd52e7b23 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7115,7 +7115,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
+# Run the main pg_regress and isolation tests
+<userinput>meson test --suite main</userinput>This does not work for me in a fresh install until running
meson test --suite setup
In fact, we see in
https://wiki.postgresql.org/wiki/Meson
meson test --suite setup --suite main
That was just an eyeball check from a naive user -- it would be good to try
running everything documented here.
--
John Naylor
EDB: http://www.enterprisedb.com
Re: Documentation for building with meson
On Thu, Oct 27, 2022 at 1:04 AM John Naylor
<john.naylor@enterprisedb.com> wrote:
This does not work for me in a fresh install until running
meson test --suite setup
In fact, we see in
https://wiki.postgresql.org/wiki/Meson
meson test --suite setup --suite main
(Is there a way to declare a dependency on the setup suite in Meson,
so that we don't have to specify it manually? I was bitten by this
recently; if you make a code change and forget to run setup, it'll
recompile locally but then skip reinstallation, giving false test
results.)
--Jacob
Re: Documentation for building with meson
Hi,
On 2022-10-27 14:15:32 -0700, Jacob Champion wrote:
On Thu, Oct 27, 2022 at 1:04 AM John Naylor
<john.naylor@enterprisedb.com> wrote:This does not work for me in a fresh install until running
meson test --suite setup
In fact, we see in
https://wiki.postgresql.org/wiki/Meson
meson test --suite setup --suite main
(Is there a way to declare a dependency on the setup suite in Meson,
so that we don't have to specify it manually? I was bitten by this
recently; if you make a code change and forget to run setup, it'll
recompile locally but then skip reinstallation, giving false test
results.)
Tests can have dependencies, and they're correctly built. The problem however
is that, for historical reasons if I understand correctly, dependencies of
tests are automatically included in the default 'all' target. Which means if
you just type in 'ninja', it'd automatically create the test installation -
which is probably not what we want, given that that's not a fast step on some
platforms.
Greetings,
Andres Freund
Re: Documentation for building with meson
On Thu, Oct 27, 2022 at 4:03 PM Andres Freund <andres@anarazel.de> wrote:
Tests can have dependencies, and they're correctly built. The problem however
is that, for historical reasons if I understand correctly, dependencies of
tests are automatically included in the default 'all' target. Which means if
you just type in 'ninja', it'd automatically create the test installation -
which is probably not what we want, given that that's not a fast step on some
platforms.
And I see that between-suite dependencies were rejected as a feature
[1]: https://github.com/mesonbuild/meson/issues/2740
Thanks!
--Jacob
Re: Documentation for building with meson
Hi,
On Thu, Oct 27, 2022 at 1:04 AM John Naylor <john.naylor@enterprisedb.com>
wrote:
+# Run the main pg_regress and isolation tests +<userinput>meson test --suite main</userinput>This does not work for me in a fresh install until running
meson test --suite setup
In fact, we see in
https://wiki.postgresql.org/wiki/Meson
meson test --suite setup --suite main
You are right that this will be needed for a new install. I've added
--suite setup in the testing section in the v3 of the patch (attached).
That was just an eyeball check from a naive user -- it would be good to
try running everything documented here.
I retried all the instructions as suggested and they work for me.
Regards,
Samay
Show quoted text
--
John Naylor
EDB: http://www.enterprisedb.com
Attachments:
v3-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v3-0001-Add-docs-for-building-with-meson.patchDownload
From 58936eef2040244d9e6ccf15868d8da7697351b4 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v3] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1631 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1591 insertions(+), 49 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..cd45a22c32 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the <productname>Git</productname> version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -237,7 +266,7 @@ su - postgres
can download an add-on package from <ulink
url="https://www.gnu.org/software/gettext/"></ulink>.
If you are using the <application>Gettext</application> implementation in
- the <acronym>GNU</acronym> C library then you will additionally
+ the <acronym>GNU</acronym> C library, then you will additionally
need the <productname>GNU Gettext</productname> package for some
utility programs. For any of the other implementations you will
not need it.
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1553 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <application>pip</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.35 or later and
+ <application>Bison</application> 2.3 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and
+ is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>LZ4</productname>, if you want to support
+ compression of data with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>Zstandard</productname>, if you want to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library, then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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:
+
+<screen>
+#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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename>. The actual
+ files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>, which
+ normally means <filename>/usr/local/pgsql/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various <productname>PostgreSQL</productname> features that are not
+ built by default. Most of these are non-default only because they
+ require additional software, as described in
+ <xref linkend="install-requirements-meson"/>. To specify PostgreSQL
+ specific options, the name of the option should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ 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 an implementation of the
+ <application>Gettext API</application> is found.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the TCL version to use when building PL/Tcl.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ This requires the <productname>ICU4C</productname> package
+ to be installed. The minimum required version
+ of <productname>ICU4C</productname> is currently 4.2.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </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.
+ <!-- Add description for older ICU4C versions and when pkg-config isn't available-->
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$major-$minor</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>.
+ <!--Add substitute fo LLVM_CONFIG when llvm-config is not in PATH-->
+ </para>
+
+ <para>
+ <productname>LLVM</productname> support requires a compatible
+ <command>clang</command> compiler (specified, if necessary, using the
+ <envar>CLANG</envar> environment variable), and a working C++
+ compiler (specified, if necessary, using the <envar>CXX</envar>
+ environment variable).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ <filename>configure</filename> will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>-Dextra_include_dirs</option> and <option>-Dextra_lib_dirs</option> in
+ addition to this option. <filename>meson configure</filename> 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 dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. <filename>configure</filename> will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding. It defaults to auto, meaning that it will be enabled automatically
+ if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto, meaning that it
+ will be enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ 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 use this option.
+ It defaults to auto, meaning that it will be enabled automatically if the
+ required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the ussp module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD, NetBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 dependencies are found.
+ </para>
+
+ <para>
+ To detect the required compiler and linker options, PostgreSQL will
+ query <command>pkg-config</command>, if that is installed and knows
+ about libxml2. Otherwise the program <command>xml2-config</command>,
+ which is installed by libxml2, will be used if it is found. Use
+ of <command>pkg-config</command> is preferred, because it can deal
+ with multi-architecture installations better.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option enables
+ command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false, that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enables use of the <application>Zlib</application> library.
+ This enables
+ support for compressed archives in <application>pg_dump</application>
+ ,<application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
+ It defaults to auto, meaning that it will be
+ enabled automatically if the required dependencies are found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<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>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include:/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<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>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib:/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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 <productname>Git</productname>
+ 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>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ If a program required to build Postgres (with or without optional
+ flags) is stored at a non-standard path, you could specify it
+ manually to meson configure. The complete list of programs for which
+ this is supported can be found by running <literal>meson configure</literal>.
+ An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ 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, debug, debugoptimized
+ and release. More information about them can be found in the
+ <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">
+ meson documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--errorlogs</option></term>
+ <listitem>
+ <para>
+ This option can be used to print the logs from the failing tests
+ making debugging easier.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ environment variable <envar>DTRACE</envar> can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step,
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other than ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once Postgres is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases,
+ but if you'd like to use more options, you could also use
+ <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and its options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run a specific test
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+# Run the main pg_regress and isolation tests
+<userinput>meson test --suite setup --suite main</userinput>
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results,
+ you can refer to the documentation.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3711,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e5d622d514..bfd52e7b23 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7115,7 +7115,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
Hi,
On 2022-10-30 20:51:59 -0700, samay sharma wrote:
+# setup and enter build directory (done only first time) +meson setup build src --prefix=$PWD/install
This command won't work on windows, I think.
+ <sect2 id="configure-meson"> + <title>Configuring the build</title> + + <para> + The first step of the installation procedure is to configure the + source tree for your system and choose the options you would like. To
s/source tree/build tree/?
+ create and configure the build directory, you can start with the + <literal>meson setup</literal> command. + </para> + +<screen> +<userinput>meson setup build</userinput> +</screen> + + <para> + The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal> + argument. If no <literal>srcdir</literal> is given, Meson will deduce the + <literal>srcdir</literal> based on the current directory and the location + of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory. + </para> + + <para> + 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:
Somehow the "tone" is descriptive in a distanced way, rather than instructing
what to do.
+ <sect3 id="configure-install-locations"> + <title>Installation Locations</title> + + <para> + These options control where <literal>ninja install (or meson install)</literal> will put + the files. The <option>--prefix</option> option is sufficient for + most cases.
Perhaps the short version use of prefix could be a link here? Not sure if
that's a good idea.
+ <variablelist> + <varlistentry> + <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term> + <listitem> + <para> + Install all files under the directory <replaceable>PREFIX</replaceable> + instead of <filename>/usr/local/pgsql</filename>. The actual + files will be installed into various subdirectories; no files + will ever be installed directly into the + <replaceable>PREFIX</replaceable> directory. + </para> + </listitem> + </varlistentry>
Hm, need to mention windows here likely. By default the installation will go
to <current drive letter>:/usr/local/pgsql.
+ <varlistentry> + <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term> + <listitem> + <para> + Specifies the directory for executable programs. The default + is <filename><replaceable>PREFIX</replaceable>/bin</filename>, which + normally means <filename>/usr/local/pgsql/bin</filename>. + </para> + </listitem> + </varlistentry>
Hm, do we really want the "which normally means" part? That'll make the OS
stuff more complicated.
+ <varlistentry> + <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term> + <listitem> + <para> + Sets the directory for various configuration files, + <filename><replaceable>PREFIX</replaceable>/etc</filename> by default. + </para> + </listitem> + </varlistentry>
Need to check what windows does here.
+ <varlistentry> + <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
Wonder if we should define a entity for
<replaceable>auto/enabled/disabled</replaceable>? There's a lot of repetitions
of it.
+ <listitem> + <para> + Enables or disables Native Language Support (<acronym>NLS</acronym>), + 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 an implementation of the + <application>Gettext API</application> is found. + </para>
Do we really want to repeat the "It defaults to auto, meaning that it will be
enabled automatically if ..." for each of these? Perhaps we could say
'defaults to <xref ...>auto</xref>'?
+ <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. + <!-- Add description for older ICU4C versions and when pkg-config isn't available--> + </para>
I'd just remove this paragraph. Right now the meson build will just use solely
use pkg-config config files for icu. I don't think we need to care about 4.6
(from 2010) anymore.
+ <varlistentry id="configure-with-llvm-meson"> + <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term> + <listitem> + <para> + Build with support for <productname>LLVM</productname> based + <acronym>JIT</acronym> compilation<phrase + condition="standalone-ignore"> (see <xref + linkend="jit"/>)</phrase>. This + requires the <productname>LLVM</productname> library to be installed. + The minimum required version of <productname>LLVM</productname> is + currently 3.9. It is set to disabled by default. + </para> + <para> + <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm> + will be used to find the required compilation options. + <command>llvm-config</command>, and then + <command>llvm-config-$major-$minor</command> for all supported + versions, will be searched for in your <envar>PATH</envar>. + <!--Add substitute fo LLVM_CONFIG when llvm-config is not in PATH--> + </para>
Probably a link to the docs for meson native files suffices here for
now. Since the autoconf docs have been written there's only
llvm-config-$version, llvm stopped having separate major/minor versions
somewhere around llvm 4. I think it'd suffice to say llvm-config-$version?
+ <para> + <productname>LLVM</productname> support requires a compatible + <command>clang</command> compiler (specified, if necessary, using the + <envar>CLANG</envar> environment variable), and a working C++ + compiler (specified, if necessary, using the <envar>CXX</envar> + environment variable). + </para>
For clang we don't look for CLANG anymore, we use for the clang compiler
belonging to the llvm installation of llvm-config.
+ <listitem> + <para> + Build with support for <acronym>SSL</acronym> (encrypted) + connections. The only <replaceable>LIBRARY</replaceable> + supported is <option>openssl</option>. This requires the + <productname>OpenSSL</productname> package to be installed. + <filename>configure</filename> will check for the required
The <filename>configure</filename> reference is out of date.
+ header files and libraries to make sure that your + <productname>OpenSSL</productname> installation is sufficient + before proceeding. The default for this option is none. + </para> + </listitem> + </varlistentry>
+ <varlistentry> + <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term> + <listitem> + <para> + 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>-Dextra_include_dirs</option> and <option>-Dextra_lib_dirs</option> in + addition to this option. <filename>meson configure</filename> 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 dependencies are found. + </para> + </listitem> + </varlistentry>
Right now we only work for gssapi installations providing a pkg-config config
file. We could change that if we encounter a system where that's insufficient.
+ <varlistentry> + <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term> + <listitem> + <para> + Build the <xref linkend="uuid-ossp"/> module + (which provides functions to generate UUIDs), using the specified + UUID library.<indexterm><primary>UUID</primary></indexterm> + <replaceable>LIBRARY</replaceable> must be one of: + </para> + <itemizedlist> + <listitem> + <para> + <option>none</option> to not build the ussp module. This is the default. + </para> + </listitem>
s/ussp/uuid/?
+ <para> + To detect the required compiler and linker options, PostgreSQL will + query <command>pkg-config</command>, if that is installed and knows + about libxml2. Otherwise the program <command>xml2-config</command>, + which is installed by libxml2, will be used if it is found. Use + of <command>pkg-config</command> is preferred, because it can deal + with multi-architecture installations better. + </para>
Right now only pkg-config is supported with meson.
+ + <varlistentry> + <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term> + <listitem> + <para> + This option is set to true by default; setting it to false will + 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 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 <productname>PostgreSQL</productname> on + your platform, please report the problem to the + <productname>PostgreSQL</productname> developers. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-Datomics=<replaceable>true/false</replaceable></option></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + </variablelist>
I think these should rather be in the developer section? They're not
dependencies and as you noted, they're not normally useful.
+ <varlistentry> + <term><option>-Dextra_include_dirs=<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>-Dextra_lib_dirs</option> option. + </para> + <para> + Example: <literal>-Dextra_include_dirs=/opt/gnu/include:/usr/sup/include</literal>. + </para> + </listitem> + </varlistentry>
The separator for meson is a comma, rather than a :
+ <varlistentry> + <term><option>-Dextra_lib_dirs=<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>-Dextra_include_dirs</option> option) if you have packages + installed in non-standard locations. + </para> + <para> + Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib:/usr/sup/lib</literal>. + </para> + </listitem> + </varlistentry>
Dito.
+ <variablelist> + + <varlistentry> + <term><option>-Dsegsize=<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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-Dblocksize=<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). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-Dwal_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). + </para> + </listitem> + </varlistentry> + + </variablelist>
The order of the list entries seems a bit random? Perhaps just go for
alphabetical?
+ </sect3> + + <sect3 id="configure-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>--debug</option>, which can be useful to enable + detailed bug reports in the unlucky event that you encounter a bug. + On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option> + and <option>-Dcassert</option> options. + </para> + + <variablelist> + <varlistentry> + <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term> + <listitem> + <para> + 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, debug, debugoptimized + and release. More information about them can be found in the + <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory"> + meson documentation</ulink>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--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> + + <varlistentry> + <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term> + <listitem> + <para> + Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}. + </para> + </listitem> + </varlistentry>
Wonder if we should just document optimization and debug, rather than
buildtype. The fact that debug/optimization override buildtype is a bit
confusing.
+ <varlistentry> + <term><option>-Dtap-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>
This is an auto option as well.
+ <varlistentry> + <term><option>--errorlogs</option></term> + <listitem> + <para> + This option can be used to print the logs from the failing tests + making debugging easier. + </para> + </listitem> + </varlistentry>
I don't think it's worth documenting this, it defaults to true anyway.
+ <para> + To point to the <command>dtrace</command> program, the + environment variable <envar>DTRACE</envar> can be set. This + will often be necessary because <command>dtrace</command> is + typically installed under <filename>/usr/sbin</filename>, + which might not be in your <envar>PATH</envar>. + </para>
We don't read the DTRACE environment variable, but the DTRACE option.
+ <para> + <literal>ninja install</literal> should work for most cases, + but if you'd like to use more options, you could also use + <literal>meson install</literal> instead. You can learn more about + <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink> + and its options in the meson documentation. + </para>
Maybe we should mention meson --quiet here? The verbosity of ninja install is
a bit annoying.
+# Run the main pg_regress and isolation tests +<userinput>meson test --suite setup --suite main</userinput>
Since yesterday the main suite is no more. There's 'regress' and 'isolation'
now.
Greetings,
Andres Freund
Re: Documentation for building with meson
Hi,
On Sat, Nov 5, 2022 at 2:39 PM Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2022-10-30 20:51:59 -0700, samay sharma wrote:
+# setup and enter build directory (done only first time) +meson setup build src --prefix=$PWD/installThis command won't work on windows, I think.
I'll submit another version after testing on windows and seeing what else
we need to fix. I've addressed all the other feedback in the attached v4.
+ <sect2 id="configure-meson"> + <title>Configuring the build</title> + + <para> + The first step of the installation procedure is to configure the + source tree for your system and choose the options you would like.To
s/source tree/build tree/?
Done
+ create and configure the build directory, you can start with the + <literal>meson setup</literal> command. + </para> + +<screen> +<userinput>meson setup build</userinput> +</screen> + + <para> + The setup command takes a <literal>builddir</literal> and a<literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will
deduce the
+ <literal>srcdir</literal> based on the current directory and the
location
+ of <literal>meson.build</literal>. The <literal>builddir</literal>
is mandatory.
+ </para> + + <para> + Meson then loads the build configuration file and sets up the builddirectory.
+ 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:
Somehow the "tone" is descriptive in a distanced way, rather than
instructing
what to do.
This was mostly copy pasted from meson docs. Rewrote it to make briefer and
changed the tone to be more conversational.
+ <sect3 id="configure-install-locations"> + <title>Installation Locations</title> + + <para> + These options control where <literal>ninja install (or mesoninstall)</literal> will put
+ the files. The <option>--prefix</option> option is sufficient for + most cases.Perhaps the short version use of prefix could be a link here? Not sure if
that's a good idea.
Added as an example
+ <variablelist> + <varlistentry> +<term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem> + <para> + Install all files under the directory<replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename>. The actual + files will be installed into various subdirectories; no files + will ever be installed directly into the + <replaceable>PREFIX</replaceable> directory. + </para> + </listitem> + </varlistentry>Hm, need to mention windows here likely. By default the installation will
go
to <current drive letter>:/usr/local/pgsql.+ <varlistentry>
+<term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem> + <para> + Specifies the directory for executable programs. The default + is <filename><replaceable>PREFIX</replaceable>/bin</filename>,which
+ normally means <filename>/usr/local/pgsql/bin</filename>. + </para> + </listitem> + </varlistentry>Hm, do we really want the "which normally means" part? That'll make the OS
stuff more complicated.
Removed. We mention what the default is in the description of PREFIX, so it
shouldn't be needed anyway.
+ <varlistentry>
+<term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem> + <para> + Sets the directory for various configuration files, + <filename><replaceable>PREFIX</replaceable>/etc</filename> bydefault.
+ </para> + </listitem> + </varlistentry>Need to check what windows does here.
+ <varlistentry>
+<term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
Wonder if we should define a entity for
<replaceable>auto/enabled/disabled</replaceable>? There's a lot of
repetitions
of it.
I couldn't come up with a good entity name which is significantly shorter.
I think it's probably fine to have this as it clearly tells you the
possible values you can set it to. I'll remove repetitive descriptions of
what they mean.
+ <listitem> + <para> + Enables or disables Native Language Support(<acronym>NLS</acronym>),
+ that is, the ability to display a program's messages in a + language other than English. It defaults to auto, meaning thatit
+ will be enabled automatically if an implementation of the + <application>Gettext API</application> is found. + </para>Do we really want to repeat the "It defaults to auto, meaning that it will
be
enabled automatically if ..." for each of these? Perhaps we could say
'defaults to <xref ...>auto</xref>'?
I added a description to the beginning of the Postgres features section and
removed the repetitive "enabled automatically if ....".
+ <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 andlater.
+ <!-- Add description for older ICU4C versions and when
pkg-config isn't available-->
+ </para>
I'd just remove this paragraph. Right now the meson build will just use
solely
use pkg-config config files for icu. I don't think we need to care about
4.6
(from 2010) anymore.
Removed
+ <varlistentry id="configure-with-llvm-meson"> +<term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem> + <para> + Build with support for <productname>LLVM</productname> based + <acronym>JIT</acronym> compilation<phrase + condition="standalone-ignore"> (see <xref + linkend="jit"/>)</phrase>. This + requires the <productname>LLVM</productname> library to beinstalled.
+ The minimum required version of
<productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default. + </para> + <para> +<command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options. + <command>llvm-config</command>, and then + <command>llvm-config-$major-$minor</command> for all supported + versions, will be searched for in your <envar>PATH</envar>. + <!--Add substitute fo LLVM_CONFIG when llvm-config is not inPATH-->
+ </para>
Probably a link to the docs for meson native files suffices here for
now. Since the autoconf docs have been written there's only
llvm-config-$version, llvm stopped having separate major/minor versions
somewhere around llvm 4. I think it'd suffice to say llvm-config-$version?
LLVM_CONFIG is now supported by newer versions of meson
https://github.com/mesonbuild/meson/pull/10757. So, will just ask users to
use that?
Changed to llvm-config-$version
+ <para> + <productname>LLVM</productname> support requires a compatible + <command>clang</command> compiler (specified, if necessary,using the
+ <envar>CLANG</envar> environment variable), and a working C++ + compiler (specified, if necessary, using the <envar>CXX</envar> + environment variable). + </para>For clang we don't look for CLANG anymore, we use for the clang compiler
belonging to the llvm installation of llvm-config.
Removed the paragraph.
+ <listitem> + <para> + Build with support for <acronym>SSL</acronym> (encrypted) + connections. The only <replaceable>LIBRARY</replaceable> + supported is <option>openssl</option>. This requires the + <productname>OpenSSL</productname> package to be installed. + <filename>configure</filename> will check for the requiredThe <filename>configure</filename> reference is out of date.
Removed.
+ header files and libraries to make sure that your + <productname>OpenSSL</productname> installation is sufficient + before proceeding. The default for this option is none. + </para> + </listitem> + </varlistentry>+ <varlistentry>
+<term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem> + <para> + 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>-Dextra_include_dirs</option> and<option>-Dextra_lib_dirs</option> in
+ addition to this option. <filename>meson configure</filename>
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 enabledautomatically if the
+ required dependencies are found. + </para> + </listitem> + </varlistentry>Right now we only work for gssapi installations providing a pkg-config
config
file. We could change that if we encounter a system where that's
insufficient.
Changed to use pkg-config for non-standard paths.
+ <varlistentry>
+<term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem> + <para> + Build the <xref linkend="uuid-ossp"/> module + (which provides functions to generate UUIDs), using thespecified
+ UUID library.<indexterm><primary>UUID</primary></indexterm> + <replaceable>LIBRARY</replaceable> must be one of: + </para> + <itemizedlist> + <listitem> + <para> + <option>none</option> to not build the ussp module. This isthe default.
+ </para>
+ </listitem>s/ussp/uuid/?
Changed.
+ <para> + To detect the required compiler and linker options, PostgreSQLwill
+ query <command>pkg-config</command>, if that is installed and
knows
+ about libxml2. Otherwise the program
<command>xml2-config</command>,
+ which is installed by libxml2, will be used if it is found.
Use
+ of <command>pkg-config</command> is preferred, because it can
deal
+ with multi-architecture installations better. + </para>Right now only pkg-config is supported with meson.
Removed the paragraph and only left " To use a libxml2 installation that is
in an unusual location, you can set <command>pkg-config</command>-related
environment variables (see its documentation)."
+ + <varlistentry> +<term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem> + <para> + This option is set to true by default; setting it to false will + 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 very poor performance;therefore,
+ this option should only be changed if the build aborts and + informs you that the platform lacks spinlock support. Ifsetting this
+ option to false 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>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem> + <para> + This option is set to true by default; setting it to false will + disable use of CPU atomic operations. The option does nothingon
+ 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.
+ </para> + </listitem> + </varlistentry> + </variablelist>I think these should rather be in the developer section? They're not
dependencies and as you noted, they're not normally useful.
Makes sense. Moved.
+ <varlistentry>
+<term><option>-Dextra_include_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem> + <para> + <replaceable>DIRECTORIES</replaceable> is a colon-separatedlist 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 ina non-standard
+ location, + you have to use this option and probably also the corresponding + <option>-Dextra_lib_dirs</option> option. + </para> + <para> + Example:<literal>-Dextra_include_dirs=/opt/gnu/include:/usr/sup/include</literal>.
+ </para> + </listitem> + </varlistentry>The separator for meson is a comma, rather than a :
Changed.
+ <varlistentry>
+<term><option>-Dextra_lib_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem> + <para> + <replaceable>DIRECTORIES</replaceable> is a colon-separatedlist of
+ directories to search for libraries. You will probably have + to use this option (and the corresponding + <option>-Dextra_include_dirs</option> option) if you havepackages
+ installed in non-standard locations. + </para> + <para> + Example:<literal>-Dextra_lib_dirs=/opt/gnu/lib:/usr/sup/lib</literal>.
+ </para> + </listitem> + </varlistentry>Dito.
Changed.
+ <variablelist> + + <varlistentry> +<term><option>-Dsegsize=<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 thisvalue
+ be a power of 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> +<term><option>-Dblocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
+ <listitem> + <para> + Set the <firstterm>block size</firstterm>, in kilobytes. Thisis 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). + </para> + </listitem> + </varlistentry> + + <varlistentry> +<term><option>-Dwal_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). + </para> + </listitem> + </varlistentry> + + </variablelist>The order of the list entries seems a bit random? Perhaps just go for
alphabetical?
Done
+ </sect3> + + <sect3 id="configure-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>--debug</option>, which can be useful to enable + detailed bug reports in the unlucky event that you encounter a bug. + On platforms supporting DTrace, <option>-Ddtrace</option> + may also be reasonable to use in production. + </para> + + <para> + When building an installation that will be used to develop codeinside
+ the server, it is recommended to use at least the
<option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options. + </para> + + <variablelist> + <varlistentry> +<term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem> + <para> + 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, debug,debugoptimized
+ and release. More information about them can be found in the + <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory
">+ meson documentation</ulink>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--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 developmentwork
+ or running a beta version. + </para> + </listitem> + </varlistentry> + + <varlistentry> +<term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem> + <para> + Specify the optimization level. LEVEL can be set to any of{0,g,1,2,3,s}.
+ </para> + </listitem> + </varlistentry>Wonder if we should just document optimization and debug, rather than
buildtype. The fact that debug/optimization override buildtype is a bit
confusing.
Yes, it was a bit confusing which is why I ended up documenting them as
well. Not sure about doing just the debug / optimization as buildtype is
likely a useful shorthand. I've kept as is for now but if you feel strongly
about documenting only one of the two, I can remove.
+ <varlistentry> + <term><option>-Dtap-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 <xreflinkend="regress-tap"/> for more information.</phrase>
+ </para> + </listitem> + </varlistentry>This is an auto option as well.
Fixed.
+ <varlistentry> + <term><option>--errorlogs</option></term> + <listitem> + <para> + This option can be used to print the logs from the failing tests + making debugging easier. + </para> + </listitem> + </varlistentry>I don't think it's worth documenting this, it defaults to true anyway.
Makes sense. Removed.
+ <para> + To point to the <command>dtrace</command> program, the + environment variable <envar>DTRACE</envar> can be set. This + will often be necessary because <command>dtrace</command> is + typically installed under <filename>/usr/sbin</filename>, + which might not be in your <envar>PATH</envar>. + </para>We don't read the DTRACE environment variable, but the DTRACE option.
Good catch. Changed.
+ <para> + <literal>ninja install</literal> should work for most cases, + but if you'd like to use more options, you could also use + <literal>meson install</literal> instead. You can learn more about + <ulink url="https://mesonbuild.com/Commands.html#install">mesoninstall</ulink>
+ and its options in the meson documentation. + </para>Maybe we should mention meson --quiet here? The verbosity of ninja install
is
a bit annoying.
Done
+# Run the main pg_regress and isolation tests +<userinput>meson test --suite setup --suite main</userinput>Since yesterday the main suite is no more. There's 'regress' and
'isolation'
now.
Changed
Regards,
Samay
Show quoted text
Greetings,
Andres Freund
Attachments:
v4-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v4-0001-Add-docs-for-building-with-meson.patchDownload
From 1a06b6adaf1c939d4329280a0442c2ae07865a72 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v4] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1583 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1543 insertions(+), 49 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..23219a3205 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the <productname>Git</productname> version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -237,7 +266,7 @@ su - postgres
can download an add-on package from <ulink
url="https://www.gnu.org/software/gettext/"></ulink>.
If you are using the <application>Gettext</application> implementation in
- the <acronym>GNU</acronym> C library then you will additionally
+ the <acronym>GNU</acronym> C library, then you will additionally
need the <productname>GNU Gettext</productname> package for some
utility programs. For any of the other implementations you will
not need it.
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1505 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <application>pip</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.35 or later and
+ <application>Bison</application> 2.3 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and
+ is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>LZ4</productname>, if you want to support
+ compression of data with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>Zstandard</productname>, if you want to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library, then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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 ones are mentioned in the subsequent sections. For example:
+
+<screen>
+#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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> option (example
+ <xref linkend="install-short-meson"/>) 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename>. The actual
+ files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various optional <productname>PostgreSQL</productname> features.
+ Most of these require additional software, as described in
+ <xref linkend="install-requirements-meson"/>, and are set to be auto
+ features. This means that they will be automatically enabled if the
+ required software is found. You can change this behavior by manually
+ setting the auto features to <literal>enabled</literal> to require them
+ or <literal>disabled</literal> to not build with them.
+ </para>
+
+ <para>
+ To specify PostgreSQL specific options, the name of the option
+ should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ that is, the ability to display a program's messages in a
+ language other than English. It defaults to auto and will be enabled
+ automatically if an implementation of the <application>Gettext API</application> is found.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the TCL version to use when building PL/Tcl.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ It defaults to auto and 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 id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$version</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>. If
+ that would not yield the desired program,
+ use <envar>LLVM_CONFIG</envar> to specify a path to the
+ correct <command>llvm-config</command>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ Building with this will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>). In those cases, PostgreSQL will
+ query <command>pkg-config</command> to detect the required compiler
+ and linker options. It defaults to auto and <filename>meson 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>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. It defults to auto and <filename>meson configure</filename>
+ will check for the required header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with BSD Authentication support. (The BSD Authentication framework is
+ currently only available on OpenBSD.) It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ is started under <application>systemd</application> but has no impact
+ otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
+ information</phrase>. It defaults to auto and <application>libsystemd</application> and the
+ associated header files need to be installed to use this option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for Bonjour automatic service discovery.
+ It defaults to auto and requires Bonjour support in your operating system.
+ Recommended on macOS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the uuid module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD, NetBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxml2, enabling SQL/XML support. It defaults to auto and Libxml2
+ version 2.6.23 or later is required for this feature.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option defaults to auto
+ and enables command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false, that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enables use of the <application>Zlib</application> library.
+ It defaults to auto and enables
+ support for compressed archives in <application>pg_dump</application>
+ ,<application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> 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 <application>Readline</application>) installed in a non-standard
+ location,
+ you have to use this option and probably also the corresponding
+ <option>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include,/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> is a comma-separated list of
+ directories to search for libraries. You will probably have
+ to use this option (and the corresponding
+ <option>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib,/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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 <productname>Git</productname>
+ 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>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ If a program required to build Postgres (with or without optional
+ flags) is stored at a non-standard path, you could specify it
+ manually to meson configure. The complete list of programs for which
+ this is supported can be found by running <literal>meson configure</literal>.
+ An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ 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, debug, debugoptimized
+ and release. More information about them can be found in the
+ <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">
+ meson documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-tests=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable tests using the Perl TAP tools. This is set to auto and 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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ <option>DTRACE</option> option can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step,
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other than ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once Postgres is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases,
+ but if you'd like to use more options (like --quiet to suppress extra output),
+ you could also use <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and its options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run a specific test
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+# Run the pg_regress tests
+<userinput>meson test --suite setup --suite regress</userinput>
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results,
+ you can refer to the documentation.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3663,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e5d622d514..bfd52e7b23 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7115,7 +7115,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
Hi,
I did some tests on windows. I used 'ninja' as a backend.
On 11/8/2022 9:23 PM, samay sharma wrote:
Hi,
On Sat, Nov 5, 2022 at 2:39 PM Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2022-10-30 20:51:59 -0700, samay sharma wrote:
+# setup and enter build directory (done only first time) +meson setup build src --prefix=$PWD/installThis command won't work on windows, I think.
Yes, $PWD isn't recognized on windows, %CD% could be alternative.
+ <varlistentry>
+<term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem> + <para> + Sets the directory for various configuration files, + <filename><replaceable>PREFIX</replaceable>/etc</filename> bydefault.
+ </para> + </listitem> + </varlistentry>Need to check what windows does here.
It is same on windows: 'PREFIX/etc'.
I also checked other dirs(bindir, sysconfdir, libdir, includedir,
datadir, localedir, mandir), default path is correct for all of them.
Regards,
Nazir Bilal Yavuz
Re: Documentation for building with meson
Hi,
On Thu, Nov 10, 2022 at 4:46 AM Nazir Bilal Yavuz <byavuz81@gmail.com>
wrote:
Hi,
I did some tests on windows. I used 'ninja' as a backend.
On 11/8/2022 9:23 PM, samay sharma wrote:Hi,
On Sat, Nov 5, 2022 at 2:39 PM Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2022-10-30 20:51:59 -0700, samay sharma wrote:
+# setup and enter build directory (done only first time) +meson setup build src --prefix=$PWD/installThis command won't work on windows, I think.
Yes, $PWD isn't recognized on windows, %CD% could be alternative.
Added.
+ <varlistentry>
+
<term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem> + <para> + Sets the directory for various configuration files, + <filename><replaceable>PREFIX</replaceable>/etc</filename> bydefault.
+ </para> + </listitem> + </varlistentry>Need to check what windows does here.
It is same on windows: 'PREFIX/etc'.
I also checked other dirs(bindir, sysconfdir, libdir, includedir, datadir,
localedir, mandir), default path is correct for all of them.
Thanks. I've made a few windows specific fixes in the latest version.
Attached v5.
Regards,
Samay
Show quoted text
Regards,
Nazir Bilal Yavuz
Attachments:
v5-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v5-0001-Add-docs-for-building-with-meson.patchDownload
From 9a9bf419fbf3876b0ab67cb95ca04032f1efb813 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v5] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1590 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1550 insertions(+), 49 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..afbea1574a 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the <productname>Git</productname> version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -237,7 +266,7 @@ su - postgres
can download an add-on package from <ulink
url="https://www.gnu.org/software/gettext/"></ulink>.
If you are using the <application>Gettext</application> implementation in
- the <acronym>GNU</acronym> C library then you will additionally
+ the <acronym>GNU</acronym> C library, then you will additionally
need the <productname>GNU Gettext</productname> package for some
utility programs. For any of the other implementations you will
not need it.
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1512 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.git src
+
+# setup and enter build directory (done only first time)
+## Unix based platforms
+meson setup build src --prefix=$PWD/install
+
+## Windows
+meson setup build src --prefix=%cd%/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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <application>pip</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.35 or later and
+ <application>Bison</application> 2.3 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and
+ is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>LZ4</productname>, if you want to support
+ compression of data with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <productname>Zstandard</productname>, if you want to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library, then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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 ones are mentioned in the subsequent sections. For example:
+
+<screen>
+#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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> option (example
+ <xref linkend="install-short-meson"/>) 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename> (on Unix based systems) or
+ <filename>current drive letter:/usr/local/pgsql</filename> (on Windows).
+ The actual files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various optional <productname>PostgreSQL</productname> features.
+ Most of these require additional software, as described in
+ <xref linkend="install-requirements-meson"/>, and are set to be auto
+ features. This means that they will be automatically enabled if the
+ required software is found. You can change this behavior by manually
+ setting the auto features to <literal>enabled</literal> to require them
+ or <literal>disabled</literal> to not build with them.
+ </para>
+
+ <para>
+ To specify PostgreSQL specific options, the name of the option
+ should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ that is, the ability to display a program's messages in a
+ language other than English. It defaults to auto and will be enabled
+ automatically if an implementation of the <application>Gettext API</application> is found.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the TCL version to use when building PL/Tcl.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ It defaults to auto and 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 id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$version</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>. If
+ that would not yield the desired program,
+ use <envar>LLVM_CONFIG</envar> to specify a path to the
+ correct <command>llvm-config</command>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ Building with this will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>). In those cases, PostgreSQL will
+ query <command>pkg-config</command> to detect the required compiler
+ and linker options. It defaults to auto and <filename>meson 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>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. It defults to auto and <filename>meson configure</filename>
+ will check for the required header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with BSD Authentication support. (The BSD Authentication framework is
+ currently only available on OpenBSD.) It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ is started under <application>systemd</application> but has no impact
+ otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
+ information</phrase>. It defaults to auto and <application>libsystemd</application> and the
+ associated header files need to be installed to use this option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for Bonjour automatic service discovery.
+ It defaults to auto and requires Bonjour support in your operating system.
+ Recommended on macOS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the uuid module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD, NetBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxml2, enabling SQL/XML support. It defaults to auto and Libxml2
+ version 2.6.23 or later is required for this feature.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option defaults to auto
+ and enables command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false, that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enables use of the <application>Zlib</application> library.
+ It defaults to auto and enables
+ support for compressed archives in <application>pg_dump</application>
+ ,<application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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 <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> 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 <application>Readline</application>) installed in a non-standard
+ location,
+ you have to use this option and probably also the corresponding
+ <option>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include,/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> is a comma-separated list of
+ directories to search for libraries. You will probably have
+ to use this option (and the corresponding
+ <option>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib,/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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 <productname>Git</productname>
+ 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>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ If a program required to build Postgres (with or without optional
+ flags) is stored at a non-standard path, you could specify it
+ manually to meson configure. The complete list of programs for which
+ this is supported can be found by running <literal>meson configure</literal>.
+ An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ 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, debug, debugoptimized
+ and release. More information about them can be found in the
+ <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">
+ meson documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. LEVEL can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-tests=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable tests using the Perl TAP tools. This is set to auto and 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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ <option>DTRACE</option> option can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step,
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other than ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once Postgres is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases,
+ but if you'd like to use more options (like --quiet to suppress extra output),
+ you could also use <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and its options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run the pg_regress tests
+<userinput>meson test --suite setup --suite regress</userinput>
+
+# Run a specific test (might need to run setup suite first)
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results,
+ you can refer to the documentation.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3670,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e5d622d514..bfd52e7b23 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7115,7 +7115,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
2022年10月20日(木) 11:43 Justin Pryzby <pryzby@telsasoft.com>:
On Wed, Oct 19, 2022 at 11:35:10AM -0700, samay sharma wrote:
Creating a new thread focussed on adding docs for building Postgres with
meson. This is a spinoff from the original thread [1] and I've attempted to
address all the feedback provided there in the attached patch.Please let me know your thoughts.
It's easier to review rendered documentation.
I made a rendered copy available here:
https://api.cirrus-ci.com/v1/artifact/task/6084297781149696/html_docs/html_docs/install-meson.html
For reference, are there any instructions anywhere on how to do this? It'd be
useful to be able to provide a link to the latest version of this documentation
(and also document the process for patch authors in general).
Regards
Ian Barwick
Re: Documentation for building with meson
On Wed, Nov 16, 2022 at 10:52:35AM +0900, Ian Lawrence Barwick wrote:
2022年10月20日(木) 11:43 Justin Pryzby <pryzby@telsasoft.com>:
On Wed, Oct 19, 2022 at 11:35:10AM -0700, samay sharma wrote:
Creating a new thread focussed on adding docs for building Postgres with
meson. This is a spinoff from the original thread [1] and I've attempted to
address all the feedback provided there in the attached patch.Please let me know your thoughts.
It's easier to review rendered documentation.
I made a rendered copy available here:
https://api.cirrus-ci.com/v1/artifact/task/6084297781149696/html_docs/html_docs/install-meson.htmlFor reference, are there any instructions anywhere on how to do this? It'd be
useful to be able to provide a link to the latest version of this documentation
(and also document the process for patch authors in general).
I've submitted patches which would do that for every patch (ideally,
excluding patches that don't touch the docs, although it looks like the
"exclusion" isn't working).
https://commitfest.postgresql.org/40/3709/
The most recent patches on that thread don't include the "docs as
artifacts" patch, but only the preparatory "build docs as a separate
task". I think the other part is stalled waiting for some updates to
cfbot to allow knowing how many commits are in the patchset.
FYI, you can navigate from the cirrus task's URL to the git commit (and
its parents)
https://cirrus-ci.com/task/6084297781149696 =>
https://github.com/justinpryzby/postgres/commit/7b57f3323fc77e9b04ef2e76976776090eb8b5b5
--
Justin
Re: Documentation for building with meson
On Mon, Nov 14, 2022 at 10:41:21AM -0800, samay sharma wrote:
You need LZ4, if you want to support compression of data with that
method; see default_toast_compression and wal_compression.
=> The first comma is odd. Maybe it should say "LZ4 is needed to
support .."
You need Zstandard, if you want to support compression of data or
backups with that method; see wal_compression. The minimum required
version is 1.4.0.
Same.
Also, since v15, LZ4 and zstd can both be used by basebackup.
Some commonly used ones are mentioned in the subsequent sections
=> Some commonly used options ...
Most of these require additional software, as described in Section
17.3.2, and are set to be auto features.
=> "Are set to be auto features" sounds odd. I think it should say
something like " .. and are automatically enabled if the required
software is detected.".
You can change this behavior by manually setting the auto features to
enabled to require them or disabled to not build with them.
remove "auto". Maybe "enabled" and "disabled" need markup.
On Windows, the default WinLDAP library is used. It defults to auto
typo: defults
It defaults to auto and libsystemd and the associated header files need
to be installed to use this option.
=> write this as two separate sentences. Same for libxml.
bsd to use the UUID functions found in FreeBSD, NetBSD, and some other
BSD-derived systems
=> should remove mention of netbsd, like c4b6d218e
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.
=> The comma is mis-placed.
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.
=> BACKEND is missing markup.
This option can be used to specify the buildtype to use; defaults to
release
=> release is missing markup
Specify the optimization level. LEVEL can be set to any of
{0,g,1,2,3,s}.
=> LEVEL is missing markup
Thanks,
--
Justin
Re: Documentation for building with meson
Hi,
On Tue, Nov 22, 2022 at 10:36 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
On Mon, Nov 14, 2022 at 10:41:21AM -0800, samay sharma wrote:
You need LZ4, if you want to support compression of data with that
method; see default_toast_compression and wal_compression.=> The first comma is odd. Maybe it should say "LZ4 is needed to
support .."You need Zstandard, if you want to support compression of data or
backups with that method; see wal_compression. The minimum required
version is 1.4.0.Same.
Also, since v15, LZ4 and zstd can both be used by basebackup.
Some commonly used ones are mentioned in the subsequent sections
=> Some commonly used options ...
Most of these require additional software, as described in Section
17.3.2, and are set to be auto features.=> "Are set to be auto features" sounds odd. I think it should say
something like " .. and are automatically enabled if the required
software is detected.".You can change this behavior by manually setting the auto features to
enabled to require them or disabled to not build with them.remove "auto". Maybe "enabled" and "disabled" need markup.
On Windows, the default WinLDAP library is used. It defults to auto
typo: defults
It defaults to auto and libsystemd and the associated header files need
to be installed to use this option.=> write this as two separate sentences. Same for libxml.
bsd to use the UUID functions found in FreeBSD, NetBSD, and some other
BSD-derived systems=> should remove mention of netbsd, like c4b6d218e
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.=> The comma is mis-placed.
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.=> BACKEND is missing markup.
This option can be used to specify the buildtype to use; defaults to
release=> release is missing markup
Specify the optimization level. LEVEL can be set to any of
{0,g,1,2,3,s}.=> LEVEL is missing markup
Thanks for the feedback. Addressed all and added markup at a few more
places in v6 (attached).
Regards,
Samay
Show quoted text
Thanks,
--
Justin
Attachments:
v6-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v6-0001-Add-docs-for-building-with-meson.patchDownload
From 01f12da78e72222da8185e79e637798255649b7f Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v6] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1590 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1550 insertions(+), 49 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..e805bd2a84 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the <productname>Git</productname> version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -237,7 +266,7 @@ su - postgres
can download an add-on package from <ulink
url="https://www.gnu.org/software/gettext/"></ulink>.
If you are using the <application>Gettext</application> implementation in
- the <acronym>GNU</acronym> C library then you will additionally
+ the <acronym>GNU</acronym> C library, then you will additionally
need the <productname>GNU Gettext</productname> package for some
utility programs. For any of the other implementations you will
not need it.
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1512 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.git src
+
+# setup and enter build directory (done only first time)
+## Unix based platforms
+meson setup build src --prefix=$PWD/install
+
+## Windows
+meson setup build src --prefix=%cd%/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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <application>pip</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.35 or later and
+ <application>Bison</application> 2.3 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and
+ is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <productname>LZ4</productname> is needed to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <productname>Zstandard</productname> is needed to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library, then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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:
+
+<screen>
+#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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> option (example
+ <xref linkend="install-short-meson"/>) 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename> (on Unix based systems) or
+ <filename>current drive letter:/usr/local/pgsql</filename> (on Windows).
+ The actual files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various optional <productname>PostgreSQL</productname> features.
+ Most of these require additional software, as described in
+ <xref linkend="install-requirements-meson"/>, and will be automatically enabled if the
+ required software is found. You can change this behavior by manually
+ setting these features to <literal>enabled</literal> to require them
+ or <literal>disabled</literal> to not build with them.
+ </para>
+
+ <para>
+ To specify PostgreSQL specific options, the name of the option
+ should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ that is, the ability to display a program's messages in a
+ language other than English. It defaults to auto and will be enabled
+ automatically if an implementation of the <application>Gettext API</application> is found.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the TCL version to use when building PL/Tcl.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ It defaults to auto and 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 id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$version</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>. If
+ that would not yield the desired program,
+ use <envar>LLVM_CONFIG</envar> to specify a path to the
+ correct <command>llvm-config</command>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ Building with this will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>). In those cases, PostgreSQL will
+ query <command>pkg-config</command> to detect the required compiler
+ and linker options. It defaults to auto and <filename>meson 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>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. It defaults to auto and <filename>meson configure</filename>
+ will check for the required header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with BSD Authentication support. (The BSD Authentication framework is
+ currently only available on OpenBSD.) It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ is started under <application>systemd</application> but has no impact
+ otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
+ information</phrase>. It defaults to auto. <application>libsystemd</application> and the
+ associated header files need to be installed to use this option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for Bonjour automatic service discovery.
+ It defaults to auto and requires Bonjour support in your operating system.
+ Recommended on macOS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the uuid module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxml2, enabling SQL/XML support. It defaults to auto. Libxml2
+ version 2.6.23 or later is required for this feature.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option defaults to auto
+ and enables command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false, that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enables use of the <application>Zlib</application> library.
+ It defaults to auto and enables
+ support for compressed archives in <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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
+ <option>BACKEND</option> to <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> 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 <application>Readline</application>) installed in a non-standard
+ location,
+ you have to use this option and probably also the corresponding
+ <option>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include,/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> is a comma-separated list of
+ directories to search for libraries. You will probably have
+ to use this option (and the corresponding
+ <option>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib,/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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 <productname>Git</productname>
+ 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>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ If a program required to build Postgres (with or without optional
+ flags) is stored at a non-standard path, you could specify it
+ manually to meson configure. The complete list of programs for which
+ this is supported can be found by running <literal>meson configure</literal>.
+ An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to specify the buildtype to use; defaults
+ to <option>release</option>. If you'd like finer control on the debug symbols
+ and optimization levels than what this option provides, you can
+ refer to the <option>--debug</option> and <option>--optimization</option> flags.
+
+ The following build types are generally used: <option>plain</option>,
+ <option>debug</option>, <option>debugoptimized</option> and <option>release</option>.
+ More information about them can be found in the
+ <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">
+ meson documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. <option>LEVEL</option> can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-tests=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable tests using the Perl TAP tools. This is set to auto and 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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>auto/enabled/disabled</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ <option>DTRACE</option> option can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step,
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other than ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once Postgres is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases,
+ but if you'd like to use more options (like --quiet to suppress extra output),
+ you could also use <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and its options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run the pg_regress tests
+<userinput>meson test --suite setup --suite regress</userinput>
+
+# Run a specific test (might need to run setup suite first)
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results,
+ you can refer to the documentation.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3670,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e2426f7210..8d1af92ed2 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7119,7 +7119,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
On Wed, Nov 23, 2022 at 11:30:54AM -0800, samay sharma wrote:
Thanks for the feedback. Addressed all and added markup at a few more
places in v6 (attached).
Thanks. It looks good to me. A couple thoughts, maybe they're not
important.
- LZ4 and Zstd refer to wal_compression and default_toast_compression,
but not to any corresponding option to basebackup.
- There's no space after the hash mark here; but above, there was:
#Setup build directory with a different installation prefix
- You use slash to show enumerated options, but it's more typical to
use braces: {a | b | c}:
-Dnls=auto/enabled/disabled
- There's no earlier description/definition of an "auto" feature, but
still says this:
"Setting this option allows you to override value of all 'auto' features"
- Currently the documentation always refers to "PostgreSQL", but you
added two references to "Postgres":
+ If a program required to build Postgres...
+ Once Postgres is built...--
Justin
Re: Documentation for building with meson
Hi,
On Wed, Nov 23, 2022 at 12:16 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
On Wed, Nov 23, 2022 at 11:30:54AM -0800, samay sharma wrote:
Thanks for the feedback. Addressed all and added markup at a few more
places in v6 (attached).Thanks. It looks good to me. A couple thoughts, maybe they're not
important.
Thank you. Attaching v7 addressing most of the points below.
- LZ4 and Zstd refer to wal_compression and default_toast_compression,
but not to any corresponding option to basebackup.- There's no space after the hash mark here; but above, there was:
#Setup build directory with a different installation prefix
Added a space as that looks better.
- You use slash to show enumerated options, but it's more typical to
use braces: {a | b | c}:
-Dnls=auto/enabled/disabled
Changed.
- There's no earlier description/definition of an "auto" feature, but
still says this:
"Setting this option allows you to override value of all 'auto'
features"
Described what an "auto" feature is in ().
- Currently the documentation always refers to "PostgreSQL", but you added two references to "Postgres": + If a program required to build Postgres... + Once Postgres is built...
Good catch. Changed to PostgreSQL.
Regards,
Samay
Show quoted text
--
Justin
Attachments:
v7-0001-Add-docs-for-building-with-meson.patchapplication/octet-stream; name=v7-0001-Add-docs-for-building-with-meson.patchDownload
From 9cbb2022179d2ea60636c2d6c6ed71d666438fcc Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Sat, 27 Aug 2022 09:55:20 -0700
Subject: [PATCH v7] Add docs for building with meson
---
doc/src/sgml/installation.sgml | 1591 +++++++++++++++++++++++++++++++-
doc/src/sgml/monitoring.sgml | 2 +-
doc/src/sgml/runtime.sgml | 2 +-
doc/src/sgml/sourcerepo.sgml | 5 +-
4 files changed, 1551 insertions(+), 49 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 319c7e6966..3bc80a233c 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -31,7 +31,36 @@ documentation. See standalone-profile.xsl for details.
C++</productname>, see <xref linkend="install-windows"/> instead.
</para>
- <sect1 id="install-short">
+ <sect1 id="get-source">
+ <title>Getting the Source</title>
+
+ <para>
+ The <productname>PostgreSQL</productname> source code for released versions
+ can be obtained from the download section of our website:
+ <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+ Download the
+ <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+ or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+ file you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+ This will create a directory
+ <filename>postgresql-<replaceable>version</replaceable></filename> under
+ the current directory with the <productname>PostgreSQL</productname> sources.
+ Change into that directory for the rest of the installation procedure.
+ </para>
+
+ <para>
+ Alternatively, you can use the <productname>Git</productname> version control system; see
+ <xref linkend="git"/> for more information.
+ </para>
+ </sect1>
+
+<sect1 id="install-make">
+ <title>Building and Installation with autoconf and make</title>
+
+ <sect2 id="install-short-make">
<title>Short Version</title>
<para>
@@ -50,12 +79,12 @@ su - postgres
/usr/local/pgsql/bin/psql test
</synopsis>
The long version is the rest of this
- <phrase>chapter</phrase>.
+ <phrase>section</phrase>.
</para>
- </sect1>
+ </sect2>
- <sect1 id="install-requirements">
+ <sect2 id="install-requirements-make">
<title>Requirements</title>
<para>
@@ -237,7 +266,7 @@ su - postgres
can download an add-on package from <ulink
url="https://www.gnu.org/software/gettext/"></ulink>.
If you are using the <application>Gettext</application> implementation in
- the <acronym>GNU</acronym> C library then you will additionally
+ the <acronym>GNU</acronym> C library, then you will additionally
need the <productname>GNU Gettext</productname> package for some
utility programs. For any of the other implementations you will
not need it.
@@ -343,45 +372,9 @@ su - postgres
url="ftp://ftp.gnu.org/gnu/"></ulink>.
</para>
- <para>
- 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 <command>df</command> command to check free disk
- space.
- </para>
- </sect1>
-
- <sect1 id="install-getsource">
- <title>Getting the Source</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code for released versions
- can be obtained from the download section of our website:
- <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
- Download the
- <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
- or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
- file you're interested in, then unpack it:
-<screen>
-<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
-</screen>
- This will create a directory
- <filename>postgresql-<replaceable>version</replaceable></filename> under
- the current directory with the <productname>PostgreSQL</productname> sources.
- Change into that directory for the rest of the installation procedure.
- </para>
-
- <para>
- Alternatively, you can use the Git version control system; see
- <xref linkend="git"/> for more information.
- </para>
- </sect1>
+ </sect2>
- <sect1 id="install-procedure">
+ <sect2 id="install-procedure-make">
<title>Installation Procedure</title>
<procedure>
@@ -630,6 +623,7 @@ build-postgresql:
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
+ </sect2>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
@@ -844,7 +838,7 @@ build-postgresql:
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
- <xref linkend="install-requirements"/>.
+ <xref linkend="install-requirements-make"/>.
</para>
<variablelist>
@@ -1958,6 +1952,1513 @@ build-postgresql:
</sect2>
</sect1>
+ <sect1 id="install-meson">
+ <title>Building and Installation with meson</title>
+
+ <sect2 id="install-short-meson">
+ <title>Short Version</title>
+
+ <para>
+<synopsis>
+
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.git src
+
+# setup and enter build directory (done only first time)
+## Unix based platforms
+meson setup build src --prefix=$PWD/install
+
+## Windows
+meson setup build src --prefix=%cd%/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
+
+</synopsis>
+ The long version is the rest of this
+ <phrase>section</phrase>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-requirements-meson">
+ <title>Requirements</title>
+
+ <para>
+ In general, a modern Unix-compatible platform or Windows should be able
+ to build <productname>PostgreSQL</productname> with meson and run it.
+ The platforms which have received specific testing at the time of release are:
+
+ <itemizedlist spacing="compact">
+ <listitem><simpara>Linux</simpara></listitem>
+ <listitem><simpara>Windows</simpara></listitem>
+ <listitem><simpara>OpenBSD</simpara></listitem>
+ <listitem><simpara>NetBSD</simpara></listitem>
+ <listitem><simpara>FreeBSD</simpara></listitem>
+ <listitem><simpara>macOS</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect3 id="required-packages">
+ <title>Required packages</title>
+
+ <para>
+ The following software packages are required for building
+ <productname>PostgreSQL</productname>:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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
+ <productname>Git</productname>, which you can get from
+ <ulink url="https://git-scm.com"></ulink>. Many systems already
+ have a recent version of <productname>Git</productname>
+ installed by default, or available in their package distribution system.
+ If you download the source code tarballs, you will need
+ <application>tar</application> in addition to
+ <application>gzip</application> or <application>bzip2</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>meson</primary>
+ </indexterm>
+ You need to install <application>
+ <ulink url="https://mesonbuild.com/">meson</ulink></application> version
+ 0.54 or later to be able to build <productname>PostgreSQL</productname>
+ with it. If your operating system provides a package manager, you can install
+ <application>meson</application> with that. If not, you
+ can download a <ulink url="https://github.com/mesonbuild/meson">meson release</ulink>
+ from github and run <literal>./meson.py</literal> from the git repository
+ itself. Lastly, Meson is also available in the python package index and can
+ be installed with <application>pip</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You need an <acronym>ISO</acronym>/<acronym>ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <productname>GCC</productname> are recommended, but
+ <productname>PostgreSQL</productname> is known to build using a wide variety
+ of compilers from different vendors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>lex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
+ </indexterm>
+
+ <application>Flex</application> and <application>Bison</application>
+ are needed to build <productname>PostgreSQL</productname> using
+ <application>meson</application>. Be sure to get
+ <application>Flex</application> 2.5.35 or later and
+ <application>Bison</application> 2.3 or later from your package manager.
+ Other <application>lex</application> and <application>yacc</application>
+ programs cannot be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>perl</primary>
+ </indexterm>
+ <application>Perl</application> 5.8.3 or later is needed to build PostgreSQL
+ using <application>meson</application> and to run some test suites.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="recommended-packages">
+ <title>Recommended packages</title>
+
+ <para>
+ The following packages are not required to build
+ <application>PostgreSQL</application> but are strongly recommended:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>readline</primary>
+ </indexterm>
+ <indexterm>
+ <primary>libedit</primary>
+ </indexterm>
+
+ The <acronym>GNU</acronym> <productname>Readline</productname> library
+ allows <application>psql</application> (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 <filename>libedit</filename> library, originally
+ developed on <productname>NetBSD</productname>. The
+ <filename>libedit</filename> library is GNU
+ <productname>Readline</productname>-compatible and is used if
+ <filename>libreadline</filename> is not found, or if
+ <option>libedit_preferred</option> is enabled as an
+ option to <filename>meson configure</filename>. If you are using a
+ package-based Linux distribution, be aware that you need both the
+ <literal>readline</literal> and <literal>readline-devel</literal> packages, if
+ those are separate in your distribution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+
+ The <productname>zlib</productname> compression library is
+ used to provide support for compressed archives in
+ <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and
+ is recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various tests, particularly the client program tests under
+ <filename>src/bin</filename>, use the Perl TAP tools. Running
+ these tests is recommended for development. These TAP tests
+ require the Perl module <literal>IPC::Run</literal> which is
+ available from CPAN or an operating system package.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ <sect3 id="optional-packages">
+ <title>Optional packages</title>
+
+ <para>
+ 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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You need <productname>OpenSSL</productname>, if you want to support
+ encrypted client connections. <productname>OpenSSL</productname> is
+ also required for random number generation on platforms that do not
+ have <filename>/dev/urandom</filename> (except Windows). The minimum
+ required version is 1.0.1.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <productname>LZ4</productname> is needed to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-default-toast-compression"/> and
+ <xref linkend="guc-wal-compression"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <productname>Zstandard</productname> is needed to support
+ compression of data or backups with that method; see
+ <xref linkend="guc-wal-compression"/>.
+ The minimum required version is 1.4.0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You need <application>Kerberos</application>, <productname>OpenLDAP</productname>,
+ and/or <application>PAM</application>, if you want to support authentication
+ using those services.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the server programming language
+ <application>PL/Perl</application> you need a full
+ <productname>Perl</productname> installation, including the
+ <filename>libperl</filename> library and the header files.
+ The minimum required version is <productname>Perl</productname> 5.8.3.
+ Since <application>PL/Perl</application> will be a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <productname>Perl</productname> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <filename>configure</filename> will fail
+ if building <application>PL/Perl</application> is selected but it cannot
+ find a shared <filename>libperl</filename>. In that case, you will have
+ to rebuild and install <productname>Perl</productname> manually to be
+ able to build <application>PL/Perl</application>. During the
+ configuration process for <productname>Perl</productname>, request a
+ shared library.
+ </para>
+
+ <para>
+ If you intend to make more than incidental use of
+ <application>PL/Perl</application>, you should ensure that the
+ <productname>Perl</productname> installation was built with the
+ <literal>usemultiplicity</literal> option enabled (<literal>perl -V</literal>
+ will show whether this is the case).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Python</application> server programming
+ language, you need a <productname>Python</productname>
+ installation with the header files and
+ the <application>sysconfig</application> module. The minimum
+ required version is <productname>Python</productname> 3.2.
+ </para>
+
+ <para>
+ Since <application>PL/Python</application> will be a shared
+ library, the <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <productname>Python</productname> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <filename>configure</filename> will fail if
+ building <application>PL/Python</application> is selected but it cannot
+ find a shared <filename>libpython</filename>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <productname>Python</productname> installation to provide this shared
+ library. When building from source, run <productname>Python</productname>'s
+ configure with the <literal>--enable-shared</literal> flag.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <application>PL/Tcl</application>
+ procedural language, you of course need a <productname>Tcl</productname>
+ installation. The minimum required version is
+ <productname>Tcl</productname> 8.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <application>Gettext</application> <acronym>API</acronym>. Some operating
+ systems have this built-in (e.g., <systemitem
+ class="osname">Linux</systemitem>, <systemitem class="osname">NetBSD</systemitem>,
+ <systemitem class="osname">Solaris</systemitem>), for other systems you
+ can download an add-on package from <ulink
+ url="https://www.gnu.org/software/gettext/"></ulink>.
+ If you are using the <application>Gettext</application> implementation in
+ the <acronym>GNU</acronym> C library, then you will additionally
+ need the <productname>GNU Gettext</productname> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the <productname>PostgreSQL</productname> documentation,
+ there is a separate set of requirements; see
+ <xref linkend="docguide-toolsets"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="configure-meson">
+ <title>Configuring the build</title>
+
+ <para>
+ 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
+ <literal>meson setup</literal> command.
+ </para>
+
+<screen>
+<userinput>meson setup build</userinput>
+</screen>
+
+ <para>
+ The setup command takes a <literal>builddir</literal> and a <literal>srcdir</literal>
+ argument. If no <literal>srcdir</literal> is given, Meson will deduce the
+ <literal>srcdir</literal> based on the current directory and the location
+ of <literal>meson.build</literal>. The <literal>builddir</literal> is mandatory.
+ </para>
+
+ <para>
+ 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:
+
+<screen>
+# 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
+</screen>
+
+ Setting up the build directory is a one-time step. To reconfigure before a
+ new build, you can simply use the <literal>meson configure</literal> command
+ </para>
+
+<para>
+<screen>
+meson configure -Dcassert=true
+</screen>
+</para>
+
+<para>
+ <command>meson configure</command>'s commonly used command line options
+ are explained below. This list is not exhaustive (use
+ <literal>meson configure --help</literal> to get one that is).
+ The options not covered here are meant for advanced use-cases, and are
+ documented in the standard meson
+ <ulink url="https://mesonbuild.com/Commands.html#configure">documentation</ulink>.
+ These arguments can be used with <command>meson setup</command> as well.
+</para>
+
+ <sect3 id="configure-install-locations">
+ <title>Installation Locations</title>
+
+ <para>
+ These options control where <literal>ninja install (or meson install)</literal> will put
+ the files. The <option>--prefix</option> option (example
+ <xref linkend="install-short-meson"/>) 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 <literal>man</literal> and <literal>doc</literal> locations are
+ not affected by this restriction.)
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+ <listitem>
+ <para>
+ Install all files under the directory <replaceable>PREFIX</replaceable>
+ instead of <filename>/usr/local/pgsql</filename> (on Unix based systems) or
+ <filename>current drive letter:/usr/local/pgsql</filename> (on Windows).
+ The actual files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <replaceable>PREFIX</replaceable> directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--bindir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the directory for executable programs. The default
+ is <filename><replaceable>PREFIX</replaceable>/bin</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--sysconfdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for various configuration files,
+ <filename><replaceable>PREFIX</replaceable>/etc</filename> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--libdir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <filename><replaceable>PREFIX</replaceable>/lib</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--includedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing C and C++ header files. The
+ default is <filename><replaceable>PREFIX</replaceable>/include</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--datadir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <filename><replaceable>PREFIX</replaceable>/share</filename>. Note that this has
+ nothing to do with where your database files will be placed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--localedir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <filename><replaceable>DATADIR</replaceable>/locale</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mandir=<replaceable>DIRECTORY</replaceable></option></term>
+ <listitem>
+ <para>
+ The man pages that come with <productname>PostgreSQL</productname> will be installed under
+ this directory, in their respective
+ <filename>man<replaceable>x</replaceable></filename> subdirectories.
+ The default is <filename><replaceable>DATADIR</replaceable>/man</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ Care has been taken to make it possible to install
+ <productname>PostgreSQL</productname> into shared installation locations
+ (such as <filename>/usr/local/include</filename>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote><literal>postgres</literal></quote> or
+ <quote><literal>pgsql</literal></quote>. For example, if you choose
+ <filename>/usr/local</filename> as prefix, the documentation will
+ be installed in <filename>/usr/local/doc/postgresql</filename>,
+ but if the prefix is <filename>/opt/postgres</filename>, then it
+ will be in <filename>/opt/postgres/doc</filename>. The public C
+ header files of the client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <varname>includedir</varname>. 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 <varname>libdir</varname>
+ for dynamically loadable modules.
+ </para>
+ </note>
+ </sect3>
+
+ <sect3 id="configure-pg-features">
+ <title><productname>PostgreSQL</productname> Features</title>
+
+ <para>
+ The options described in this section enable building of
+ various optional <productname>PostgreSQL</productname> features.
+ Most of these require additional software, as described in
+ <xref linkend="install-requirements-meson"/>, and will be automatically enabled if the
+ required software is found. You can change this behavior by manually
+ setting these features to <literal>enabled</literal> to require them
+ or <literal>disabled</literal> to not build with them.
+ </para>
+
+ <para>
+ To specify PostgreSQL specific options, the name of the option
+ should be prefixed by -D.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-Dnls=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Enables or disables Native Language Support (<acronym>NLS</acronym>),
+ that is, the ability to display a program's messages in a
+ language other than English. It defaults to auto and will be enabled
+ automatically if an implementation of the <application>Gettext API</application> is found.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplperl=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Perl</application> server-side language. It
+ defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dplpython=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Python</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpltcl=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <application>PL/Tcl</application> server-side language.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtcl_version=<replaceable>TCL_VERSION</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the TCL version to use when building PL/Tcl.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dicu=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for
+ the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
+ library, enabling use of ICU collation
+ features<phrase condition="standalone-ignore"> (see
+ <xref linkend="collation"/>)</phrase>.
+ It defaults to auto and 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 id="configure-with-llvm-meson">
+ <term><option>-Dllvm=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for <productname>LLVM</productname> based
+ <acronym>JIT</acronym> compilation<phrase
+ condition="standalone-ignore"> (see <xref
+ linkend="jit"/>)</phrase>. This
+ requires the <productname>LLVM</productname> library to be installed.
+ The minimum required version of <productname>LLVM</productname> is
+ currently 3.9. It is set to disabled by default.
+ </para>
+ <para>
+ <command>llvm-config</command><indexterm><primary>llvm-config</primary></indexterm>
+ will be used to find the required compilation options.
+ <command>llvm-config</command>, and then
+ <command>llvm-config-$version</command> for all supported
+ versions, will be searched for in your <envar>PATH</envar>. If
+ that would not yield the desired program,
+ use <envar>LLVM_CONFIG</envar> to specify a path to the
+ correct <command>llvm-config</command>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlz4=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>LZ4</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzstd=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <productname>Zstandard</productname> compression support.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dssl=<replaceable>LIBRARY</replaceable></option>
+ <indexterm>
+ <primary>OpenSSL</primary>
+ <seealso>SSL</seealso>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Build with support for <acronym>SSL</acronym> (encrypted)
+ connections. The only <replaceable>LIBRARY</replaceable>
+ supported is <option>openssl</option>. This requires the
+ <productname>OpenSSL</productname> package to be installed.
+ Building with this will check for the required
+ header files and libraries to make sure that your
+ <productname>OpenSSL</productname> installation is sufficient
+ before proceeding. The default for this option is none.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dgssapi=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ 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>). In those cases, PostgreSQL will
+ query <command>pkg-config</command> to detect the required compiler
+ and linker options. It defaults to auto and <filename>meson 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>
+
+ <varlistentry>
+ <term><option>-Dldap=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
+ support for authentication and connection parameter lookup (see
+ <phrase id="install-ldap-links-meson"><xref linkend="libpq-ldap"/> and
+ <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
+ this requires the <productname>OpenLDAP</productname> package to be
+ installed. On Windows, the default <productname>WinLDAP</productname>
+ library is used. It defaults to auto and <filename>meson configure</filename>
+ will check for the required header files and libraries to make sure that your
+ <productname>OpenLDAP</productname> installation is sufficient before
+ proceeding.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dpam=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
+ (Pluggable Authentication Modules) support. It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbsd_auth=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with BSD Authentication support. (The BSD Authentication framework is
+ currently only available on OpenBSD.) It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystemd=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support
+ for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
+ service notifications. This improves integration if the server
+ is started under <application>systemd</application> but has no impact
+ otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
+ information</phrase>. It defaults to auto. <application>libsystemd</application> and the
+ associated header files need to be installed to use this option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dbonjour=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with support for Bonjour automatic service discovery.
+ It defaults to auto and requires Bonjour support in your operating system.
+ Recommended on macOS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Duuid=<replaceable>LIBRARY</replaceable></option></term>
+ <listitem>
+ <para>
+ Build the <xref linkend="uuid-ossp"/> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<indexterm><primary>UUID</primary></indexterm>
+ <replaceable>LIBRARY</replaceable> must be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>none</option> to not build the uuid module. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bsd</option> to use the UUID functions found in FreeBSD,
+ and some other BSD-derived systems
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>e2fs</option> to use the UUID library created by
+ the <literal>e2fsprogs</literal> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>ossp</option> to use the <ulink
+ url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxml=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxml2, enabling SQL/XML support. It defaults to auto. Libxml2
+ version 2.6.23 or later is required for this feature.
+ </para>
+
+ <para>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <command>pkg-config</command>-related environment
+ variables (see its documentation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibxslt=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Build with libxslt, enabling the
+ <xref linkend="xml2"/>
+ module to perform XSL transformations of XML.
+ <option>-Dlibxml</option> must be specified as well.
+ It defaults to auto.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dreadline=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Allows use of the <application>Readline</application> library
+ (and <application>libedit</application> as well). This option defaults to auto
+ and enables command-line editing and history in
+ <application>psql</application> and is strongly recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dlibedit_preferred=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this to true 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 is false, that is to use <application>Readline</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dzlib=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>zlib</primary>
+ </indexterm>
+ Enables use of the <application>Zlib</application> library.
+ It defaults to auto and enables
+ support for compressed archives in <application>pg_dump</application>,
+ <application>pg_restore</application> and <application>pg_basebackup</application> and is recommended.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-build-process">
+ <title>Build Process Details</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--auto_features=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Setting this option allows you to override value of all 'auto' features
+ (features which 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--backend=<replaceable>BACKEND</replaceable></option></term>
+ <listitem>
+ <para>
+ 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
+ <option>BACKEND</option> to <command>vs</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C compiler.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dc_link_args=<replaceable>OPTIONS</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to pass extra options to the C linker.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_include_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> 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 <application>Readline</application>) installed in a non-standard
+ location,
+ you have to use this option and probably also the corresponding
+ <option>-Dextra_lib_dirs</option> option.
+ </para>
+ <para>
+ Example: <literal>-Dextra_include_dirs=/opt/gnu/include,/usr/sup/include</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_lib_dirs=<replaceable>DIRECTORIES</replaceable></option></term>
+ <listitem>
+ <para>
+ <replaceable>DIRECTORIES</replaceable> is a comma-separated list of
+ directories to search for libraries. You will probably have
+ to use this option (and the corresponding
+ <option>-Dextra_include_dirs</option> option) if you have packages
+ installed in non-standard locations.
+ </para>
+ <para>
+ Example: <literal>-Dextra_lib_dirs=/opt/gnu/lib,/usr/sup/lib</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsystem_tzdata=<replaceable>DIRECTORY</replaceable></option>
+ <indexterm>
+ <primary>time zone data</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> 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 <replaceable>DIRECTORY</replaceable> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <replaceable>DIRECTORY</replaceable> must be specified as an
+ absolute path. <filename>/usr/share/zoneinfo</filename> 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 <productname>PostgreSQL</productname>.
+ </para>
+
+ <indexterm><primary>cross compilation</primary></indexterm>
+
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dextra_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 <productname>Git</productname>
+ 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>-D<replaceable>BINARY_NAME</replaceable>=<replaceable>PATH</replaceable></option></term>
+ <listitem>
+ <para>
+ If a program required to build PostgreSQL (with or without optional
+ flags) is stored at a non-standard path, you could specify it
+ manually to meson configure. The complete list of programs for which
+ this is supported can be found by running <literal>meson configure</literal>.
+ An example is included below.
+<programlisting>meson configure -DBISON=PATH_TO_BISON</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-layout">
+ <title>Data layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
+ <sect3 id="configure-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>--debug</option>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <option>-Ddtrace</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 <option>--buildtype=debug</option>
+ and <option>-Dcassert</option> options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--buildtype=<replaceable>BUILDTYPE</replaceable></option></term>
+ <listitem>
+ <para>
+ This option can be used to specify the buildtype to use; defaults
+ to <option>release</option>. If you'd like finer control on the debug symbols
+ and optimization levels than what this option provides, you can
+ refer to the <option>--debug</option> and <option>--optimization</option> flags.
+
+ The following build types are generally used: <option>plain</option>,
+ <option>debug</option>, <option>debugoptimized</option> and <option>release</option>.
+ More information about them can be found in the
+ <ulink url="https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory">
+ meson documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--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>
+
+ <varlistentry>
+ <term><option>--optimization</option>=<replaceable>LEVEL</replaceable></term>
+ <listitem>
+ <para>
+ Specify the optimization level. <option>LEVEL</option> can be set to any of {0,g,1,2,3,s}.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--werror</option></term>
+ <listitem>
+ <para>
+ Setting this option asks the compiler to treat warnings as errors. This can
+ be useful for code development purposes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dcassert</option></term>
+ <listitem>
+ <para>
+ Enables <firstterm>assertion</firstterm> checks in the server, which test for
+ many <quote>cannot happen</quote> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dtap-tests=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable tests using the Perl TAP tools. This is set to auto and 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>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
+ <listitem>
+ <para>
+ Enable test suites which require special software to run. This option
+ accepts arguments via a whitespace-separated list. The following values
+ are currently supported:
+ <variablelist>
+ <varlistentry>
+ <term><literal>kerberos</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/kerberos</filename>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ldap</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ldap</filename>. This
+ requires an <productname>OpenLDAP</productname> installation and opens
+ TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ssl</literal></term>
+ <listitem>
+ <para>
+ Runs the test suite under <filename>src/test/ssl</filename>. This opens TCP/IP listen sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>wal_consistency_checking</literal></term>
+ <listitem>
+ <para>
+ Uses <literal>wal_consistency_checking=all</literal> while running
+ certain tests under <filename>src/test/recovery</filename>. Not
+ enabled by default because it is resource intensive.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <varname>PG_TEST_EXTRA</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Db_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>-Ddtrace=<replaceable>{ auto | enabled | disabled }</replaceable></option></term>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>DTrace</primary>
+ </indexterm>
+ Enabling this compiles <productname>PostgreSQL</productname> with support for the
+ dynamic tracing tool DTrace.
+ <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
+ for more information.</phrase>
+ </para>
+
+ <para>
+ To point to the <command>dtrace</command> program, the
+ <option>DTRACE</option> option can be set. This
+ will often be necessary because <command>dtrace</command> is
+ typically installed under <filename>/usr/sbin</filename>,
+ which might not be in your <envar>PATH</envar>.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dspinlocks=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Datomics=<replaceable>true/false</replaceable></option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id="configure-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="build-meson">
+ <title>Building the source</title>
+ <para>
+ By default, <productname>Meson</productname> uses the
+ <ulink url="https://ninja-build.org/"> Ninja build system</ulink>.
+ To build <productname>PostgreSQL</productname> from source using meson, you can
+ simply use the <literal>ninja</literal> command in the build directory.
+<screen>
+ninja
+</screen>
+ 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 <literal>-j</literal>.
+ </para>
+
+ <para>
+ It should be noted that after the initial configure step,
+ <command>ninja</command> 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.
+ </para>
+
+ <para>
+ If you'd like to build with a backend other than ninja, you can use configure
+ with the <option>--backend</option> option to select the one you want to use and then
+ build using <literal>meson compile</literal>. To learn more about these
+ backends and other arguments you can provide to ninja, you can refer to the
+ meson <ulink url="https://mesonbuild.com/Running-Meson.html#building-from-the-source">
+ documentation</ulink>.
+ </para>
+ </sect2>
+
+ <sect2 id="install-files-meson">
+ <title>Installing the files</title>
+ <para>
+ Once PostgreSQL is built, you can install it by simply running the
+ <literal>ninja install</literal> command.
+
+<screen>
+ninja install
+</screen>
+ </para>
+
+ <para>
+ This will install files into the directories that were specified
+ in <xref linkend="configure-meson"/>. 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.
+ </para>
+
+ <para>
+ <literal>ninja install</literal> should work for most cases,
+ but if you'd like to use more options (like --quiet to suppress extra output),
+ you could also use <literal>meson install</literal> instead. You can learn more about
+ <ulink url="https://mesonbuild.com/Commands.html#install">meson install</ulink>
+ and its options in the meson documentation.
+ </para>
+
+ <para>
+ Depending on your platform and setup, you might have to perform a
+ few steps after installation. Those are outlined in
+ <xref linkend="install-post"/>.
+ </para>
+
+ <formalpara>
+ <title>Uninstallation:</title>
+ <para>
+ To undo the installation, you can use the <command>ninja
+ uninstall</command> command.
+ </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>ninja clean</command>
+ command.
+ </para>
+ </formalpara>
+
+ </sect2>
+
+ <sect2 id="running-tests">
+ <title>Running tests</title>
+ <para>
+ 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 <productname>PostgreSQL</productname> runs on your machine in
+ the way the developers expected it to. To run them, simply type:
+<screen>
+<userinput>meson test</userinput>
+</screen>
+ You can repeat this at any later time by issuing the same command.
+ </para>
+
+ <para>Meson also allows you to list tests and run specific tests or suites.
+<screen>
+# List all tests
+<userinput>meson test --list</userinput>
+
+# Run the pg_regress tests
+<userinput>meson test --suite setup --suite regress</userinput>
+
+# Run a specific test (might need to run setup suite first)
+<userinput>meson test recovery/001_stream_rep</userinput>
+
+</screen>
+ </para>
+
+ <para>
+ To learn more about running the tests and how to interpret the results,
+ you can refer to the documentation.
+ <literal>meson test</literal> also provides a number of additional
+ options you can use which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
<sect1 id="install-post">
<title>Post-Installation Setup</title>
@@ -2170,7 +3671,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 <xref linkend="install-requirements"/> as well. Also,
+ particular <xref linkend="install-requirements-make"/> as well. Also,
check <xref linkend="regress"/> regarding the
interpretation of regression test results.
</para>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e2426f7210..8d1af92ed2 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7119,7 +7119,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref
- linkend="install-procedure"/> for further information.
+ linkend="configure-options-devel"/> for further information.
</para>
</sect2>
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 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
- outlined in <xref linkend="install-procedure"/>.
+ outlined in <xref linkend="installation"/>.
</para>
</step>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 0ed7f8a3fe..f16be29a61 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,10 @@
Note that building <productname>PostgreSQL</productname> from the source
repository requires reasonably up-to-date versions of <application>bison</application>,
<application>flex</application>, and <application>Perl</application>. 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 <xref linkend="install-requirements"/>.
+ are the same as shown in <xref linkend="install-requirements-make"/> and
+ <xref linkend="install-requirements-meson"/>.
</para>
<sect1 id="git">
--
2.38.1
Re: Documentation for building with meson
Thanks; two more things I saw:
- In other docs, <replacable> isn't used around { a | b } lists:
git grep '<replaceable>[^<]*|' doc
- I think this is(was) missing a word;
Setting this option allows you to override THE value of all 'auto' features
--
Justin
Re: Documentation for building with meson
On 23.11.22 22:24, samay sharma wrote:
Thank you. Attaching v7 addressing most of the points below.
I have committed this, after some editing and making some structural
changes. I moved the "Requirements" section back to the top level. It
did not look appealing to have to maintain two copies of this that have
almost no substantial difference (but for some reason were written with
separate structure and wording). Also, I rearranged the Building with
Meson section to use the same internal structure as the Building with
Autoconf and Make section. This will make it easier to maintain going
forward. For example if someone adds a new option, it will be easier to
find the corresponding places in the lists where to add them.
We will likely keep iterating on the contents for the next little while,
but I'm glad we now have a structure in place that we should be able to
live with.
Re: Documentation for building with meson
Hi,
On 2022-12-01 15:58:39 +0100, Peter Eisentraut wrote:
On 23.11.22 22:24, samay sharma wrote:
Thank you. Attaching v7 addressing most of the points below.
I have committed this, after some editing and making some structural
changes.
Thanks. I was working on that too, but somehow felt a bit stuck...
I'll try if I can adapt my pending changes.
I moved the "Requirements" section back to the top level. It did
not look appealing to have to maintain two copies of this that have almost
no substantial difference (but for some reason were written with separate
structure and wording).
I don't think this is good. The whole "The following software packages are
required for building PostgreSQL" section is wrong now. "They are not
required in the default configuration, but they are needed when certain build
options are enabled, as explained below:" section is misleading as well.
By the time we fix all of those we'll end up with a different section again.
Also, I rearranged the Building with Meson section to use the same internal
structure as the Building with Autoconf and Make section. This will make it
easier to maintain going forward. For example if someone adds a new option,
it will be easier to find the corresponding places in the lists where to add
them.
I don't know. The existing list order makes very little sense to me. The
E.g. --enable-nls is before the rest in configure, presumably because it sorts
there alphabetically. But that's not the case for meson.
Copying "Anti-Features" as a structure element to the meson docs seems bogus
(also the name is bogus, but that's a pre-existing issue). There's no
difference in -Dreadline= to the other options meson-options-features list.
Nor does -Dspinlocks= -Datomics= make sense in the "anti features" section. It
made some sense for autoconf because of the --without- prefix, but that's not
at play in meson. Their placement in the "Developer Options" made a whole lot
more sense.
I don't like "Miscellaneous" bit containing minor stuff like krb_srvnam and
data layout changing options like blocksize,segsize,wal_blocksize. But it
makes sense to change that for both at the same time.
We will likely keep iterating on the contents for the next little while, but
I'm glad we now have a structure in place that we should be able to live
with.
I agree that it's good to have something we can work from more
iteratively. But I don't think this is a structure that we can live with.
I'm not particularly happy about this level of structural change made without
discussing it prior.
Greetings,
Andres Freund
Re: Documentation for building with meson
Hi,
On Thu, Dec 1, 2022 at 9:21 AM Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2022-12-01 15:58:39 +0100, Peter Eisentraut wrote:
On 23.11.22 22:24, samay sharma wrote:
Thank you. Attaching v7 addressing most of the points below.
I have committed this, after some editing and making some structural
changes.Thanks. I was working on that too, but somehow felt a bit stuck...
I'll try if I can adapt my pending changes.
I got back to working on the meson docs. I'm attaching a new patch set
proposing some improvements to the current installation docs. I've tried to
make some corrections and improvements suggested in this thread while
trying to maintain consistency across make and meson docs as per Peter's
ask. There are 5 patches in the patch-set:
v8-0001: Makes minor corrections, adds instructions to build docs and adds
a few links to meson docs.
v8-0002, v8-0003 and v8-0004 make changes to restructure the configure
options based on reasoning discussed below. To maintain consistency, I've
made those changes on both the make and meson side.
v8-0005 Reproposes the Short Version I had proposed in v7 as I feel we
should discuss that proposal. I think it improves things in terms of
installation docs. More details below.
I moved the "Requirements" section back to the top level. It did
not look appealing to have to maintain two copies of this that havealmost
no substantial difference (but for some reason were written with separate
structure and wording).
There are a few reasons why I had done this. Some reasons Andres has
described in his previous email and I'll add a few specific examples on why
having the same section for both might not be a good idea.
* Having readline and zlib as required for building PostgreSQL is now wrong
because they are not required for meson builds. Also, the name of the
configs are different for make and meson and the current section only lists
the make ones.
* There are many references to configure in that section which don't apply
to meson.
* Last I checked Flex and Bison were always required to build via meson but
not for make and the current section doesn't explain those differences.
I spent a good amount of time thinking if we could have a single section,
clarify these differences to make it correct and not confuse the users. I
couldn't find a way to do all three. Therefore, I think we should move to a
different requirements section for both. I'm happy to re-propose the
previous version which separates them but wanted to see if anybody has
better ideas.
I don't think this is good. The whole "The following software packages are
required for building PostgreSQL" section is wrong now. "They are not
required in the default configuration, but they are needed when certain
build
options are enabled, as explained below:" section is misleading as well.By the time we fix all of those we'll end up with a different section
again.Also, I rearranged the Building with Meson section to use the same
internal
structure as the Building with Autoconf and Make section. This will
make it
easier to maintain going forward. For example if someone adds a new
option,
it will be easier to find the corresponding places in the lists where to
add
them.
I don't know. The existing list order makes very little sense to me. The
E.g. --enable-nls is before the rest in configure, presumably because it
sorts
there alphabetically. But that's not the case for meson.Copying "Anti-Features" as a structure element to the meson docs seems
bogus
(also the name is bogus, but that's a pre-existing issue). There's no
difference in -Dreadline= to the other options meson-options-features list.
Nor does -Dspinlocks= -Datomics= make sense in the "anti features"
section. It
made some sense for autoconf because of the --without- prefix, but that's
not
at play in meson. Their placement in the "Developer Options" made a whole
lot
more sense.
I agree "Anti-Features" desn't make sense in the meson context. One of my
patches removes that section and moves some options into the "Postgres
Features" section and others into the "Developer Options" section. I've
proposed to make those changes on both sides to make it easier to maintain.
I don't like "Miscellaneous" bit containing minor stuff like krb_srvnam and
data layout changing options like blocksize,segsize,wal_blocksize. But it
makes sense to change that for both at the same time.
I've proposed a patch to add a new "Data Layout Options" section which
includes: blocksize, segsize and wal_blocksize. I've created that section
on both sides.
We will likely keep iterating on the contents for the next little while,
but
I'm glad we now have a structure in place that we should be able to live
with.
I feel that there are a few shortcomings of the current "Short Version". I
tried to address them in my previous proposal but I noticed that a version
similar to the make version was committed. So, I thought I'd describe why I
proposed a new structure.
1) The current version has OS specific commands (eg. adduser). They don't
work across all platforms.
2) The installation instructions use paths which require sudo and which are
also OS specific. Not every developer who wants to build and try out
Postgres might have sudo permissions.
3) Most developers have a separate installation path where they store their
dev binaries while the current instructions install them in standard paths.
4) I wanted to have a separate directory which can nicely be cleaned once
you're done with building and testing the packages. That's easier to do at
a local path.
5) There's no description of what each instruction does so that developers
can modify the commands if they want to change something.
Due to these reasons, I feel it's worth considering the newer version of
the "Short version". I've proposed to change it only in the meson docs for
now but if there's interest I can modify the make instructions to be the
same. I left them as it is as people might be used to those instructions.
Regards,
Samay
Show quoted text
I agree that it's good to have something we can work from more
iteratively. But I don't think this is a structure that we can live with.I'm not particularly happy about this level of structural change made
without
discussing it prior.Greetings,
Andres Freund
Attachments:
v8-0002-Add-data-layout-options-sub-section-in-installati.patchapplication/octet-stream; name=v8-0002-Add-data-layout-options-sub-section-in-installati.patchDownload
From b539821835267e2c43f15eb7d0afa30918b00ce9 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 16:09:42 -0800
Subject: [PATCH v8 2/5] Add data layout options sub-section in installation
docs
This commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.
---
doc/src/sgml/installation.sgml | 156 +++++++++++++++++++--------------
1 file changed, 89 insertions(+), 67 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 97ee0a04a3..657330d368 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1470,6 +1470,35 @@ build-postgresql:
</listitem>
</varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id="configure-options-data-layout">
+ <title>Data layout Options</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-option-with-blocksize">
+ <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).
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="configure-option-with-segsize">
<term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
<listitem>
@@ -1488,25 +1517,6 @@ build-postgresql:
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 breaks on-disk database compatibility,
- meaning you cannot use <command>pg_upgrade</command> to upgrade to
- a build with a different segment size.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-option-with-blocksize">
- <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 breaks on-disk database compatibility,
- meaning you cannot use <command>pg_upgrade</command> to upgrade to
- a build with a different block size.
</para>
</listitem>
</varlistentry>
@@ -1520,9 +1530,6 @@ build-postgresql:
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 breaks on-disk database compatibility,
- meaning you cannot use <command>pg_upgrade</command> to upgrade to
- a build with a different WAL block size.
</para>
</listitem>
</varlistentry>
@@ -2917,53 +2924,68 @@ ninja install
</listitem>
</varlistentry>
- <varlistentry id="configure-segsize-meson">
- <term><option>-Dsegsize=<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.
- </para>
- </listitem>
- </varlistentry>
+ </variablelist>
+ </sect3>
- <varlistentry id="configure-blocksize-meson">
- <term><option>-Dblocksize=<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).
- </para>
- </listitem>
- </varlistentry>
+ <sect3 id="meson-options-data-layout">
+ <title>Data layout Options</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry id="configure-wal-blocksize-meson">
- <term><option>-Dwal_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).
- </para>
- </listitem>
- </varlistentry>
</variablelist>
</sect3>
--
2.38.1
v8-0005-Change-Short-Version-for-meson-installation-guide.patchapplication/octet-stream; name=v8-0005-Change-Short-Version-for-meson-installation-guide.patchDownload
From 523211d70810ce2bc15c3fc5fed3bbaf5b4fa1d7 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Fri, 24 Feb 2023 20:41:28 -0800
Subject: [PATCH v8 5/5] Change Short Version for meson installation guide
This commit proposes a new version of the short version for building
from source using meson. Some advantages over the current version
include: does not require sudo, creates a localised installation
path and doesn't replace system binaries, doesn't have distro specific
commands and has one line description of what each command does.
---
doc/src/sgml/installation.sgml | 40 +++++++++++++++++++++++++---------
1 file changed, 30 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 140b1f518f..0b87f320f5 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1983,19 +1983,39 @@ build-postgresql:
<para>
<synopsis>
-meson setup build --prefix=/usr/local/pgsql
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.git src
+
+# setup and enter build directory (done only first time)
+## Unix based platforms
+meson setup build src --prefix=$PWD/install
+
+## Windows
+meson setup build src --prefix=%cd%/install
+
cd build
+
+# Compile source
ninja
-su
+
+# Install to the prefix directory specified above
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
+
+# 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
</synopsis>
The long version is the rest of this
<phrase>section</phrase>.
--
2.38.1
v8-0001-Make-minor-additions-and-corrections-to-meson-doc.patchapplication/octet-stream; name=v8-0001-Make-minor-additions-and-corrections-to-meson-doc.patchDownload
From f8213542976dac49e2f061099c82aceb9f472bf6 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 15:31:48 -0800
Subject: [PATCH v8 1/5] Make minor additions and corrections to meson docs
This commit makes a few corrections to the meson docs
and adds a few instructions and links for better clarity.
---
doc/src/sgml/installation.sgml | 26 +++++++++++++++++++-------
1 file changed, 19 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 0ed35d99e9..97ee0a04a3 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -2057,8 +2057,7 @@ meson setup build -Dssl=openssl
<screen>
meson configure -Dcassert=true
</screen>
- <command>meson configure</command>'s commonly used command-line options
- are explained in <xref linkend="meson-options"/>.
+ Commonly used build options for <command>meson configure</command> (and <command>meson setup</command>) are explained in <xref linkend="meson-options"/>.
</para>
</step>
@@ -2078,6 +2077,13 @@ ninja
processes used with the command line argument <literal>-j</literal>.
</para>
+ <para>
+ If you want to build the docs, you can type:
+<screen>
+ninja docs
+</screen>
+ </para>
+
<para>
It should be noted that after the initial configure step,
<command>ninja</command> is the only command you ever need to type to
@@ -2118,9 +2124,15 @@ ninja
<userinput>meson test</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.
+ You can repeat this test at any later time by issuing the same command.
+ </para>
+
+ <para>
+ <literal>meson test</literal> also provides a number of additional options
+ which can be found in the
+ <ulink url="https://mesonbuild.com/Unit-tests.html#testing-tool">meson test documentation</ulink>.
+ You can also see <xref linkend="regress"/> for
+ detailed information about interpreting the test results.
</para>
<para>
@@ -2199,8 +2211,8 @@ ninja install
to get one that is). The options not covered here are meant for advanced
use-cases, and are documented in the standard <ulink
url="https://mesonbuild.com/Commands.html#configure">Meson
- documentation</ulink>. These arguments can be used with <command>meson
- setup</command> as well.
+ documentation</ulink>. These options can be used with <command>meson
+ configure</command> as well.
</para>
<sect3 id="meson-options-locations">
--
2.38.1
v8-0003-Remove-Anti-Features-section-from-Installation-fr.patchapplication/octet-stream; name=v8-0003-Remove-Anti-Features-section-from-Installation-fr.patchDownload
From 614ac11bcdba08ae8ce2844b72312a818379aced Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:23:52 -0800
Subject: [PATCH v8 3/5] Remove Anti-Features section from Installation from
source docs
Currently, several meson setup options are listed in anti-features.
However, they are similar to most other options in the postgres
features list as they are 'auto' features themselves. Also, other
options are likely better suited to the developer options section.
This commit, therefore, moves the options listed in the anti-features
section into other sections and removes that section.
For consistency, this reorganization has been done on the make section
of the docs as well.
---
doc/src/sgml/installation.sgml | 166 ++++++++++++++-------------------
1 file changed, 70 insertions(+), 96 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 657330d368..9c7ee91cb9 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1214,23 +1214,6 @@ build-postgresql:
</listitem>
</varlistentry>
- </variablelist>
-
- </sect3>
-
- <sect3 id="configure-options-anti-features">
- <title>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 id="configure-option-without-readline">
<term><option>--without-readline</option></term>
<listitem>
@@ -1270,47 +1253,6 @@ build-postgresql:
</listitem>
</varlistentry>
- <varlistentry id="configure-option-disable-spinlocks">
- <term><option>--disable-spinlocks</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 very 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 id="configure-option-disable-atomics">
- <term><option>--disable-atomics</option></term>
- <listitem>
- <para>
- 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 id="configure-option-disable-thread-safety">
- <term><option>--disable-thread-safety</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. Use this only on platforms
- with deficient threading support.
- </para>
- </listitem>
- </varlistentry>
-
</variablelist>
</sect3>
@@ -1702,6 +1644,47 @@ build-postgresql:
</listitem>
</varlistentry>
+ <varlistentry id="configure-option-disable-spinlocks">
+ <term><option>--disable-spinlocks</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 very 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 id="configure-option-disable-atomics">
+ <term><option>--disable-atomics</option></term>
+ <listitem>
+ <para>
+ 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 id="configure-option-disable-thread-safety">
+ <term><option>--disable-thread-safety</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. Use this only on platforms
+ with deficient threading support.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect3>
@@ -2661,13 +2644,6 @@ ninja install
</para>
</listitem>
</varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="meson-options-anti-features">
- <title>Anti-Features</title>
-
- <variablelist>
<varlistentry id="configure-readline-meson">
<term><option>-Dreadline={ auto | enabled | disabled }</option></term>
<listitem>
@@ -2707,36 +2683,6 @@ ninja install
</para>
</listitem>
</varlistentry>
-
- <varlistentry id="configure-spinlocks-meson">
- <term><option>-Dspinlocks={ true | false }</option></term>
- <listitem>
- <para>
- This option is set to true by default; setting it to false will
- 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 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 <productname>PostgreSQL</productname> on
- your platform, please report the problem to the
- <productname>PostgreSQL</productname> developers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-atomics-meson">
- <term><option>-Datomics={ true | false }</option></term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
</variablelist>
</sect3>
@@ -3158,8 +3104,36 @@ ninja install
</para>
</listitem>
</varlistentry>
+ <varlistentry id="configure-spinlocks-meson">
+ <term><option>-Dspinlocks={ true | false }</option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
- </variablelist>
+ <varlistentry id="configure-atomics-meson">
+ <term><option>-Datomics={ true | false }</option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect3>
</sect2>
</sect1>
--
2.38.1
v8-0004-Re-organize-Miscellaneous-section.patchapplication/octet-stream; name=v8-0004-Re-organize-Miscellaneous-section.patchDownload
From 969960955ce30590ee6ec6dd4427cf2c059924d0 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:57:07 -0800
Subject: [PATCH v8 4/5] Re-organize Miscellaneous section
Move Miscellaneous section to the end of the options section after
all the named sections.
---
doc/src/sgml/installation.sgml | 163 +++++++++++++++++----------------
1 file changed, 82 insertions(+), 81 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 9c7ee91cb9..140b1f518f 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1371,51 +1371,6 @@ build-postgresql:
</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 id="configure-option-with-pgport">
- <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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-option-with-krb-srvnam">
- <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 are building for a Windows
- environment, in which case it must be set to upper case
- <literal>POSTGRES</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect3>
-
<sect3 id="configure-options-data-layout">
<title>Data layout Options</title>
@@ -1689,6 +1644,51 @@ build-postgresql:
</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 id="configure-option-with-pgport">
+ <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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-option-with-krb-srvnam">
+ <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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect3>
+
</sect2>
<sect2 id="configure-envvars">
@@ -2837,42 +2837,6 @@ ninja install
</variablelist>
</sect3>
- <sect3 id="meson-options-misc">
- <title>Miscellaneous</title>
-
- <variablelist>
- <varlistentry id="configure-pgport-meson">
- <term><option>-Dpgport=<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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-krb-srvnam-meson">
- <term><option>-Dkrb_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 are building for a Windows
- environment, in which case it must be set to upper case
- <literal>POSTGRES</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
-
<sect3 id="meson-options-data-layout">
<title>Data layout Options</title>
@@ -3135,6 +3099,43 @@ ninja install
</varlistentry>
</variablelist>
</sect3>
+
+ <sect3 id="meson-options-misc">
+ <title>Miscellaneous</title>
+
+ <variablelist>
+ <varlistentry id="configure-pgport-meson">
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-krb-srvnam-meson">
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect3>
+
</sect2>
</sect1>
--
2.38.1
Re: Documentation for building with meson
[PATCH v8 1/5] Make minor additions and corrections to meson docs
The last hunk revealed that there is some mixing up between meson setup
and meson configure. This goes a bit further. For example, earlier it
says that to get a list of meson setup options, call meson configure
--help and look at https://mesonbuild.com/Commands.html#configure, which
are both wrong. Also later throughout the text it uses one or the
other. I think this has the potential to be very confusing, and we
should clean this up carefully.
The text about additional meson test options maybe should go into the
regress.sgml chapter?
[PATCH v8 2/5] Add data layout options sub-section in installation
docs
This makes sense. Please double check your patch for correct title
casing, vertical spacing of XML, to keep everything looking consistent.
This text isn't yours, but since your patch emphasizes it, I wonder if
it could use some clarification:
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use <command>pg_upgrade</command> to upgrade to
+ a build with different values of these options.This isn't really correct. What breaking on-disk compatibility means is
that you can't use a server compiled one way with a data directory
initialized by binaries compiled another way. pg_upgrade may well have
the ability to upgrade between one or the other; that's up to pg_upgrade
to figure out but not an intrinsic property. (I wonder why pg_upgrade
cares about the WAL block size.)
[PATCH v8 3/5] Remove Anti-Features section from Installation from
source docs
Makes sense. But is "--disable-thread-safety" really a developer
feature? I think not.
[PATCH v8 4/5] Re-organize Miscellaneous section
This moves the Miscellaneous section after Developer Features. I think
Developer Features should be last.
Maybe should remove this section and add the options to the regular
PostgreSQL Features section.
Also consider the grouping in meson_options.txt, which is slightly
different yet.
[PATCH v8 5/5] Change Short Version for meson installation guide
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.git srcThis comes after the "Getting the Source" section, so at this point they
already have the source and don't need to do "git clone" etc. again.
+# setup and enter build directory (done only first time)
+## Unix based platforms
+meson setup build src --prefix=$PWD/install
+
+## Windows
+meson setup build src --prefix=%cd%/installMaybe some people work this way, but to me the directory structures you
create here are completely weird.
+# 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 postgresThe terminology here needs to be tightened up. You are using "database"
here to mean three different things.
Re: Documentation for building with meson
Hi,
On Wed, Mar 15, 2023 at 4:28 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:
[PATCH v8 1/5] Make minor additions and corrections to meson docs
The last hunk revealed that there is some mixing up between meson setup
and meson configure. This goes a bit further. For example, earlier it
says that to get a list of meson setup options, call meson configure
--help and look at https://mesonbuild.com/Commands.html#configure, which
are both wrong. Also later throughout the text it uses one or the
other. I think this has the potential to be very confusing, and we
should clean this up carefully.The text about additional meson test options maybe should go into the
regress.sgml chapter?
I tried to make the meson setup and meson configure usage consistent. I've
removed the text for the test options.
[PATCH v8 2/5] Add data layout options sub-section in installation
docs
This makes sense. Please double check your patch for correct title
casing, vertical spacing of XML, to keep everything looking consistent.
Thanks for noticing. Made it consistent on both sides.
This text isn't yours, but since your patch emphasizes it, I wonder if
it could use some clarification:+ These options affect how PostgreSQL lays out data on disk. + Note that changing these breaks on-disk database compatibility, + meaning you cannot use <command>pg_upgrade</command> to upgrade to + a build with different values of these options.This isn't really correct. What breaking on-disk compatibility means is
that you can't use a server compiled one way with a data directory
initialized by binaries compiled another way. pg_upgrade may well have
the ability to upgrade between one or the other; that's up to pg_upgrade
to figure out but not an intrinsic property. (I wonder why pg_upgrade
cares about the WAL block size.)
Fixed.
[PATCH v8 3/5] Remove Anti-Features section from Installation from
source docs
Makes sense. But is "--disable-thread-safety" really a developer
feature? I think not.
Moved to PostgreSQL features. Do you think there's a better place for it?
[PATCH v8 4/5] Re-organize Miscellaneous section
This moves the Miscellaneous section after Developer Features. I think
Developer Features should be last.Maybe should remove this section and add the options to the regular
PostgreSQL Features section.
Yes, that makes sense. Made this change.
Also consider the grouping in meson_options.txt, which is slightly
different yet.
Removed Misc options section from meson_options.txt too.
[PATCH v8 5/5] Change Short Version for meson installation guide
+# create working directory +mkdir postgres +cd postgres + +# fetch source code +git clone https://git.postgresql.org/git/postgresql.git srcThis comes after the "Getting the Source" section, so at this point they
already have the source and don't need to do "git clone" etc. again.+# setup and enter build directory (done only first time) +## Unix based platforms +meson setup build src --prefix=$PWD/install + +## Windows +meson setup build src --prefix=%cd%/installMaybe some people work this way, but to me the directory structures you
create here are completely weird.
I'd like to discuss what you think is a good directory structure to work
with. I've mentioned some of the drawbacks I see with the current structure
for the short version. I know this structure can feel different but it
feeling weird is not ideal. Do you have a directory structure in mind which
is different but doesn't feel odd to you?
+# 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 postgresThe terminology here needs to be tightened up. You are using "database"
here to mean three different things.
I'll address this together once we are aligned on the overall directory
structure etc.
There are a few reasons why I had done this. Some reasons Andres has
described in his previous email and I'll add a few specific examples on why
having the same section for both might not be a good idea.* Having readline and zlib as required for building PostgreSQL is now
wrong because they are not required for meson builds. Also, the name of the
configs are different for make and meson and the current section only lists
the make ones.
* There are many references to configure in that section which don't
apply to meson.
* Last I checked Flex and Bison were always required to build via meson
but not for make and the current section doesn't explain those differences.I spent a good amount of time thinking if we could have a single section,
clarify these differences to make it correct and not confuse the users. I
couldn't find a way to do all three. Therefore, I think we should move to
a different requirements section for both. I'm happy to re-propose the
previous version which separates them but wanted to see if anybody has
better ideas.
Do you have thoughts on the requirements section and the motivation to have
two different versions I had mentioned upthread?
Regards,
Samay
Attachments:
v9-0004-Remove-Miscellaneous-section.patchapplication/octet-stream; name=v9-0004-Remove-Miscellaneous-section.patchDownload
From dd728df385266ff61d03324dac44adc5792e279d Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:57:07 -0800
Subject: [PATCH v9 4/5] Remove Miscellaneous section
After some reorganization, only 2 options remain in the
Miscellaneous section. This commit removes that section and
moves the options to the PostgreSQL features section.
---
doc/src/sgml/installation.sgml | 141 ++++++++++++++-------------------
meson_options.txt | 15 ++--
2 files changed, 66 insertions(+), 90 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index d7ab0c205e..0efbb1c2a3 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1061,6 +1061,20 @@ build-postgresql:
</listitem>
</varlistentry>
+ <varlistentry id="configure-option-with-krb-srvnam">
+ <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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="configure-option-with-ldap">
<term><option>--with-ldap</option></term>
<listitem>
@@ -1253,6 +1267,21 @@ build-postgresql:
</listitem>
</varlistentry>
+ <varlistentry id="configure-option-with-pgport">
+ <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.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="configure-option-disable-thread-safety">
<term><option>--disable-thread-safety</option></term>
<listitem>
@@ -1384,51 +1413,6 @@ build-postgresql:
</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 id="configure-option-with-pgport">
- <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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-option-with-krb-srvnam">
- <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 are building for a Windows
- environment, in which case it must be set to upper case
- <literal>POSTGRES</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect3>
-
<sect3 id="configure-options-data-layout">
<title>Data Layout</title>
@@ -2506,6 +2490,20 @@ ninja install
</listitem>
</varlistentry>
+ <varlistentry id="configure-krb-srvnam-meson">
+ <term><option>-Dkrb_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 are building for a Windows
+ environment, in which case it must be set to upper case
+ <literal>POSTGRES</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="configure-with-ldap-meson">
<term><option>-Dldap={ auto | enabled | disabled }</option></term>
<listitem>
@@ -2679,6 +2677,22 @@ ninja install
</para>
</listitem>
</varlistentry>
+
+ <varlistentry id="configure-pgport-meson">
+ <term><option>-Dpgport=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect3>
@@ -2852,42 +2866,6 @@ ninja install
</variablelist>
</sect3>
- <sect3 id="meson-options-misc">
- <title>Miscellaneous</title>
-
- <variablelist>
- <varlistentry id="configure-pgport-meson">
- <term><option>-Dpgport=<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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-krb-srvnam-meson">
- <term><option>-Dkrb_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 are building for a Windows
- environment, in which case it must be set to upper case
- <literal>POSTGRES</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
-
<sect3 id="meson-options-data-layout">
<title>Data Layout</title>
@@ -3152,6 +3130,7 @@ ninja install
</varlistentry>
</variablelist>
</sect3>
+
</sect2>
</sect1>
diff --git a/meson_options.txt b/meson_options.txt
index 4402dd4299..afa7fc7056 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -19,15 +19,6 @@ option('segsize_blocks', type : 'integer', value: 0,
description : '''Segment size, in blocks''')
-# Miscellaneous options
-
-option('krb_srvnam', type : 'string', value : 'postgres',
- description : '''Default Kerberos service principal for GSSAPI''')
-
-option('system_tzdata', type: 'string', value: '',
- description: 'use system time zone data in specified directory')
-
-
# Defaults
option('pgport', type : 'integer', value : 5432,
@@ -70,6 +61,9 @@ option('darwin_sysroot', type : 'string', value: '',
option('rpath', type : 'boolean', value: true,
description: 'whether to embed shared library search path in executables')
+option('system_tzdata', type: 'string', value: '',
+ description: 'use system time zone data in specified directory')
+
# External dependencies
@@ -106,6 +100,9 @@ option('llvm', type : 'feature', value: 'disabled',
option('lz4', type : 'feature', value: 'auto',
description: 'LZ4 support')
+option('krb_srvnam', type : 'string', value : 'postgres',
+ description : '''Default Kerberos service principal for GSSAPI''')
+
option('nls', type: 'feature', value: 'auto',
description: 'native language support')
--
2.38.1
v9-0002-Add-data-layout-options-sub-section-in-installati.patchapplication/octet-stream; name=v9-0002-Add-data-layout-options-sub-section-in-installati.patchDownload
From c5e637a54c2b83e5bd8c4155784d97e82937eb51 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 16:09:42 -0800
Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
docs
This commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.
---
doc/src/sgml/installation.sgml | 160 +++++++++++++++++++--------------
1 file changed, 92 insertions(+), 68 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index e3b9b6c0d0..7e65cdd72e 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1470,6 +1470,35 @@ build-postgresql:
</listitem>
</varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id="configure-options-data-layout">
+ <title>Data Layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use these binaries with data directories
+ created with different values of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-option-with-blocksize">
+ <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).
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="configure-option-with-segsize">
<term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
<listitem>
@@ -1488,25 +1517,6 @@ build-postgresql:
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 breaks on-disk database compatibility,
- meaning you cannot use <command>pg_upgrade</command> to upgrade to
- a build with a different segment size.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-option-with-blocksize">
- <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 breaks on-disk database compatibility,
- meaning you cannot use <command>pg_upgrade</command> to upgrade to
- a build with a different block size.
</para>
</listitem>
</varlistentry>
@@ -1520,9 +1530,6 @@ build-postgresql:
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 breaks on-disk database compatibility,
- meaning you cannot use <command>pg_upgrade</command> to upgrade to
- a build with a different WAL block size.
</para>
</listitem>
</varlistentry>
@@ -2932,54 +2939,71 @@ ninja install
</listitem>
</varlistentry>
- <varlistentry id="configure-segsize-meson">
- <term><option>-Dsegsize=<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.
- </para>
- </listitem>
- </varlistentry>
+ </variablelist>
+ </sect3>
- <varlistentry id="configure-blocksize-meson">
- <term><option>-Dblocksize=<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).
- </para>
- </listitem>
- </varlistentry>
+ <sect3 id="meson-options-data-layout">
+ <title>Data Layout</title>
+
+ <para>
+ These options affect how PostgreSQL lays out data on disk.
+ Note that changing these breaks on-disk database compatibility,
+ meaning you cannot use these binaries with data directories
+ created with different values of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="meson-option-with-blocksize">
+ <term><option>-Dblocksize=<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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="meson-option-with-segsize">
+ <term><option>-Dsegsize=<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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="meson-option-with-wal-blocksize">
+ <term><option>-Dwal_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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
- <varlistentry id="configure-wal-blocksize-meson">
- <term><option>-Dwal_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).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
</sect3>
<sect3 id="meson-options-devel">
--
2.38.1
v9-0001-Make-minor-additions-and-corrections-to-meson-doc.patchapplication/octet-stream; name=v9-0001-Make-minor-additions-and-corrections-to-meson-doc.patchDownload
From 920d628a6fcc8d64a1fcbeadeb9574a01f21c425 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 15:31:48 -0800
Subject: [PATCH v9 1/5] Make minor additions and corrections to meson docs
This commit makes a few corrections to the meson docs
and adds a few instructions and links for better clarity.
---
doc/src/sgml/installation.sgml | 24 +++++++++++++++---------
1 file changed, 15 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 70ab5b77d8..e3b9b6c0d0 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -2057,8 +2057,7 @@ meson setup build -Dssl=openssl
<screen>
meson configure -Dcassert=true
</screen>
- <command>meson configure</command>'s commonly used command-line options
- are explained in <xref linkend="meson-options"/>.
+ Commonly used build options for <command>meson configure</command> (and <command>meson setup</command>) are explained in <xref linkend="meson-options"/>.
</para>
</step>
@@ -2078,6 +2077,13 @@ ninja
processes used with the command line argument <literal>-j</literal>.
</para>
+ <para>
+ If you want to build the docs, you can type:
+<screen>
+ninja docs
+</screen>
+ </para>
+
<para>
It should be noted that after the initial configure step,
<command>ninja</command> is the only command you ever need to type to
@@ -2118,9 +2124,9 @@ ninja
<userinput>meson test</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.
+ You can repeat this test at any later time by issuing the same command.
+ You can also see <xref linkend="regress"/> for
+ detailed information about interpreting the test results.
</para>
<para>
@@ -2191,16 +2197,16 @@ ninja install
</sect2>
<sect2 id="meson-options">
- <title><literal>meson setup</literal> Options</title>
+ <title>Configuration Options</title>
<para>
- <command>meson setup</command>'s command-line options are explained below.
+ <command>meson setup</command> and <command>meson configure</command>
+ support several command-line options which are explained below.
This list is not exhaustive (use <literal>meson configure --help</literal>
to get one that is). The options not covered here are meant for advanced
use-cases, and are documented in the standard <ulink
url="https://mesonbuild.com/Commands.html#configure">Meson
- documentation</ulink>. These arguments can be used with <command>meson
- setup</command> as well.
+ documentation</ulink>.
</para>
<sect3 id="meson-options-locations">
--
2.38.1
v9-0003-Remove-Anti-Features-section-from-Installation-fr.patchapplication/octet-stream; name=v9-0003-Remove-Anti-Features-section-from-Installation-fr.patchDownload
From 11d82aa49efb3d1cbc08f14562a757f115053c8b Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:23:52 -0800
Subject: [PATCH v9 3/5] Remove Anti-Features section from Installation from
source docs
Currently, several meson setup options are listed in anti-features.
However, they are similar to most other options in the postgres
features list as they are 'auto' features themselves. Also, other
options are likely better suited to the developer options section.
This commit, therefore, moves the options listed in the anti-features
section into other sections and removes that section.
For consistency, this reorganization has been done on the make section
of the docs as well.
---
doc/src/sgml/installation.sgml | 140 ++++++++++++++-------------------
1 file changed, 57 insertions(+), 83 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 7e65cdd72e..d7ab0c205e 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1214,23 +1214,6 @@ build-postgresql:
</listitem>
</varlistentry>
- </variablelist>
-
- </sect3>
-
- <sect3 id="configure-options-anti-features">
- <title>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 id="configure-option-without-readline">
<term><option>--without-readline</option></term>
<listitem>
@@ -1270,34 +1253,6 @@ build-postgresql:
</listitem>
</varlistentry>
- <varlistentry id="configure-option-disable-spinlocks">
- <term><option>--disable-spinlocks</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 very 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 id="configure-option-disable-atomics">
- <term><option>--disable-atomics</option></term>
- <listitem>
- <para>
- 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 id="configure-option-disable-thread-safety">
<term><option>--disable-thread-safety</option></term>
<listitem>
@@ -1702,6 +1657,34 @@ build-postgresql:
</listitem>
</varlistentry>
+ <varlistentry id="configure-option-disable-spinlocks">
+ <term><option>--disable-spinlocks</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 very 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 id="configure-option-disable-atomics">
+ <term><option>--disable-atomics</option></term>
+ <listitem>
+ <para>
+ 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>
+
</variablelist>
</sect3>
@@ -2657,13 +2640,6 @@ ninja install
</para>
</listitem>
</varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="meson-options-anti-features">
- <title>Anti-Features</title>
-
- <variablelist>
<varlistentry id="configure-readline-meson">
<term><option>-Dreadline={ auto | enabled | disabled }</option></term>
<listitem>
@@ -2703,36 +2679,6 @@ ninja install
</para>
</listitem>
</varlistentry>
-
- <varlistentry id="configure-spinlocks-meson">
- <term><option>-Dspinlocks={ true | false }</option></term>
- <listitem>
- <para>
- This option is set to true by default; setting it to false will
- 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 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 <productname>PostgreSQL</productname> on
- your platform, please report the problem to the
- <productname>PostgreSQL</productname> developers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="configure-atomics-meson">
- <term><option>-Datomics={ true | false }</option></term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
</variablelist>
</sect3>
@@ -3175,8 +3121,36 @@ ninja install
</para>
</listitem>
</varlistentry>
+ <varlistentry id="configure-spinlocks-meson">
+ <term><option>-Dspinlocks={ true | false }</option></term>
+ <listitem>
+ <para>
+ This option is set to true by default; setting it to false will
+ 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 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 <productname>PostgreSQL</productname> on
+ your platform, please report the problem to the
+ <productname>PostgreSQL</productname> developers.
+ </para>
+ </listitem>
+ </varlistentry>
- </variablelist>
+ <varlistentry id="configure-atomics-meson">
+ <term><option>-Datomics={ true | false }</option></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect3>
</sect2>
</sect1>
--
2.38.1
v9-0005-Change-Short-Version-for-meson-installation-guide.patchapplication/octet-stream; name=v9-0005-Change-Short-Version-for-meson-installation-guide.patchDownload
From 6945616e713be01cc779e14c78ad0f8e8a69876b Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Fri, 24 Feb 2023 20:41:28 -0800
Subject: [PATCH v9 5/5] Change Short Version for meson installation guide
This commit proposes a new version of the short version for building
from source using meson. Some advantages over the current version
include: does not require sudo, creates a localised installation
path and doesn't replace system binaries, doesn't have distro specific
commands and has one line description of what each command does.
---
doc/src/sgml/installation.sgml | 40 +++++++++++++++++++++++++---------
1 file changed, 30 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 0efbb1c2a3..d1791e5952 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1967,19 +1967,39 @@ build-postgresql:
<para>
<synopsis>
-meson setup build --prefix=/usr/local/pgsql
+# create working directory
+mkdir postgres
+cd postgres
+
+# fetch source code
+git clone https://git.postgresql.org/git/postgresql.git src
+
+# setup and enter build directory (done only first time)
+## Unix based platforms
+meson setup build src --prefix=$PWD/install
+
+## Windows
+meson setup build src --prefix=%cd%/install
+
cd build
+
+# Compile source
ninja
-su
+
+# Install to the prefix directory specified above
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
+
+# 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
</synopsis>
The long version is the rest of this
<phrase>section</phrase>.
--
2.38.1
Re: Documentation for building with meson
Hi,
On 2023-03-28 12:27:26 -0700, samay sharma wrote:
Subject: [PATCH v9 1/5] Make minor additions and corrections to meson docs
This commit makes a few corrections to the meson docs
and adds a few instructions and links for better clarity.
---
doc/src/sgml/installation.sgml | 24 +++++++++++++++---------
1 file changed, 15 insertions(+), 9 deletions(-)diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 70ab5b77d8..e3b9b6c0d0 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -2057,8 +2057,7 @@ meson setup build -Dssl=openssl <screen> meson configure -Dcassert=true </screen> - <command>meson configure</command>'s commonly used command-line options - are explained in <xref linkend="meson-options"/>. + Commonly used build options for <command>meson configure</command> (and <command>meson setup</command>) are explained in <xref linkend="meson-options"/>. </para> </step>@@ -2078,6 +2077,13 @@ ninja
processes used with the command line argument <literal>-j</literal>.
</para>+ <para> + If you want to build the docs, you can type: +<screen> +ninja docs +</screen> + </para>
"type" sounds a bit too, IDK, process oriented. "To build the docs, use"?
Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
docsThis commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.
Makes sense. I'm planning to apply this unless Peter or somebody else has
further feedback.
From 11d82aa49efb3d1cbc08f14562a757f115053c8b Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:23:52 -0800
Subject: [PATCH v9 3/5] Remove Anti-Features section from Installation from
source docsCurrently, several meson setup options are listed in anti-features.
However, they are similar to most other options in the postgres
features list as they are 'auto' features themselves. Also, other
options are likely better suited to the developer options section.
This commit, therefore, moves the options listed in the anti-features
section into other sections and removes that section.For consistency, this reorganization has been done on the make section
of the docs as well.
Makes sense to me. "Anti-Features" is confusing as a name to start with.
Greetings,
Andres Freund
Re: Documentation for building with meson
Hi,
On Tue, Apr 11, 2023 at 10:18 AM Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2023-03-28 12:27:26 -0700, samay sharma wrote:
Subject: [PATCH v9 1/5] Make minor additions and corrections to meson
docs
This commit makes a few corrections to the meson docs
and adds a few instructions and links for better clarity.
---
doc/src/sgml/installation.sgml | 24 +++++++++++++++---------
1 file changed, 15 insertions(+), 9 deletions(-)diff --git a/doc/src/sgml/installation.sgmlb/doc/src/sgml/installation.sgml
index 70ab5b77d8..e3b9b6c0d0 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -2057,8 +2057,7 @@ meson setup build -Dssl=openssl <screen> meson configure -Dcassert=true </screen> - <command>meson configure</command>'s commonly used command-lineoptions
- are explained in <xref linkend="meson-options"/>. + Commonly used build options for <command>meson configure</command>(and <command>meson setup</command>) are explained in <xref
linkend="meson-options"/>.</para>
</step>@@ -2078,6 +2077,13 @@ ninja
processes used with the command line argument <literal>-j</literal>.
</para>+ <para> + If you want to build the docs, you can type: +<screen> +ninja docs +</screen> + </para>"type" sounds a bit too, IDK, process oriented. "To build the docs, use"?
Sure, that works.
Subject: [PATCH v9 2/5] Add data layout options sub-section in
installation
docs
This commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.Makes sense. I'm planning to apply this unless Peter or somebody else has
further feedback.
Cool.
Show quoted text
From 11d82aa49efb3d1cbc08f14562a757f115053c8b Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:23:52 -0800
Subject: [PATCH v9 3/5] Remove Anti-Features section from Installationfrom
source docs
Currently, several meson setup options are listed in anti-features.
However, they are similar to most other options in the postgres
features list as they are 'auto' features themselves. Also, other
options are likely better suited to the developer options section.
This commit, therefore, moves the options listed in the anti-features
section into other sections and removes that section.For consistency, this reorganization has been done on the make section
of the docs as well.Makes sense to me. "Anti-Features" is confusing as a name to start with.
Greetings,
Andres Freund
Re: Documentation for building with meson
On 11.04.23 19:18, Andres Freund wrote:
Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
docsThis commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.Makes sense. I'm planning to apply this unless Peter or somebody else has
further feedback.
I'm okay with patches 0001 through 0004.
I don't like 0005. I think we should drop that for now and maybe have a
separate discussion under a separate heading about that.
Show quoted text
From 11d82aa49efb3d1cbc08f14562a757f115053c8b Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:23:52 -0800
Subject: [PATCH v9 3/5] Remove Anti-Features section from Installation from
source docsCurrently, several meson setup options are listed in anti-features.
However, they are similar to most other options in the postgres
features list as they are 'auto' features themselves. Also, other
options are likely better suited to the developer options section.
This commit, therefore, moves the options listed in the anti-features
section into other sections and removes that section.For consistency, this reorganization has been done on the make section
of the docs as well.Makes sense to me. "Anti-Features" is confusing as a name to start with.
Re: Documentation for building with meson
Hey!
Nice work organizing the docs. Looks pretty good. I had a single comment
regarding the Meson docs in general.
It seems like Postgres cares a bit about Windows/Mac development. Is
ninja the blessed way to build Postgres on Windows and Mac? Otherwise, I
would suggest just being more generic and replace instances of `ninja
xxx` in the docs with `meson compile xxx`, making the command
backend-agnostic to accomodate XCode and VS project users.
--
Tristan Partin
Neon (https://neon.tech)
Re: Documentation for building with meson
On Wed Apr 12, 2023 at 4:19 PM CDT, Peter Eisentraut wrote:
On 11.04.23 19:18, Andres Freund wrote:
Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
docsThis commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.Makes sense. I'm planning to apply this unless Peter or somebody else has
further feedback.I'm okay with patches 0001 through 0004.
I don't like 0005. I think we should drop that for now and maybe have a
separate discussion under a separate heading about that.
With regard to 0005, perhaps it makes the most sense to use the XDG
Directory Specification as an example. Install into ~/.local or
~/.local/postgres (as the Meson default prefix is). Put the data into
~/.var/lib/postgres or something similar.
--
Tristan Partin
Neon (https://neon.tech)
Re: Documentation for building with meson
Hi,
On 2023-03-28 12:27:26 -0700, samay sharma wrote:
+ <para> + If you want to build the docs, you can type: +<screen> +ninja docs +</screen> + </para>
To me 'you can type' sounds odd. To me even just "To build the docs:" would
sound better. But the make docs do it "your" way, so I'll just go along with
it for now.
From c5e637a54c2b83e5bd8c4155784d97e82937eb51 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 16:09:42 -0800
Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
docsThis commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.
I still like this change, but ISTM that the "Data Layout" section should
follow the "PostgreSQL Features" section, rather than follow "Anti Features",
"Build Process Details" and "Miscellaneous". I realize some of these are
reorganized later on, but even then "Build Process Details"
Would anybody mind if I swapped these around?
+ <varlistentry id="meson-option-with-blocksize">
I don't quite understand the "-with" added to the ids?
From 11d82aa49efb3d1cbc08f14562a757f115053c8b Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 13 Feb 2023 16:23:52 -0800
Subject: [PATCH v9 3/5] Remove Anti-Features section from Installation from
source docsCurrently, several meson setup options are listed in anti-features.
However, they are similar to most other options in the postgres
features list as they are 'auto' features themselves. Also, other
options are likely better suited to the developer options section.
This commit, therefore, moves the options listed in the anti-features
section into other sections and removes that section.
For consistency, this reorganization has been done on the make section
of the docs as well.
---
doc/src/sgml/installation.sgml | 140 ++++++++++++++-------------------
1 file changed, 57 insertions(+), 83 deletions(-)diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 7e65cdd72e..d7ab0c205e 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1214,23 +1214,6 @@ build-postgresql: </listitem> </varlistentry>- </variablelist>
-
- </sect3>
-
- <sect3 id="configure-options-anti-features">
- <title>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 id="configure-option-without-readline">
<term><option>--without-readline</option></term>
<listitem>
I don't think this is quite right. The section above the list says
"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 Section 17.1."
So just merging --without-icu, --without-readline, --without-zlib,
--disable-thread-safety, in with the rest doesn't quite seem right.
I suspect that the easiest way for that is to just move --disable-atomics,
--disable-spinlocks to the developer section and then to leave the
anti-features section around for autoconf.
Any better idea?
Greetings,
Andres Freund
Re: Documentation for building with meson
On 10.06.23 06:00, Andres Freund wrote:
From c5e637a54c2b83e5bd8c4155784d97e82937eb51 Mon Sep 17 00:00:00 2001
From: Samay Sharma<smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 16:09:42 -0800
Subject: [PATCH v9 2/5] Add data layout options sub-section in installation
docsThis commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.I still like this change, but ISTM that the "Data Layout" section should
follow the "PostgreSQL Features" section, rather than follow "Anti Features",
"Build Process Details" and "Miscellaneous". I realize some of these are
reorganized later on, but even then "Build Process Details"Would anybody mind if I swapped these around?
I don't mind a Data Layout section in principle, but I wonder whether
it's worth changing now. The segsize option is proposed to be turned
into a run-time option (and/or removed). For the WAL block size, I had
previously mentioned, I don't think it is correct that pg_upgrade should
actually care about it. So I wouldn't spend too much time trying to
carefully refactor the notes on the data layout options if we're going
to have to change them around before long again anyway.
Re: Documentation for building with meson
On Wed, 29 Mar 2023 at 00:57, samay sharma <smilingsamay@gmail.com> wrote:
Hi,
On Wed, Mar 15, 2023 at 4:28 AM Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
[PATCH v8 1/5] Make minor additions and corrections to meson docs
The last hunk revealed that there is some mixing up between meson setup
and meson configure. This goes a bit further. For example, earlier it
says that to get a list of meson setup options, call meson configure
--help and look at https://mesonbuild.com/Commands.html#configure, which
are both wrong. Also later throughout the text it uses one or the
other. I think this has the potential to be very confusing, and we
should clean this up carefully.The text about additional meson test options maybe should go into the
regress.sgml chapter?I tried to make the meson setup and meson configure usage consistent. I've removed the text for the test options.
[PATCH v8 2/5] Add data layout options sub-section in installation
docs
This makes sense. Please double check your patch for correct title
casing, vertical spacing of XML, to keep everything looking consistent.Thanks for noticing. Made it consistent on both sides.
This text isn't yours, but since your patch emphasizes it, I wonder if
it could use some clarification:+ These options affect how PostgreSQL lays out data on disk. + Note that changing these breaks on-disk database compatibility, + meaning you cannot use <command>pg_upgrade</command> to upgrade to + a build with different values of these options.This isn't really correct. What breaking on-disk compatibility means is
that you can't use a server compiled one way with a data directory
initialized by binaries compiled another way. pg_upgrade may well have
the ability to upgrade between one or the other; that's up to pg_upgrade
to figure out but not an intrinsic property. (I wonder why pg_upgrade
cares about the WAL block size.)Fixed.
[PATCH v8 3/5] Remove Anti-Features section from Installation from
source docs
Makes sense. But is "--disable-thread-safety" really a developer
feature? I think not.Moved to PostgreSQL features. Do you think there's a better place for it?
[PATCH v8 4/5] Re-organize Miscellaneous section
This moves the Miscellaneous section after Developer Features. I think
Developer Features should be last.Maybe should remove this section and add the options to the regular
PostgreSQL Features section.Yes, that makes sense. Made this change.
Also consider the grouping in meson_options.txt, which is slightly
different yet.Removed Misc options section from meson_options.txt too.
[PATCH v8 5/5] Change Short Version for meson installation guide
+# create working directory +mkdir postgres +cd postgres + +# fetch source code +git clone https://git.postgresql.org/git/postgresql.git srcThis comes after the "Getting the Source" section, so at this point they
already have the source and don't need to do "git clone" etc. again.+# setup and enter build directory (done only first time) +## Unix based platforms +meson setup build src --prefix=$PWD/install + +## Windows +meson setup build src --prefix=%cd%/installMaybe some people work this way, but to me the directory structures you
create here are completely weird.I'd like to discuss what you think is a good directory structure to work with. I've mentioned some of the drawbacks I see with the current structure for the short version. I know this structure can feel different but it feeling weird is not ideal. Do you have a directory structure in mind which is different but doesn't feel odd to you?
+# 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 postgresThe terminology here needs to be tightened up. You are using "database"
here to mean three different things.I'll address this together once we are aligned on the overall directory structure etc.
There are a few reasons why I had done this. Some reasons Andres has described in his previous email and I'll add a few specific examples on why having the same section for both might not be a good idea.
* Having readline and zlib as required for building PostgreSQL is now wrong because they are not required for meson builds. Also, the name of the configs are different for make and meson and the current section only lists the make ones.
* There are many references to configure in that section which don't apply to meson.
* Last I checked Flex and Bison were always required to build via meson but not for make and the current section doesn't explain those differences.I spent a good amount of time thinking if we could have a single section, clarify these differences to make it correct and not confuse the users. I couldn't find a way to do all three. Therefore, I think we should move to a different requirements section for both. I'm happy to re-propose the previous version which separates them but wanted to see if anybody has better ideas.
Do you have thoughts on the requirements section and the motivation to have two different versions I had mentioned upthread?
I have changed the status of commitfest entry to "Returned with
Feedback" as there was no followup on Tristan Partin and Andres's
comments from many months. Please handle the comments and add a new
commitfest entry if required for any pending tasks left.
Regards,
Vignesh