> ## 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 服务器代码库的开发。

本指南涵盖调试、运行服务器测试套件以及参与 VillageSQL 的开发。它假定您已有一个可用的源码构建——如果尚未完成，请参阅[从源代码构建](https://villagesql.com/docs/zh/9.7/stable/source.md)。

## 调试

VillageSQL 服务器调试在 Linux 上使用 GDB，在 macOS 上使用 lldb。macOS 上的 GDB 需要代码签名，设置起来很麻烦——lldb 是标准的 macOS 调试器，开箱即用。

### Linux（GDB）

在 GDB 下运行 VillageSQL：

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

**在 GDB 内部：**

```
(gdb) run                    # Start the server
(gdb) break function_name    # Set breakpoints
(gdb) continue               # Resume execution
(gdb) bt                     # Show backtrace on crash
```

**常用 GDB 命令：**

```
# Break on specific SQL command execution
(gdb) break mysql_execute_command

# Break on extension loading
(gdb) break Sql_cmd_install_extension::execute

# Print variable values
(gdb) print variable_name

# Step through code
(gdb) step      # Step into functions
(gdb) next      # Step over functions
```

### macOS（lldb）

在 lldb 下运行 VillageSQL：

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

**在 lldb 内部：**

```
(lldb) run                         # Start the server
(lldb) breakpoint set -n function_name  # Set breakpoints
(lldb) continue                    # Resume execution
(lldb) bt                          # Show backtrace on crash
```

**常用 lldb 命令：**

```
# Break on specific SQL command execution
(lldb) breakpoint set -n mysql_execute_command

# Break on extension loading
(lldb) breakpoint set -n Sql_cmd_install_extension::execute

# Print variable values
(lldb) print variable_name

# Step through code
(lldb) step      # Step into functions
(lldb) next      # Step over functions
```

## 运行测试

VillageSQL 包含单元测试和回归测试，以验证功能。

### 单元测试

运行 VillageSQL 特定的单元测试（从您的构建目录中）：

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

或者运行所有单元测试：

```bash theme={null}
ctest --output-on-failure
```

### 回归测试

切换到 mysql-test 目录：

```bash theme={null}
cd mysql-test
```

**运行完整的 MySQL 测试套件（速度较慢）：**

```bash theme={null}
./mysql-test-run.pl --parallel=auto
```

**运行一个 VillageSQL 子套件：**

```bash theme={null}
./mysql-test-run.pl --suite=villagesql/insert
```

**运行 VillageSQL 测试，包括所有子套件：**

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

请以普通用户而非 root 身份运行测试：以 root 运行时，测试运行器会跳过部分测试，其中一个会失败。

> [!NOTE]
>
> **--suite 与 --do-suite：**
>
> * `--suite=villagesql/insert` 运行一个子套件
> * `--do-suite=villagesql` 运行所有测试，包括子套件（insert、select、stored\_procedure 等）
> * `--nounit-tests` 跳过 MTR 原本会随套件一起运行的单元测试。这些是上游 MySQL 的单元测试，其中包含已知的失败；请使用上面的[单元测试](#unit-tests)命令单独运行 VillageSQL 的单元测试。

### 运行单个测试

通过名称运行特定的测试：

```bash theme={null}
./mysql-test-run.pl villagesql/startup.recovery_complex_index
```

从子套件中运行测试：

```bash theme={null}
./mysql-test-run.pl --suite=villagesql/insert
```

### 更新测试结果

如果您更改了功能并需要更新预期的测试输出：

```bash theme={null}
./mysql-test-run.pl --record villagesql/startup.recovery_complex_index
```

> [!WARNING]
>
> **测试记录：** 始终检查 `.result` 文件的更改，以确保它们反映了预期的行为，而不是错误。`--record` 标志会盲目地覆盖预期的输出。

### 测试可移植性

当测试输出包含来自测试运行程序的临时目录的路径时，请在每条会打印此类路径的语句之前添加以下指令，这样记录的结果就不会包含在其他机器上会出错的绝对路径：

```sql theme={null}
--replace_result $MYSQLTEST_VARDIR MYSQLTEST_VARDIR
```

### 调试测试失败

VillageSQL 特定的日志消息（通过 `LogVSQL()` 发出）在 `--log-error-verbosity=3` 时写入错误日志，MTR 默认设置该级别。要为单次运行设置该级别：

```bash theme={null}
./mysql-test-run.pl --mysqld=--log-error-verbosity=3 villagesql/startup.recovery_complex_index
```

单工作进程运行时，完整的错误日志位于 `mysql-test/var/log/mysqld.1.err`。使用 `--parallel` 时，每个工作进程改为写入 `mysql-test/var/<N>/log/mysqld.1.err`。

有关编写扩展回归测试，请参阅 [C++ 测试](https://villagesql.com/docs/zh/sdk/cpp/testing.md)。

## 安装二进制文件

要在系统范围内安装 VillageSQL（需要适当的权限）：

```bash theme={null}
cmake --build "$HOME/build/villagesql" --target install
```

这会将二进制文件默认安装到 `/usr/local/mysql/`。您可以自定义安装前缀：

```bash theme={null}
cmake -S "$HOME/villagesql-server" -B "$HOME/build/villagesql" -DCMAKE_INSTALL_PREFIX=/opt/villagesql
cmake --build "$HOME/build/villagesql" --target install
```

## 贡献

如果您要为 VillageSQL 做出贡献，请参阅[贡献指南](https://github.com/villagesql/villagesql-server/blob/main/CONTRIBUTING.md)，了解编码标准和开发流程。


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