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

	modified:   docs/compile-percona-server.md

Author: patrickbirch

docs/compile-percona-server.md

@@ -2,20 +2,96 @@
 
 The following instructions install Percona Server for MySQL {{vers}}.
 
-## Install Percona Server for MySQL from the Git Source Tree
+## When to use this guide
 
-Percona uses the [Github :octicons-link-external-16:](https://github.com/) revision
-control system for development. To build the latest Percona Server for MySQL
-from the source tree, you will need `git` installed on your system.
+Use this guide when you need a custom or debug build from source (for example, to test patches or build with non-default options).
 
-You can now fetch the latest Percona Server for MySQL {{vers}} sources.
+For creating packages (RPM, DEB) or repeatable production builds, Percona provides automated build and packaging tooling that installs dependencies and produces installable packages; see [Build APT packages](build-apt-packages.md) and the Percona Server source repository for those workflows.
+
+Warning: A manual source build does not match the performance or security profile of official Percona binaries. Release builds use Profile-Guided Optimization (PGO), Link-Time Optimization (LTO), and hardened compiler flags.
+
+Treat a custom-compiled binary as suitable for development or testing, not as a drop-in production replacement for official packages.
+
+## Installation prerequisites
+
+The build requires a fixed set of dependencies. Install the packages for your platform before running CMake so that configuration and compilation succeed without discovering missing libraries one at a time.
+
+Toolchain: Percona Server {{vers}} uses modern C++ and requires a minimum glibc version and a modern linker (binutils). Having "GCC 11+" is not enough: on many systems a newer GCC is installed from a side-repo (for example, Software Collections) while the system linker stays old; the linker is what resolves C++20 symbols, and an old linker can cause a build failure in the final link phase after hours of compilation.
+
+Check glibc: run `ldd --version` and compare the reported version to the minimum required for {{vers}} (see Percona Server {{vers}} release notes or build documentation). Check linker: run `ld --version` (or `ld.bfd --version`) and ensure the linker meets the requirement for {{vers}}.
+
+On older LTS distros (for example, RHEL 7/8 with default or SCL toolchain), a late failure is often glibc or linker; use a distribution and full toolchain that Percona documents as supported.
+
+RHEL, CentOS, Rocky, Alma, Fedora (package manager: `dnf` or `yum`):
+
+```shell
+dnf install cmake gcc gcc-c++ ncurses-devel openssl-devel libudev-devel libaio-devel bison wget curl
+```
+
+Debian, Ubuntu (package manager: `apt`):
+
+```shell
+apt install cmake gcc g++ libncurses-dev libssl-dev libudev-dev libaio-dev bison wget curl
+```
+
+If you will use `-DDOWNLOAD_BOOST=1`, you must have `wget` or `curl` installed and network access during configuration; otherwise the configure step can fail with a network or download error unrelated to C++. The lists below include both so a minimal environment has at least one.
+
+Additional packages may be required depending on optional features (for example, PAM, zlib, MyRocks). For a Percona-specific list that extends the MySQL 8.4 baseline with requirements for XtraDB, MyRocks, and other components, see [Percona Server for MySQL {{vers}} source installation prerequisites](source-installation-prerequisites.md). The [MySQL 8.4 Source Installation Prerequisites](https://dev.mysql.com/doc/refman/8.4/en/source-installation-prerequisites.html) page remains the upstream baseline reference.
+
+If CMake reports a "library not found" or similar error for a dependency not listed in the prerequisites doc, check the Percona Server source repository or CMake configuration for that component.
+
+## Install location and overwrite risk
+
+The default install prefix is `/usr/local/mysql` (`CMAKE_INSTALL_PREFIX`). Installing to the default prefix can overwrite or conflict with a package-managed Percona Server or MySQL installation.
+
+To avoid overwriting package-managed installations, set a custom prefix at configure time and use that prefix consistently for `make install`:
+
+```shell
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DCMAKE_INSTALL_PREFIX=/opt/percona-server-{{vers}}
+```
+
+For staged installs (for example, into a package root), set `DESTDIR` when installing. Warning: DESTDIR prepends the entire prefix path. The install layout is not at the root of `DESTDIR`; the full `CMAKE_INSTALL_PREFIX` is replicated under `DESTDIR`.
+
+With `-DCMAKE_INSTALL_PREFIX=/opt/ps-8.4` and `make install DESTDIR=/tmp/stage`, files land at `/tmp/stage/opt/ps-8.4/` (for example, `/tmp/stage/opt/ps-8.4/bin/mysqld`), not at `/tmp/stage/bin/`. A beginner often expects everything under `/tmp/stage/` and may assume the build failed when the binaries are not there. Do not assume the build failed—look inside `/tmp/stage/opt/ps-8.4/` (or whatever prefix you set). Plan packaging and copy steps around that path.
+
+```shell
+make -j<N> install DESTDIR=/path/to/package/root
+```
+
+## Obtain the source
+
+You can build from a Git clone (when the build machine has network access to GitHub) or from a source tarball (the standard way on air-gapped or proxy-restricted build servers).
+
+### Build from a source tarball (offline or restricted network)
+
+Many enterprise build servers cannot run `git clone` (proxy restrictions, no outbound access, or no git). In that case, obtain a source tarball on a machine that can download or build the tarball, transfer the tarball to the build machine, then configure and build there.
+
+- Download a Percona Server source tarball from [Percona downloads](https://www.percona.com/downloads/Percona-Server-{{vers}}), or  
+- On a machine with a full clone, generate a tarball: from the repo root run `cmake . && make dist` and use the resulting tarball.
+
+On the build machine, extract the tarball and use the same out-of-source configure and build steps as below (create a build directory inside the extracted tree, run `cmake ..` from there, then `make` and `make install`).
+
+No git is required on the build machine.
+
+### Build from the Git source tree
+
+Percona uses the [Github :octicons-link-external-16:](https://github.com/) revision control system for development. To build from git you need `git` installed and the build machine able to reach GitHub (or a mirror).
+
+Fetch the latest Percona Server for MySQL {{vers}} sources. To avoid pulling the full repository history (which is large in size and bandwidth), clone only the {{vers}} branch with a shallow clone:
+
+```shell
+git clone --branch {{vers}} --depth 1 https://github.com/percona/percona-server.git
+cd percona-server
+git submodule update --init
+```
+
+If you need full history (for example, to generate a source tarball or inspect past commits), use a normal clone and then checkout the branch:
 
 ```shell
 git clone https://github.com/percona/percona-server.git
 cd percona-server
 git checkout {{vers}}
-git submodule init
-git submodule update
+git submodule update --init
 ```
 
 If you are going to be making changes to Percona Server for MySQL {{vers}} and wanting
@@ -31,29 +107,91 @@ After either fetching the source repository or extracting a source tarball
 (from Percona or one you generated yourself), you will now need to
 configure and build Percona Server for MySQL.
 
-First, run CMake to configure the build. Here you can specify all the normal
-build options as you do for a normal MySQL build. Depending on what
-options you wish to compile Percona Server for MySQL with, you may need other
-libraries installed on your system. Here is an example using a
-configure line similar to the options that Percona uses to produce
-binaries:
+First, run CMake to configure the build. You can specify build options as for a normal MySQL build.
+
+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*.
+
+Boost: Percona Server {{vers}} requires a specific Boost version (defined in the source tree). If the system Boost is different (for example, 1.8x when the tree expects 1.77), CMake will fail or produce an incompatible build.
+
+To avoid version mismatches, use one of:
+
+- Let CMake download the correct Boost: add `-DDOWNLOAD_BOOST=1` to the `cmake` command. The DOWNLOAD_BOOST option requires `wget` or `curl` installed and working network access during configuration. In restricted or containerized environments (no network, or no wget/curl), the configure step can fail with a network or download error; in that case use a local Boost (next bullet) or install the required Boost via the system package manager.
+- Use a local Boost tree: add `-DWITH_BOOST=/path/to/boost` (must be the version required by the source).
+
+Do not rely on a single hardcoded Boost path or version in documentation; check the source or CMake output for the exact version required.
+
+Out-of-source build — the only supported approach. Understanding the separation between source and output is the only way to avoid a poisoned environment.
+
+The pipeline is:
+
+- Source tree — the "holy" directory. Never run `cmake` in the source tree; keep the source tree pristine and free of CMake or build artifacts.
+- Build directory — the "scrap heap." Configuration and object files and cache live here; delete the build directory to reset the build.
+- Install prefix — the "final product." The install prefix is where the built binaries and support files actually live and run (for example, `/opt/percona-server-{{vers}}`).
+
+From the repository root, use the following exact sequence:
 
 ```shell
-cmake . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DFEATURE_SET=community
+mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release
 ```
 
+Do not run `cmake .` in the source root; that writes generated files into the source tree and is hard to undo safely.
+
+If CMake reports a Boost version mismatch, add `-DDOWNLOAD_BOOST=1` to the `cmake` command so the correct Boost is downloaded automatically.
+
+On newer platforms or distros, if you hit compilation errors that are
+Linux-distro dependent, add `-DWITH_PACKAGE_FLAGS=OFF`:
+
+```shell
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DWITH_PACKAGE_FLAGS=OFF
+```
+
+Recovery from a poisoned source tree: If you ran `cmake .` in the source root by mistake, CMake and build artifacts are now in the source tree; `make clean` does not fully reset CMake state.
+
+Safest recovery: remove only the known generated files so you do not touch local patches or config. From the repository root, remove (for example) `CMakeCache.txt`, the `CMakeFiles/` directory, `cmake_install.cmake`, and `Makefile` (and any other files or directories CMake created in the root). After that you can run the out-of-source sequence from a clean state.
+
+Only if you are certain there are no untracked local changes, you can instead run `git clean -xfd` to remove all untracked and ignored files—but the command permanently deletes every file not tracked by git, including uncommitted work; the command is as destructive as the problem the command fixes.
+
+With an out-of-source build, recovery is simple: delete the build directory (for example, `rm -rf build`) and run the `mkdir build && cd build && cmake ..` sequence again; the source tree is unchanged.
+
 ## Compile from source
 
-Now, compile using make:
+Compile using make from the build directory. Do not use `make -j$(nproc)`.
+
+Compilation can use 2 GB or more of RAM per job, and the final link of `mysqld`—the last few percent of the build—can spike to 4 GB or more in a single job, regardless of core count. On a 32-core machine with 16 GB RAM, `-j32` would direct 32 compile jobs plus the link; that combination commonly causes swap storms or OOM.
+
+Use a fixed cap instead: at most N jobs where N is the smaller of (physical RAM in GB ÷ 2) and 8. With 8 GB RAM use `make -j4` or lower; with 16 GB or more, `make -j8` is a safe upper bound. When in doubt use `make -j2` or plain `make` (single job).
 
 ```shell
-make
+make -j4
 ```
 
-Install:
+If the build is killed by the OOM killer or the system thrashes, reduce the job count (for example, `make -j2`) or run `make` with no `-j` and try again.
+
+Install (use the same `-j` value as for the build, or a lower one if install fails due to memory):
 
 ```shell
-make install
+make -j4 install
 ```
 
-Percona Server for MySQL {{vers}} is installed on your system.
+The binaries are now under the install prefix, but compiling is only part of the process. You must initialize the data directory and set up how to start the server; otherwise you will have a binary in (for example) `/opt` and no way to run a database service.
+
+Initialize the data directory: The server does not run until the data directory is initialized. From the install prefix (or with `--basedir` and `--datadir` set), run `mysqld --initialize` or `mysqld --initialize-insecure` as the user that will run the server. See [Post-installation](post-installation.md) for the full steps (create a datadir, set permissions, run the initialize command, retrieve the temporary root password if you used `--initialize`).
+
+Starting the server and systemd/init: Package installations provide a systemd unit (or init script) that starts `mysqld` from the default path. A custom-prefix install (for example, `/opt/percona-server-{{vers}}`) is not managed by that unit. You must create or adapt a systemd unit file (or init script) so that `ExecStart` (or the equivalent) points to the actual binary path—for example, `/opt/percona-server-{{vers}}/bin/mysqld`—and so that `basedir` and `datadir` match your layout. Without that, the system service manager will not start your custom-built server. See your distribution’s documentation for creating a systemd service and [Post-installation](post-installation.md) for running and testing the server.
+
+## Maintaining a source build
+
+By building from source you opt out of package-manager updates (`dnf update` / `apt upgrade`). You become the release engineer and your own security officer: you must track Percona security and release announcements and re-pull, re-patch, and re-compile when CVEs or releases affect your version.
+
+A source build is a snapshot in time; without that discipline, a "quickstart" becomes a long-term liability. If you forget to re-pull and re-patch when CVEs are released, you are running known-vulnerable software; official packages receive security updates automatically. Subscribe to Percona security announcements and plan to rebuild when advisories affect Percona Server {{vers}}.
+
+Applying updates: Obtain fresh source (for example, `git pull` and `git submodule update` in a clone, or a new source tarball). Then:
+
+- Incremental build: If you only pulled new commits and did not change CMake options or switch major versions, re-run `make` (and `make install`) from the existing build directory. No need to delete the build dir or re-run CMake; the incremental build is the normal path for security and minor updates.
+- Full reconfigure: If you changed CMake options, switched branch or major version, or see odd build errors after pulling, remove the build directory (`rm -rf build`), run the `mkdir build && cd build && cmake ..` sequence again with the same options, then `make` and `make install`.
+
+Keep configuration files (for example, `my.cnf`) and data directories outside the install prefix; reinstalling then overwrites only the binaries and leaves your config and data intact.
+
+Use a stable custom prefix and config/datadir paths so upgrades are predictable.