从源代码构建

概述

从源代码构建 VillageSQL 可让您获得最新功能，并允许您根据特定环境自定义构建。以下步骤基于上游 MySQL 8.4 构建 VillageSQL。VillageSQL 也可以基于 Percona Server 构建，作为一个替代代码库——请参阅 Percona 构建页面。

前置条件

在开始之前，请确保已安装以下内容：

Git - 用于克隆代码仓库
受支持的平台 - Debian 或 Ubuntu Linux，或安装了 Homebrew 的 macOS

该代码仓库附带一个脚本，用于安装构建所需的 CMake 和开发库。在 Linux 上，它还会安装编译器；在 macOS 上，编译器由 Xcode Command Line Tools 提供。步骤 2 会运行该脚本，因此您无需自行安装这些软件包。

步骤 1：克隆代码仓库

从 GitHub 克隆 VillageSQL Server 代码仓库。将其克隆到主目录中，以便后续 CMake 步骤无需修改即可正常工作：

cd "$HOME"
git clone --depth 1 https://github.com/villagesql/villagesql-server.git
cd villagesql-server

要构建某个发布版本交付的确切代码，请克隆标记该版本的标签而不是分支：-b publish/mysql-8.4_0.0.7。

由于包含 MySQL 代码库，该仓库体积达数 GB。

步骤 2：安装构建依赖项

在您刚刚克隆的代码仓库中运行安装脚本。该脚本会检测您的操作系统并安装构建所需的软件包：

cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh

在 Linux 上，该脚本使用 apt-get 并会请求 sudo 权限。在 macOS 上，它使用 Homebrew。 VillageSQL CI 使用同一个脚本安装其构建依赖项，因此软件包列表始终与构建保持同步。

该脚本支持 Debian 或 Ubuntu Linux 以及 macOS。在其他 Linux 发行版上，请阅读 villagesql/bld_tools/setup_linux_build_env.sh，并使用您自己的软件包管理器安装等效的软件包。

步骤 3：使用 CMake 进行配置

在仓库外部创建构建目录并配置项目：

# Create build directory (outside the repo)
mkdir -p "$HOME/build/villagesql"
cd "$HOME/build/villagesql"

# Configure with CMake
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql"

在 macOS 上，还需要指定 OpenSSL 3 的目录。Homebrew 不带版本号的 openssl 现在是 OpenSSL 4，而服务器无法针对 OpenSSL 4 构建：

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
  -DWITH_SSL="$(brew --prefix openssl@3)"

在两个平台上，路径均使用 $HOME 而非 ~。shell 仅在单词开头展开 ~，因此 --datadir=~/mysql-data/data 传递给 mysqld 时会成为一个名称就是 ~ 的目录，服务器随即中止。使用 "$HOME/..." 加引号还能在您的主目录名称包含空格时保持路径完整。如果路径不同，请将仓库路径替换为您实际的克隆位置。

解释 CMake 选项

"$HOME/villagesql-server" - 已克隆的 VillageSQL 仓库路径
-DWITH_DEBUG=1 - 启用 DBUG 机制和断言的非优化构建（推荐用于开发）
-DCMAKE_INSTALL_PREFIX="$HOME/mysql" - 设置安装目录
-DWITH_SSL="$(brew --prefix openssl@3)" - 让 cmake 使用 OpenSSL 3。步骤 2 会安装 openssl@3。如果跳过了步骤 2，请先运行 brew install openssl@3，因为即使软件包不存在，brew --prefix openssl@3 也会输出一个路径，cmake 随后会以 Wrong option or path for WITH_SSL= 停止。

其他 CMake 选项

生产环境构建：

cmake "$HOME/villagesql-server" -DCMAKE_INSTALL_PREFIX=/usr/local/mysql

使用自定义编译注释：

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"

如果需要重新配置，请先清除 CMake 缓存（在构建目录内运行）：

rm CMakeCache.txt

步骤 4：编译代码

使用 make 进行并行编译以构建 VillageSQL。在构建目录内执行： 构建全部内容（推荐）：

