> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 从源代码构建

> 从源代码编译 VillageSQL Server for MySQL 并开始使用扩展。

## 概述

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

以下步骤基于上游 MySQL 8.4 构建 VillageSQL。VillageSQL 也可以基于 Percona Server 构建，作为一个替代代码库——请参阅 [Percona Server 入门](https://villagesql.com/docs/zh/8.4/stable/percona.md)页面。

## 前置条件

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

* **Git** - 用于克隆代码仓库
* **受支持的平台** - Debian 或 Ubuntu Linux，或安装了 [Homebrew](https://brew.sh) 的 macOS

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

## 步骤 1：克隆代码仓库

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

```bash theme={null}
cd "$HOME"
git clone --depth 1 -b publish/mysql-8.4_0.0.7 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```

> [!NOTE]
>
> 由于包含 MySQL 代码库，该仓库体积达数 GB。

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

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

```bash theme={null}
cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh
```

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

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

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

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

```bash theme={null}
# 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
```

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

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
  -DWITH_SSL="$(brew --prefix openssl@3)"
```

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

### 解释 CMake 选项

* `"$HOME/villagesql-server"` - 已克隆的 VillageSQL 仓库路径
* `-DWITH_DEBUG=1` - 启用 DBUG 机制和断言的非优化构建（推荐用于开发）
* `-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 选项

**生产环境构建：**

```bash theme={null}
cmake "$HOME/villagesql-server"
```

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

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
```

> [!NOTE]
>
> 如果需要重新配置，请先清除 CMake 缓存（在构建目录内运行）：
>
> ```bash theme={null}
> rm CMakeCache.txt
> ```

## 步骤 4：编译代码

使用 make 进行并行编译以构建 VillageSQL。在构建目录内执行：

**构建全部内容（推荐）：**

```bash theme={null}
make -j10
```

此命令会构建服务器、[步骤 7](#step-7-connect-with-mysql-client)中用于连接的 `mysql` 客户端、扩展 SDK 以及示例扩展的 VEB 文件。

**仅构建服务器和客户端：**

```bash theme={null}
make -j10 mysqld mysql
```

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

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

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

```bash theme={null}
ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"
```

## 步骤 5：初始化数据库

在首次启动服务器之前，初始化数据目录：

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

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

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

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

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

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

```bash theme={null}
ls "$HOME/mysql-data/data/mysql"
```

## 步骤 6：启动服务器

启动 VillageSQL 服务器：

```bash theme={null}
"$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

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

```bash theme={null}
"$HOME/build/villagesql/bin/mysqld" --user=root --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

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

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

打开新终端并使用 MySQL 客户端连接到服务器：

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

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root
```

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

```bash theme={null}
"$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`，请更改临时密码：

```sql theme={null}
SET PASSWORD = 'your-secure-password';
```

### 验证安装

检查您是否正在运行 VillageSQL：

```sql theme={null}
SELECT VERSION();
```

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

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

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

### 创建开发用户

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

```sql theme={null}
-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

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

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

```bash theme={null}
# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p
```

### 创建数据库

```sql theme={null}
CREATE DATABASE my_database;
USE my_database;
```

> [!TIP]
>
> 连接到特定数据库：`"$HOME/build/villagesql/bin/mysql" -u developer -p -D my_database`

## 步骤 9：运行测试

在构建目录中，使用 VillageSQL 测试套件验证构建。请以普通用户身份运行测试：以 root 身份运行时，测试运行器会跳过部分测试，并且其中一个测试会失败。

```bash theme={null}
cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto
```

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

```bash theme={null}
make -j10 villagesql-unit-tests && ctest -L villagesql
```

任一命令在有测试失败时都会以非零状态退出。

如需进行 GDB 调试、运行单个测试、重新记录预期结果或为服务器代码库做出贡献，请参阅 [服务器开发指南](https://villagesql.com/docs/zh/8.4/stable/server-development.md)。

## 构建原生软件包（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`——然后从仓库根目录运行其中一个：

```bash theme={null}
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](https://github.com/villagesql/villagesql-server/pull/931)，生成的软件包会接管目标主机上已有的 MySQL 安装，而不是与之并行安装。

## 故障排除

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

请再次运行安装脚本。[步骤 3](#step-3-configure-with-cmake)会让您停留在构建目录中，
因此请使用该脚本的绝对路径：

```bash theme={null}
"$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` 文件名是否正确

## 后续步骤

> [card] [使用扩展](https://villagesql.com/docs/zh/extensions/install.md)
>
> 了解如何安装、更新和管理 VillageSQL 扩展。

> [card] [创建扩展](https://villagesql.com/docs/zh/extensions/build/create.md)
>
> 为 VillageSQL 构建您自己的自定义扩展。

> [card] [安装](https://villagesql.com/docs/zh/8.4/stable/install-server.md)
>
> VillageSQL 快速入门指南。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.