从源代码构建

概述

从源代码构建 VillageSQL 可让您获得最新功能，并允许您根据特定环境自定义构建。

前置条件

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

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

该代码仓库附带一个脚本，用于安装构建所需的编译器、CMake 和开发库。步骤 2 会运行该脚本，因此您无需自行安装这些软件包。

步骤 1：克隆代码仓库

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

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

由于包含 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 上，请添加 -DWITH_SSL=system，以便 CMake 找到 Homebrew 提供的 OpenSSL：

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" -DWITH_SSL=system

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

解释 CMake 选项

<path-to-repo> - 已克隆的 VillageSQL 仓库路径
-DWITH_DEBUG=1 - 启用调试符号（推荐用于开发）
-DCMAKE_INSTALL_PREFIX="$HOME/mysql" - 设置安装目录
-DWITH_SSL=system - 使用系统 OpenSSL 库（macOS 必需）

其他 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 "$HOME/villagesql-server" -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1

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

rm CMakeCache.txt

步骤 4：编译代码

使用 make 进行并行编译以构建 VillageSQL。在构建目录内执行： 构建服务器和客户端（推荐用于开发）：

make -j10 mysqld mysql

mysql 目标会构建在步骤 7中用于连接的客户端；仅执行 make -j10 mysqld 只会构建服务器，届时步骤 7 将没有客户端可运行。 构建全部内容：

make -j10

根据您的 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 能够干净地停止服务器 —— 在终端中交互式运行时非常有用。若要在后台运行，请在 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 VillageSQL Server for MySQL monitor.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

验证安装

检查您是否正在运行 VillageSQL：

SELECT VERSION();

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

9.7.2-villagesql-0.0.6-dev-5a64e122090

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

更改 root 密码

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

SET PASSWORD = 'your-secure-password';

创建开发用户

用于日常开发，请创建一个非 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

如需进行 GDB 调试、运行测试或为服务器代码库做出贡献，请参阅服务器开发指南。

故障排除

构建因缺少依赖项而失败

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

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

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

服务器无法启动

验证数据目录是否已初始化：ls "$HOME/mysql-data/data/"
检查是否有其他 MySQL/VillageSQL 实例正在使用 3306 端口
查看 $HOME/mysql-data/data/*.err 中的错误日志

扩展安装失败

确保扩展库（Linux 上为 .so，macOS 上为 .dylib）存在于构建输出目录中
检查 VillageSQL 是否具有加载扩展所需的权限
验证扩展名称和 .veb 文件名是否正确

后续步骤

使用扩展

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

创建扩展

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

快速入门

VillageSQL 快速入门指南。

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

概述

前置条件

步骤 1：克隆代码仓库

步骤 2：安装构建依赖项

步骤 3：使用 CMake 进行配置

解释 CMake 选项

其他 CMake 选项

步骤 4：编译代码

步骤 5：初始化数据库

步骤 6：启动服务器

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

验证安装

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

更改 root 密码

创建开发用户

创建数据库

故障排除

构建因缺少依赖项而失败

服务器无法启动

扩展安装失败

后续步骤

使用扩展

创建扩展

快速入门

​概述

​前置条件

​步骤 1：克隆代码仓库

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

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

​解释 CMake 选项

​其他 CMake 选项

​步骤 4：编译代码

​步骤 5：初始化数据库

​步骤 6：启动服务器

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

​验证安装

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

​更改 root 密码

​创建开发用户

​创建数据库

​故障排除

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

​服务器无法启动

​扩展安装失败

​后续步骤

使用扩展

创建扩展

快速入门

概述

前置条件

步骤 1：克隆代码仓库

步骤 2：安装构建依赖项

步骤 3：使用 CMake 进行配置

解释 CMake 选项

其他 CMake 选项

步骤 4：编译代码

步骤 5：初始化数据库

步骤 6：启动服务器

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

验证安装

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

更改 root 密码

创建开发用户

创建数据库

故障排除

构建因缺少依赖项而失败

服务器无法启动

扩展安装失败

后续步骤