PS-10735 [DOCS] - update compile-percona-server 8.4

[patrickbirch]

modified:   docs/compile-percona-server.md

[inikep]

Blocking: this whole Boost section does not apply to Percona Server 8.4.

DOWNLOAD_BOOST and WITH_BOOST do not exist in this product. A grep over every CMakeLists.txt and *.cmake in the 8.4 tree returns no hits for either name. cmake/boost.cmake is explicit:

SET(BOOST_PACKAGE_NAME "boost_1_84_0")

# Always use the bundled version.
SET(BOOST_SOURCE_DIR ${CMAKE_SOURCE_DIR}/extra/boost)

Boost 1.84.0 ships in extra/boost/boost_1_84_0, and CMake raises a FATAL_ERROR if the bundled headers are not exactly 1.84 (EXPECTED_BOOST_VERSION 108400). So there is nothing to download, no system Boost to point CMake at, and no version mismatch a reader can hit or fix.

The example on line 165 is also inverted: the tree expects 1.84, not 1.77 (1.77 is the 8.0 value), so as written it tells readers that a correct Boost is the broken one.

Suggest replacing lines 163-176 with a short statement that Boost is bundled at the required version and needs no CMake flags or network access.

[inikep]

Blocking (same root cause as the Boost section above). CMake cannot report a Boost version mismatch of the kind described, and -DDOWNLOAD_BOOST=1 is not a recognised option in Percona Server 8.4 — passing it produces only the "Manually-specified variables were not used by the project" warning, exactly like -DFEATURE_SET=community. Please drop this line.

[inikep]

Percona MyRocks doesn't support snappy so all references to snappy should be removed.

[inikep]

I checked the technical claims against the percona-server 8.4 source tree (checked out at 8.4.11). Five blocking issues. Two are already flagged inline; the rest are listed here with line references.

1. The Boost sections do not apply to Percona Server 8.4

compile-percona-server.md lines 58, 163-176, 196 — source-installation-prerequisites.md lines 113, 134-148

DOWNLOAD_BOOST and WITH_BOOST do not exist in this product. A grep over every CMakeLists.txt and *.cmake in the tree returns no hits for either name. cmake/boost.cmake is explicit:

SET(BOOST_PACKAGE_NAME "boost_1_84_0")

# Always use the bundled version.
SET(BOOST_SOURCE_DIR ${CMAKE_SOURCE_DIR}/extra/boost)

Boost 1.84.0 ships in extra/boost/boost_1_84_0, and CMake raises a FATAL_ERROR if the bundled headers are not exactly 1.84 (EXPECTED_BOOST_VERSION 108400). So there is nothing to download, no system Boost to point CMake at, and no version mismatch a reader can hit or fix. Passing -DDOWNLOAD_BOOST=1 yields only the "Manually-specified variables were not used by the project" warning — the same behaviour the page correctly documents for -DFEATURE_SET=community.

Consequences to fix: the "Option A / Option B" framework in both pages, the "do not pass both flags" notes, the wget/curl justification ("Required for Option A"), and the claim that CMake configuration needs network access.

The worked example is also inverted — line 165 reads "for example, 1.8x when the tree expects 1.77". The tree expects 1.84 (1.77 is the 8.0 value), so as written it tells readers a correct Boost is the broken one.

2. The cmake . fallback for make dist cannot work

compile-percona-server.md lines 107 and 147

CMakeLists.txt makes an in-source build a FATAL_ERROR unless -DFORCE_INSOURCE_BUILD=1 is passed:

Please do not build in-source. Out-of source builds are highly recommended … You can force in-source build by invoking cmake with -DFORCE_INSOURCE_BUILD=1

So "run cmake . and make dist from the root" fails immediately. The premise is unfounded too: the dist target is declared in sql/CMakeLists.txt with WORKING_DIRECTORY ${CMAKE_BINARY_DIR}, so an out-of-source make dist is exactly how it is meant to run. This note also contradicts the page's own (correct) statement on line 194 that in-source builds must not be used. Suggest deleting the note and the cross-reference on line 107.

Related, while you are in that area: make distclean in this tree only prints "WARNING: distclean target is not functional — use git clean -fdx", which is worth knowing next to the warning about git clean -xfd.

