You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The following instructions install Percona Server for MySQL {{vers}}.
4
4
5
-
## Install Percona Server for MySQL from the Git Source Tree
5
+
## When to use this guide
6
+
7
+
Use this guide when you need a custom or debug build from source (for example, to test patches or build with non-default options). 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.
8
+
9
+
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.
10
+
11
+
## Installation prerequisites
12
+
13
+
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.
14
+
15
+
Toolchain: Percona Server {{vers}} uses modern C++. A recent GCC (or Clang) alone is not enough; the linker (binutils) and glibc must be compatible. The build requires a minimum glibc version (and possibly a minimum binutils version); check the Percona Server {{vers}} release notes or build documentation for the exact requirements. On older LTS distros, a late build failure can be due to glibc or the linker; use a distribution and toolchain that Percona documents as supported for {{vers}}.
16
+
17
+
RHEL, CentOS, Rocky, Alma, Fedora (package manager: `dnf` or `yum`):
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.
30
+
31
+
Additional packages may be required depending on optional features (for example, PAM, zlib). The [MySQL 8.4 Source Installation Prerequisites](https://dev.mysql.com/doc/refman/8.4/en/source-installation-prerequisites.html) list is a baseline only; Percona Server adds features (for example, XtraDB, MyRocks, custom components) that can require libraries not on the upstream list. If CMake reports a "library not found" or similar error for a dependency not listed there, check Percona Server documentation or the source repository for that component.
32
+
33
+
## Install location and overwrite risk
34
+
35
+
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`:
For staged installs (for example, into a package root), set `DESTDIR` when installing. The layout under `DESTDIR` mirrors `CMAKE_INSTALL_PREFIX`: files are not placed at the root of `DESTDIR`. For example, with `-DCMAKE_INSTALL_PREFIX=/opt/percona` and `DESTDIR=/tmp/package`, the server binary ends up at `/tmp/package/opt/percona/bin/mysqld`, not `/tmp/package/bin/mysqld`. Plan your packaging or copy steps accordingly.
42
+
43
+
```shell
44
+
make -j<N> install DESTDIR=/path/to/package/root
45
+
```
46
+
47
+
## Obtain the source
48
+
49
+
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).
50
+
51
+
### Build from a source tarball (offline or restricted network)
52
+
53
+
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 it, transfer the tarball to the build machine, then configure and build there.
54
+
55
+
- Download a Percona Server source tarball from [Percona downloads](https://www.percona.com/downloads/Percona-Server-{{vers}}), or
56
+
- On a machine with a full clone, generate a tarball: from the repo root run `cmake . && make dist` and use the resulting tarball.
57
+
58
+
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.
59
+
60
+
### Build from the Git source tree
6
61
7
62
Percona uses the [Github :octicons-link-external-16:](https://github.com/) revision
8
-
control system for development. To build the latest Percona Server for MySQL
9
-
from the source tree, you will need `git` installed on your system.
63
+
control system for development. To build from git you need `git` installed and the build machine able to reach GitHub (or a mirror).
64
+
65
+
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:
If you are going to be making changes to Percona Server for MySQL {{vers}} and wanting
@@ -31,29 +92,69 @@ After either fetching the source repository or extracting a source tarball
31
92
(from Percona or one you generated yourself), you will now need to
32
93
configure and build Percona Server for MySQL.
33
94
34
-
First, run CMake to configure the build. Here you can specify all the normal
35
-
build options as you do for a normal MySQL build. Depending on what
36
-
options you wish to compile Percona Server for MySQL with, you may need other
37
-
libraries installed on your system. Here is an example using a
38
-
configure line similar to the options that Percona uses to produce
39
-
binaries:
95
+
First, run CMake to configure the build. You can specify build options as for a normal MySQL build.
96
+
97
+
Note: `-DFEATURE_SET=community` is not supported in {{vers}}. If you use
98
+
`-DFEATURE_SET=community`, CMake will report: *Manually-specified variables were not used by the project:
99
+
FEATURE_SET*.
100
+
101
+
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:
102
+
103
+
- Let CMake download the correct Boost: add `-DDOWNLOAD_BOOST=1` to the `cmake` command. This 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.
104
+
- Use a local Boost tree: add `-DWITH_BOOST=/path/to/boost` (must be the version required by the source).
105
+
106
+
Do not rely on a single hardcoded Boost path or version in documentation; check the source or CMake output for the exact version required.
107
+
108
+
Out-of-source build — the only supported approach. Keep the source tree pristine and do all configuration and compilation in a separate build directory. The pipeline is:
109
+
110
+
-**Source tree** — kept pristine; no CMake or build artifacts.
111
+
-**Build directory** — where CMake runs and where object files, cache, and the "mess" live.
112
+
-**Install prefix** — the final destination for binaries and support files (for example, `/opt/percona-server-{{vers}}`).
113
+
114
+
From the repository root, use this exact sequence:
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 that command permanently deletes every file not tracked by git, including uncommitted work; it is as destructive as the problem it 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.
132
+
45
133
## Compile from source
46
134
47
-
Now, compile using make:
135
+
Compile using make from the build directory. A single GCC compile of a large C++ file in this codebase can use 2 GB or more of RAM per job. Linking the final `mysqld` binary is a heavy serial step that can consume a large amount of RAM; parallelism is not linear, and using `-j$(nproc)` on a many-core machine (for example, 32 cores) with limited RAM will often trigger swap storms or OOM during the link phase. Do not use `make -j$(nproc)` unless you have ample physical RAM. Prefer a conservative cap: use at most N jobs where N is the smaller of (physical RAM in GB ÷ 2) and 8—for example, `make -j4` or `make -j8`. With 8 GB physical RAM, use `make -j4` or lower; with 16 GB or more, `make -j8` is a reasonable upper bound. When in doubt use `make -j2` or plain `make` (single job).
48
136
49
137
```shell
50
-
make
138
+
make -j4
51
139
```
52
140
53
-
Install:
141
+
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.
142
+
143
+
Install (use the same `-j` value as for the build, or a lower one if install fails due to memory):
54
144
55
145
```shell
56
-
make install
146
+
make -j4 install
57
147
```
58
148
59
149
Percona Server for MySQL {{vers}} is installed on your system.
150
+
151
+
## Maintaining a source build
152
+
153
+
By building from source you opt out of package-manager updates (`dnf update` / `apt upgrade`). You become the release engineer: you must track Percona security and release announcements and apply updates yourself. A source build is a snapshot in time; without a process to pull and rebuild, you are effectively running an unpatched tree and taking on maintenance and security risk.
154
+
155
+
**Applying updates:** Obtain fresh source (for example, `git pull` and `git submodule update` in a clone, or a new source tarball). Then:
156
+
157
+
-**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; this is the normal path for security and minor updates.
158
+
-**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`.
159
+
160
+
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.
0 commit comments