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

[patrickbirch]

modified:   docs/compile-percona-server.md

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

[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]

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]

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?