Skip to content

Commit f302380

Browse files
patrickbirchpatrickbirch
committed
PS-9608 [DOCS] - How to build RPM packages from PS source code
 On branch ps-9608 new file: docs/build-rpm-packages.md
1 parent 77fd55e commit f302380

File tree

2 files changed

+358
-0
lines changed

2 files changed

+358
-0
lines changed

‎docs/build-rpm-packages.md

+357
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,357 @@
1+
# Build from RPM packages
2+
3+
This guide provides step-by-step instructions for building Percona Server for MySQL from source and packaging it as an RPM package. The guide covers setting up the build environment, downloading the source code, creating a SPEC file, building the RPM package, and verifying the installation.
4+
5+
## Prerequisites
6+
7+
Install the required build dependencies:
8+
9+
```{.bash data-prompt="$"}
10+
# Install build dependencies
11+
$ sudo yum groupinstall "Development Tools"
12+
$ sudo yum install \
13+
cmake \
14+
openssl-devel \
15+
libaio-devel \
16+
ncurses-devel \
17+
boost-devel \
18+
rpmdevtools \
19+
rpmlint \
20+
systemd-devel \
21+
vim-common
22+
```
23+
24+
On newer RHEL-based distributions, use the `dnf` package manager:
25+
26+
```{.bash data-prompt="$"}
27+
# Install build dependencies
28+
$ sudo dnf groupinstall "Development Tools"
29+
$ sudo dnf install \
30+
cmake \
31+
openssl-devel \
32+
libaio-devel \
33+
ncurses-devel \
34+
boost-devel \
35+
rpmdevtools \
36+
rpmlint \
37+
systemd-devel \
38+
vim-common
39+
```
40+
41+
The `yum groupinstall` command installs a group of development tools using the yum package manager. The "Development Tools" group includes essential compilers, debuggers, and other tools required for building software.
42+
43+
The `yum install` command installs additional packages required for building Percona Server for MySQL. These packages include CMake, OpenSSL development libraries, libaio development libraries, ncurses development libraries, Boost development libraries, rpmdevtools, rpmlint, systemd development libraries, and vim-common.
44+
45+
## Setup RPM build environment
46+
47+
These commands set up the necessary directory structure for building RPM packages.
48+
49+
```{.bash data-prompt="$"}
50+
# Create RPM build directory structure
51+
$ rpmdev-setuptree
52+
```
53+
54+
```text
55+
# Directory structure created:
56+
# ~/rpmbuild/
57+
# ├── BUILD
58+
# ├── RPMS
59+
# ├── SOURCES
60+
# ├── SPECS
61+
# └── SRPMS
62+
```
63+
64+
The `rpmdev-setuptree` command creates the necessary directory structure for building RPM packages. The structure includes the following directories:
65+
66+
* `BUILD`: Where the build process takes place.
67+
68+
* `RPMS`: Where the finished RPM packages are stored.
69+
70+
* `SOURCES`: Where the source tarballs and other sources are stored.
71+
72+
* `SPECS`: Where the SPEC files are stored.
73+
74+
* `SRPMS`: Where the source RPM packages are stored.
75+
76+
## Download and prepare source
77+
78+
These commands help you download the necessary source files and libraries required to build Percona Server for MySQL.
79+
80+
```{.bash data-prompt="$"}
81+
# Download Percona Server source
82+
$ cd ~/rpmbuild/SOURCES
83+
$ wget https://downloads.percona.com/downloads/Percona-Server-8.0/Percona-Server-{{release}}/source/tarball/percona-server-{{tag}}.tar.gz
84+
```
85+
86+
Change to the `SOURCES` directory within your rpmbuild environment using the cd command. Then, use the `wget` command to download the Percona Server source tarball from the specified URL. This tarball contains the source code needed to build Percona Server.
87+
88+
```{.bash data-prompt="$"}
89+
# Download boost if not included
90+
$ wget https://boostorg.jfrog.io/artifactory/main/release/1.77.0/source/boost_1_77_0.tar.gz
91+
```
92+
93+
Use the `wget` command to download the Boost library tarball from the specified URL. Boost provides a set of libraries that help with various programming tasks, and you need it for building Percona Server if it's not already included in the source.
94+
95+
## Create SPEC file
96+
97+
This SPEC file automates the process of building, installing, and packaging Percona Server for MySQL into an RPM package, ensuring that all necessary steps and dependencies are properly managed.
98+
99+
Create `~/rpmbuild/SPECS/percona-server-8.0.spec`:
100+
101+
```text
102+
%define mysql_version {{tag}}
103+
%define rpm_version {{tag}}
104+
105+
Name: percona-server
106+
Version: %{mysql_version}
107+
Release: 1%{?dist}
108+
Summary: Percona Server for MySQL
109+
License: GPL-2.0
110+
111+
Source0: percona-server-%{mysql_version}.tar.gz
112+
Source1: boost_1_77_0.tar.gz
113+
114+
BuildRequires: cmake
115+
BuildRequires: openssl-devel
116+
BuildRequires: libaio-devel
117+
BuildRequires: ncurses-devel
118+
BuildRequires: systemd-devel
119+
BuildRequires: boost-devel
120+
121+
%description
122+
Percona Server for MySQL is a free, fully compatible, enhanced, and open source drop-in replacement for MySQL.
123+
124+
%prep
125+
%setup -q -n percona-server-%{mysql_version}
126+
127+
%build
128+
mkdir build
129+
cd build
130+
cmake .. \
131+
-DCMAKE_INSTALL_PREFIX=/usr \
132+
-DINSTALL_LAYOUT=RPM \
133+
-DWITH_SSL=system \
134+
-DWITH_BOOST=../../boost_1_77_0 \
135+
-DWITH_SYSTEMD=1
136+
137+
make %{?_smp_mflags}
138+
139+
%install
140+
cd build
141+
make DESTDIR=%{buildroot} install
142+
143+
%files
144+
%{_bindir}/*
145+
%{_sbindir}/*
146+
%{_libdir}/*
147+
%{_datadir}/*
148+
%{_sysconfdir}/*
149+
%{_unitdir}/*
150+
151+
%post
152+
/sbin/ldconfig
153+
%systemd_post mysqld.service
154+
155+
%preun
156+
%systemd_preun mysqld.service
157+
158+
%postun
159+
/sbin/ldconfig
160+
%systemd_postun_with_restart mysqld.service
161+
```
162+
163+
The provided SPEC file outlines the instructions to build and package Percona Server for MySQL as an RPM package. Here's a breakdown of what each section does:
164+
165+
1. **Definitions**:
166+
```plaintext
167+
%define mysql_version 8.0.40
168+
%define rpm_version 8.0.40
169+
```
170+
These lines define variables for the MySQL and RPM version numbers.
171+
172+
2. **Package Information**:
173+
```plaintext
174+
Name: percona-server
175+
Version: %{mysql_version}
176+
Release: 1%{?dist}
177+
Summary: Percona Server for MySQL
178+
License: GPL-2.0
179+
```
180+
This section provides metadata about the package, including its name, version, release number, summary, and license.
181+
182+
3. **Sources**:
183+
```plaintext
184+
Source0: percona-server-%{mysql_version}.tar.gz
185+
Source1: boost_1_77_0.tar.gz
186+
```
187+
These lines specify the source tarballs needed to build the package.
188+
189+
4. **Build Requirements**:
190+
```plaintext
191+
BuildRequires: cmake
192+
BuildRequires: openssl-devel
193+
BuildRequires: libaio-devel
194+
BuildRequires: ncurses-devel
195+
BuildRequires: systemd-devel
196+
BuildRequires: boost-devel
197+
```
198+
This section lists the packages required to build the software.
199+
200+
5. **Description**:
201+
```plaintext
202+
%description
203+
Percona Server for MySQL is a free, fully compatible, enhanced, and open source drop-in replacement for MySQL.
204+
```
205+
A brief description of the package.
206+
207+
6. **Preparation**:
208+
```plaintext
209+
%prep
210+
%setup -q -n percona-server-%{mysql_version}
211+
```
212+
This section sets up the build environment by extracting the source tarball.
213+
214+
7. **Build**:
215+
```plaintext
216+
%build
217+
mkdir build
218+
cd build
219+
cmake .. \
220+
-DCMAKE_INSTALL_PREFIX=/usr \
221+
-DINSTALL_LAYOUT=RPM \
222+
-DWITH_SSL=system \
223+
-DWITH_BOOST=../../boost_1_77_0 \
224+
-DWITH_SYSTEMD=1
225+
make %{?_smp_mflags}
226+
```
227+
This section compiles the software using CMake and Make, with specific build options.
228+
229+
8. **Installation**:
230+
```plaintext
231+
%install
232+
cd build
233+
make DESTDIR=%{buildroot} install
234+
```
235+
This section installs the compiled software into a build root directory.
236+
237+
9. **Files**:
238+
```plaintext
239+
%files
240+
%{_bindir}/*
241+
%{_sbindir}/*
242+
%{_libdir}/*
243+
%{_datadir}/*
244+
%{_sysconfdir}/*
245+
%{_unitdir}/*
246+
```
247+
This section lists the files and directories included in the package.
248+
249+
10. **Post-Installation and Pre-Uninstallation Scripts**:
250+
```plaintext
251+
%post
252+
/sbin/ldconfig
253+
%systemd_post mysqld.service
254+
255+
%preun
256+
%systemd_preun mysqld.service
257+
258+
%postun
259+
/sbin/ldconfig
260+
%systemd_postun_with_restart mysqld.service
261+
```
262+
These scripts handle tasks to be performed after installation and before and after uninstallation, such as updating the shared library cache and managing the `mysqld` service with systemd.
263+
264+
265+
## Build RPM package
266+
267+
These commands help you build and verify RPM packages from a downloaded Percona Server for MySQL tar file. The first command builds the package, while the second command checks the directory to confirm that the packages are created successfully.
268+
269+
```{.bash data-prompt="$"}
270+
# Build the RPM package
271+
$ cd ~/rpmbuild
272+
rpmbuild -ba SPECS/percona-server-8.0.spec
273+
```
274+
275+
First, change to the rpmbuild directory with the `cd` command. Then, use the `rpmbuild -ba` command to build the RPM package based on the percona-server-8.0.spec file located in the SPECS directory. The `-ba` option tells rpmbuild to build both the binary and source RPM packages.
276+
277+
```{.bash data-prompt="$"}
278+
# Check for built packages
279+
$ ls -l RPMS/x86_64/
280+
```
281+
282+
This command lists the contents of the RPMS/x86_64 directory to verify that the built RPM packages are present. The `ls -l` command lists the files in the directory, and the `RPMS/x86_64/` argument specifies the directory to list.
283+
284+
## Important build configuration options
285+
286+
These CMAKE options help configure the build process according to your specific requirements, ensuring that the software is installed and functions correctly on your system.
287+
288+
- `-DCMAKE_INSTALL_PREFIX=/usr`: Installation directory
289+
- `-DINSTALL_LAYOUT=RPM`: RPM-specific installation layout
290+
- `-DWITH_SSL=system`: Use system OpenSSL
291+
- `-DWITH_BOOST`: Path to Boost library
292+
- `-DWITH_SYSTEMD=1`: Enable systemd support
293+
294+
These commands are CMake options used to customize the build process for your project. Here is what each one does:
295+
296+
| Option | Description |
297+
|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
298+
| **`-DCMAKE_INSTALL_PREFIX=/usr`** | This option sets the installation directory to `/usr`. When you install the software, the files will be placed in the `/usr` directory. |
299+
| **`-DINSTALL_LAYOUT=RPM`** | This option specifies the installation layout for RPM packages. It ensures that the files are organized in a way that is compatible with RPM packaging standards. |
300+
| **`-DWITH_SSL=system`** | This option tells CMake to use the system's OpenSSL library. Instead of compiling and using a separate OpenSSL library, it will use the one already installed on your system. |
301+
| **`-DWITH_BOOST`** | This option sets the path to the Boost library. It ensures that CMake can find and use the Boost libraries during the build process. |
302+
| **`-DWITH_SYSTEMD=1`** | This option enables support for systemd, the system and service manager for Linux operating systems. It allows the software to integrate with systemd for service management. |
303+
304+
305+
## Verify
306+
307+
These commands help you verify the integrity of the RPM package and check for any dependencies, and ensures a smooth installation process.
308+
309+
```{.bash data-prompt="$"}
310+
# Check RPM package integrity
311+
$ rpm -Kv RPMS/x86_64/percona-server-*.rpm
312+
```
313+
314+
This command verifies the integrity of the built RPM package. The `-K` option stands for check, and `-v` is for verbose output.
315+
316+
```{.bash data-prompt="$"}
317+
# Check package dependencies
318+
$ rpm -qpR RPMS/x86_64/percona-server-*.rpm
319+
```
320+
321+
This command lists the dependencies required by the built RPM package. The `-qpR` option queries the package for its dependencies.
322+
323+
## Install
324+
325+
These steps help you install and verify the Percona Server package on your system, and ensures everything is set up correctly.
326+
327+
```{.bash data-prompt="$"}
328+
# Install built package
329+
$ sudo rpm -ivh RPMS/x86_64/percona-server-*.rpm
330+
```
331+
332+
This command installs the built Percona Server package. The `-i` option stands for install, `-v` for verbose, and -h shows hash marks as the package installs. Using `sudo` ensures you have the necessary administrative privileges.
333+
334+
# Check the installation
335+
336+
```{.bash data-prompt="$"}
337+
$ rpm -qa | grep percona-server
338+
$ mysqld --version
339+
```
340+
341+
This command has the following options:
342+
343+
`rpm -qa | grep percona-server`: This command lists all installed packages and filters the list to show only those related to Percona Server. The `rpm -qa` command queries all installed RPM packages, and `grep percona-server` searches for Percona Server entries.
344+
345+
`mysqld --version`: This command displays the installed version of the MySQL server, confirming the successful installation of Percona Server.
346+
347+
## Troubleshoot
348+
349+
The following are common issues encountered during the RPM build process:
350+
351+
352+
| Issue | Troubleshooting Steps |
353+
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
354+
| **Missing dependencies** | ```bash $ # Install additional dependencies if needed sudo yum-builddep SPECS/percona-server-8.0.spec ``` |
355+
| **Build failures** | - Check build logs in `~/rpmbuild/BUILD/` <br> - Verify all build dependencies are installed <br> - Ensure enough disk space is available |
356+
| **Version mismatches** | - Double-check version numbers in SPEC file <br> - Verify source tarball version matches SPEC file |
357+

‎mkdocs-base.yml

+1
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,7 @@ nav:
245245
- Use YUM:
246246
- Use RPM repositories: yum-repo.md
247247
- Files in RPM package: yum-files.md
248+
- build-rpm-packages.md
248249
- Downloaded RPM packages: yum-download-rpm.md
249250
- Run Percona Server for MySQL: yum-run.md
250251
- Uninstall: yum-uninstall.md

0 commit comments

Comments
 (0)