make -j10

此命令会构建服务器、步骤 7中用于连接的 mysql 客户端、扩展 SDK 以及示例扩展的 VEB 文件。 仅构建服务器和客户端：

make -j10 mysqld mysql

这一组合速度更快，但不会构建扩展 SDK 和示例 VEB 文件，因此 INSTALL EXTENSION vsql_complex 找不到可安装的扩展包，传递 -DVillageSQL_BUILD_DIR 的扩展构建也找不到 SDK。

根据您的 CPU 核心数调整并行度（-j10）。从总核心数中减去 2-4 以保持系统响应灵敏。例如，在 12 核机器上，使用 -j10。

完成后，验证服务器和客户端二进制文件是否已构建：

ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"

步骤 5：初始化数据库

在首次启动服务器之前，初始化数据目录：生产环境（生成密码 - 推荐）：

mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

开发环境（无密码 - 可选）：

mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

以 root 用户运行（Docker 或 sudo）： 如果以 root 用户运行（例如在 Docker 中），MySQL 需要 --user=root 参数：

# Initialize as root
"$HOME/build/villagesql/bin/mysqld" --user=root --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

对于类生产环境设置，请使用 --initialize（带密码）。仅在本地开发和测试时使用 --initialize-insecure（无密码）。使用 --initialize 时，将生成一个临时密码并打印到控制台：A temporary password is generated for root@localhost: <password>

通过检查系统数据库是否已创建来验证初始化是否成功：

ls "$HOME/mysql-data/data/mysql"

步骤 6：启动服务器

启动 VillageSQL 服务器：

"$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

以 root 用户运行（Docker 或 sudo）：

"$HOME/build/villagesql/bin/mysqld" --user=root --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

--gdb 参数会解除对 SIGINT 的屏蔽，因此在终端中运行时按 Ctrl-C 即可停止服务器。它还会抑制崩溃回溯并使 --core-file 失效，所以如果您需要崩溃报告，请不要使用该参数。若要在后台运行，请在 mysqld 命令中添加 --daemonize。

步骤 7：使用 MySQL 客户端连接

打开新终端并使用 MySQL 客户端连接到服务器：如果使用 —initialize-insecure（无密码）：

"$HOME/build/villagesql/bin/mysql" -u root

如果使用 —initialize（带生成的密码）：

"$HOME/build/villagesql/bin/mysql" -u root -p
# Enter the temporary password printed during initialization

您应该会看到 MySQL 提示符：

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: <version> Source distribution

mysql>

更改 root 密码

如果您使用了 --initialize，请更改临时密码：

SET PASSWORD = 'your-secure-password';

验证安装

检查您是否正在运行 VillageSQL：

SELECT VERSION();

开发版构建的版本字符串中包含 git 提交哈希：

8.4.11-villagesql-0.0.7-dev-689c74a9-debug

步骤 8：设置用户和数据库

创建开发用户

用于日常开发，请创建一个非 root 用户：

-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

-- Grant all privileges
GRANT ALL PRIVILEGES ON *.* TO developer;

退出并以新用户的身份重新连接：

# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p

创建数据库

CREATE DATABASE my_database;
USE my_database;

连接到特定数据库：mysql -u developer -p -D my_database

步骤 9：运行测试

在构建目录中，使用 VillageSQL 测试套件验证构建：

cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto

--nounit-tests 会跳过上游 MySQL 的单元测试，其中包含已知的失败。请单独运行 VillageSQL 的单元测试：

make -j10 villagesql-unit-tests && ctest -L villagesql

任一命令在有测试失败时都会以非零状态退出。如需进行 GDB 调试、运行单个测试、重新记录预期结果或为服务器代码库做出贡献，请参阅服务器开发指南。

构建原生软件包（RPM/DEB）