3. Minimum GCC version is wrong

source-installation-prerequisites.md lines 24, 61, 101

cmake/os/Linux.cmake enforces GCC ≥ 10 or Clang ≥ 14:

# We require at least GCC 10 Clang 14
...
MESSAGE(FATAL_ERROR "GCC 10 or newer is required")
...
MESSAGE(FATAL_ERROR "Clang 14 or newer is required!")

The page says "GCC 11.3 or newer" in three places and leaves Clang as "a Clang version documented for {{vers}}". Please use the enforced numbers. If 11.3 comes from upstream MySQL's prerequisites page, say so and cite it, because it is not what Percona Server 8.4 checks.

4. Minimum CMake version is wrong

source-installation-prerequisites.md lines 24 and 59

The tree requires CMAKE_MINIMUM_REQUIRED(VERSION 3.14.6), matching upstream's documented 3.14.6. The page says 3.15 twice.

5. Broken admonition

compile-percona-server.md lines 159-161

!!! note

    `-DFEATURE_SET=community` is not supported in {{vers}}. If you use
`-DFEATURE_SET=community`, CMake will report: *Manually-specified variables were not used by the project:
FEATURE_SET*.

The continuation lines are not indented, so they fall out of the note block in MkDocs. Indent lines 160-161 by four spaces.

[inikep]

There is no glibc or linker version check anywhere in the tree, so "the
build will fail" is wrong. The C++20 part itself is right (C++20 is required: -std=c++20, cxx_std_20 in cmake/build_configurations/compiler_options.cmake and cmake/plugin.cmake).

[svetasmirnova]

It may also make sense to describe how to check out a specific tag from GitHub to build a specific version. Otherwise, GitHub instructions are for the latest code in the branch (maybe unstable).

[svetasmirnova]

What is "a task guide"? Sounds not clear to me.

[svetasmirnova]

You mix build type with the install prefix. Better to say:

Use option -DCMAKE_INSTALL_PREFIX for make install:

Or keep text instructions as they were written and write this as an example:

cmake .. -DCMAKE_INSTALL_PREFIX=/opt/percona-server-{{vers}}

[svetasmirnova]

This will build a binary. Creating a source code tarball this way is overkill, I believe. You also need to use option -DFORCE_INSOURCE_BUILD=1 to be able to have build directory under the source tree.

[svetasmirnova]

You will get an error:

sveta@lemurr:~/src/percona/percona-server/build$ cmake ..
-- Running cmake version 4.2.3
-- CMAKE_MODULE_PATH is /home/sveta/src/percona/percona-server/cmake
-- MySQL 8.0.46-37
-- Source directory /run/media/sveta/data/src/percona/percona-server
-- Binary directory /run/media/sveta/data/src/percona/percona-server
CMake Error at CMakeLists.txt:650 (MESSAGE):
  Please do not build in-source.  Out-of source builds are highly
  recommended: you can have multiple builds for the same source, and there is
  an easy way to do cleanup, simply remove the build directory (note that
  'make clean' or 'make distclean' does *not* work)

  You *can* force in-source build by invoking cmake with
  -DFORCE_INSOURCE_BUILD=1


-- Configuring incomplete, errors occurred!

[svetasmirnova]

You have to do this way:

-DDOWNLOAD_BOOST=1 -DWITH_BOOST=build/boost

Otherwise, the build would not find boost if you hit an error and will have to run cmake second time.

In my environments I also use option -DDOWNLOAD_BOOST_TIMEOUT=1800, otherwise download fails. This happens even on high speed Internet connections, so this is location thing or so.

[svetasmirnova]

And everywhere else you suggest running:

mkdir build && cd build && cmake ..

[svetasmirnova]

Shouldn't be {{vers}} instead of 8.4?

[svetasmirnova]

Where would I find a list of "others for MyRocks and XtraDB"?

[svetasmirnova]

As I wrote earlier, you have to pass both -DDOWNLOAD_BOOST and -DWITH_BOOST, so cmake is able to find downloaded Boost.

[svetasmirnova]

Shouldn't be {{vers}} instead of 8.4?