Re: Documentation for building with meson - Mailing list pgsql-hackers

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