villagesql/bld_tools/build_deb.sh 和 build_rpm.sh 直接从源代码树构建 Debian 或 RPM 软件包，以便使用您的软件包管理器安装，而不必按照上面的手动步骤操作。两者都不需要事先运行 CMake 配置——它们都从仓库根目录的 VSQL_VERSION 和 MYSQL_VERSION 文件中得出软件包版本。在已完成步骤 1-2 的情况下，安装打包工具以及步骤 2 未涵盖的构建依赖项——在 Debian/Ubuntu 上为 dpkg-dev、debhelper、libcurl4-openssl-dev、libsystemd-dev 和 systemd-dev；在 Enterprise Linux 上为 rpm-build——然后从仓库根目录运行其中一个：

cd "$HOME/villagesql-server"
villagesql/bld_tools/build_deb.sh   # writes to ./debs
# or
villagesql/bld_tools/build_rpm.sh   # writes to ./rpms

根据添加了此工具的 villagesql-server#931，生成的软件包会接管目标主机上已有的 MySQL 安装，而不是与之并行安装。

故障排除

构建因缺少依赖项而失败

请再次运行安装脚本。步骤 3会让您停留在构建目录中，因此请使用该脚本的绝对路径：

"$HOME/villagesql-server/villagesql/bld_tools/setup_build_env.sh"

请查看错误消息以获取具体缺失的库信息。

服务器无法启动

验证数据目录是否已初始化：ls "$HOME/mysql-data/data/"
检查是否有其他 MySQL/VillageSQL 实例正在使用 3306 端口
阅读 mysqld 在其终端中打印的消息，或使用 --log-error="$HOME/mysql-data/error.log" 启动它并阅读该文件

扩展安装失败

确保扩展的 .veb 文件存在于 veb_dir 目录中（源代码构建为 $HOME/build/villagesql/lib/veb），并且其库在 Linux 和 macOS 上都命名为 <extension_name>.so
检查 VillageSQL 是否具有加载扩展所需的权限
验证扩展名称和 .veb 文件名是否正确

后续步骤

使用扩展

了解如何安装、更新和管理 VillageSQL 扩展。

创建扩展

为 VillageSQL 构建您自己的自定义扩展。

快速入门

VillageSQL 快速入门指南。

Getting Started

Server Development

Using Extensions

Creating Extensions

概述

前置条件

步骤 1：克隆代码仓库

步骤 2：安装构建依赖项

步骤 3：使用 CMake 进行配置

解释 CMake 选项

其他 CMake 选项

步骤 4：编译代码

步骤 5：初始化数据库

步骤 6：启动服务器

步骤 7：使用 MySQL 客户端连接

更改 root 密码

验证安装

步骤 8：设置用户和数据库

创建开发用户

创建数据库

步骤 9：运行测试

构建原生软件包（RPM/DEB）

故障排除

构建因缺少依赖项而失败

服务器无法启动

扩展安装失败

后续步骤

使用扩展

创建扩展

快速入门

​概述

​前置条件

​步骤 1：克隆代码仓库

​步骤 2：安装构建依赖项

​步骤 3：使用 CMake 进行配置

​解释 CMake 选项

​其他 CMake 选项

​步骤 4：编译代码

​步骤 5：初始化数据库

​步骤 6：启动服务器

​步骤 7：使用 MySQL 客户端连接

​更改 root 密码

​验证安装

​步骤 8：设置用户和数据库

​创建开发用户

​创建数据库

​步骤 9：运行测试

​构建原生软件包（RPM/DEB）

​故障排除

​构建因缺少依赖项而失败

​服务器无法启动

​扩展安装失败

​后续步骤

使用扩展

创建扩展

快速入门

概述

前置条件

步骤 1：克隆代码仓库

步骤 2：安装构建依赖项

步骤 3：使用 CMake 进行配置

解释 CMake 选项

其他 CMake 选项

步骤 4：编译代码

步骤 5：初始化数据库

步骤 6：启动服务器

步骤 7：使用 MySQL 客户端连接

更改 root 密码

验证安装

步骤 8：设置用户和数据库

创建开发用户

创建数据库

步骤 9：运行测试

构建原生软件包（RPM/DEB）

故障排除

构建因缺少依赖项而失败

服务器无法启动

扩展安装失败

后续步骤