Re: Documentation for building with meson

Hi,

On Sat, Nov 5, 2022 at 2:39 PM Andres Freund <andres(at)anarazel(dot)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/install
>
> This 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 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.
>

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 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.
>

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> 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.
>

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 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>'?
>

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 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.
>

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 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?
>

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 required
>
> The <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 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.
>

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 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/?
>

Changed.

>
>
>
> > + <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.
>

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. 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.
>

Makes sense. Moved.

>
>
> > + <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 :
>

Changed.

>
> > + <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.
>

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 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?
>

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 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.
>

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 <xref
> linkend="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">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.
>

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

>
>
> Greetings,
>
> Andres Freund
>