从源代码构建

概述

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

前置条件

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

Git - 用于克隆代码仓库
CMake 3.16 或更高版本 - 构建系统生成器
C++ 编译器 - GCC 8+、Clang 8+ 或 MSVC 2019+
构建工具 - make、ninja 或等效工具
开发库 - OpenSSL、ncurses、pkg-config、bison 以及其他 MySQL 依赖项

安装依赖项

Ubuntu/Debian：

sudo apt install cmake libssl-dev libncurses5-dev pkg-config bison \
                 libtirpc-dev rpcsvc-proto build-essential zlib1g-dev

macOS（使用 Homebrew）： 如果尚未安装，请先安装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

然后安装依赖项：

brew install cmake openssl pkgconf bison libtirpc rpcsvc-proto

步骤 1：克隆代码仓库

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

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

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

步骤 2：使用 CMake 进行配置

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

# 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：

# Create build directory (outside the repo)
mkdir -p ~/build/villagesql
cd ~/build/villagesql

# Configure with CMake
cmake ~/villagesql-server -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=~/mysql -DWITH_SSL=system

Linux 用户： 对绝对路径使用 $HOME。macOS 用户： 使用 ~（波浪号）。如果路径不同，请将仓库路径替换为您实际的克隆位置。

解释 CMake 选项

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

其他 CMake 选项

不带调试符号的生产环境构建： Linux：

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

macOS：

cmake ~/villagesql-server -DCMAKE_INSTALL_PREFIX=/usr/local/mysql

使用自定义编译注释： Linux：

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

macOS：

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

具有更严格警告的开发者模式： Linux：

cmake $HOME/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1

macOS：

cmake ~/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1

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

rm CMakeCache.txt

步骤 3：编译代码

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

make -j10 mysqld

构建全部内容：

make -j10

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

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

ls $HOME/build/villagesql/bin/mysqld

macOS：

ls ~/build/villagesql/bin/mysqld

步骤 4：初始化数据库

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

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

macOS： 生产环境（生成密码 - 推荐）：

mkdir -p ~/mysql-data/data
~/build/villagesql/bin/mysqld --initialize --datadir=~/mysql-data/data --basedir=~/build/villagesql

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

mkdir -p ~/mysql-data/data
~/build/villagesql/bin/mysqld --initialize-insecure --datadir=~/mysql-data/data --basedir=~/build/villagesql

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

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

ls $HOME/mysql-data/data/mysql

macOS：

ls ~/mysql-data/data/mysql

步骤 5：启动服务器

启动 VillageSQL 服务器： Linux：

$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

macOS：

~/build/villagesql/bin/mysqld --gdb --datadir=~/mysql-data/data --basedir=~/build/villagesql

--gdb 参数会安装 SIGINT 处理器，以便 Ctrl-C 能够干净地停止服务器 —— 在终端中交互式运行时非常有用。若要在后台运行，请在 mysqld 命令中添加 --daemonize。

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

打开新终端并使用 MySQL 客户端连接到服务器： Linux： 如果使用 —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

macOS： 如果使用 —initialize-insecure（无密码）：

~/build/villagesql/bin/mysql -u root

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

~/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 提交哈希：

8.4.10-villagesql-0.0.5

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

更改 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;

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

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

macOS:

# Ctrl-D to exit
~/build/villagesql/bin/mysql -u developer -p

创建数据库

CREATE DATABASE my_database;
USE my_database;

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

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

故障排除

构建因缺少依赖项而失败

为您的平台安装所需的开发包。请查看错误消息以获取具体缺失的库信息。

服务器无法启动

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

扩展安装失败

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

后续步骤

使用扩展

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

创建扩展

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

快速入门

VillageSQL 快速入门指南。

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

概述

前置条件

安装依赖项

步骤 1：克隆代码仓库

步骤 2：使用 CMake 进行配置

解释 CMake 选项

其他 CMake 选项

步骤 3：编译代码

步骤 4：初始化数据库

步骤 5：启动服务器

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

验证安装

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

更改 root 密码

创建开发用户

创建数据库

故障排除

构建因缺少依赖项而失败

服务器无法启动

扩展安装失败

后续步骤

使用扩展

创建扩展

快速入门

​概述

​前置条件

​安装依赖项

​步骤 1：克隆代码仓库

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

​解释 CMake 选项

​其他 CMake 选项

​步骤 3：编译代码

​步骤 4：初始化数据库

​步骤 5：启动服务器

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

​验证安装

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

​更改 root 密码

​创建开发用户

​创建数据库

​故障排除

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

​服务器无法启动

​扩展安装失败

​后续步骤

使用扩展

创建扩展

快速入门

概述

前置条件

安装依赖项

步骤 1：克隆代码仓库

步骤 2：使用 CMake 进行配置

解释 CMake 选项

其他 CMake 选项

步骤 3：编译代码

步骤 4：初始化数据库

步骤 5：启动服务器

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

验证安装

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

更改 root 密码

创建开发用户

创建数据库

故障排除

构建因缺少依赖项而失败

服务器无法启动

扩展安装失败

后续步骤