Re: Documentation for building with meson - Mailing list pgsql-hackers
| From | samay sharma |
|---|---|
| Subject | Re: Documentation for building with meson |
| Date | |
| Msg-id | CAJxrbyzHyfvgESwspORMU1j8sDyQK1pbJ=yx3mDLXtwCdqOLAQ@mail.gmail.com Whole thread Raw |
| In response to | Re: Documentation for building with meson (Andres Freund <andres@anarazel.de>) |
| Responses |
Re: Documentation for building with meson
|
| List | pgsql-hackers |
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/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
Attachment
pgsql-hackers by date: