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

本指南涵盖 GDB 调试、运行服务器测试套件以及参与 VillageSQL 的开发。请先从[源码构建](/docs/zh/mysql-8.4/0.0.4/source)开始，获取一个可用的构建版本，然后再使用本指南。

## 使用 GDB 调试

为了进行开发和故障排除，您可以在 GDB 下运行 VillageSQL：

**Linux：**

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

**macOS：**

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

**在 GDB 内部：**

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

**用于 MySQL 调试的常用 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
```

## 运行测试

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
```

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

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

<Note>
  **--suite 与 --do-suite：**

  * `--suite=villagesql` 仅运行顶层 villagesql 测试
  * `--do-suite=villagesql` 运行所有测试，包括子套件（insert、select、stored\_procedure 等）
</Note>

### 运行单个测试

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

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

从子套件中运行测试：

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

### 更新测试结果

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

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

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

### 测试可移植性

当测试输出包含来自测试运行程序的临时目录的路径时，请在您的 `.test` 文件中添加以下指令，这样记录的结果就不会包含在其他机器上会出错的绝对路径：

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

### 调试测试失败

VillageSQL 特定的日志消息（通过 `LogVSQL()` 发出）默认情况下会被抑制。要在测试运行时将其显示在错误日志中：

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

完整的错误日志位于 `mysql-test/var/log/mysqld.1.err`。

有关编写扩展回归测试，请参阅[开发指南](/docs/zh/mysql-8.4/0.0.4/development)。

## 安装二进制文件

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

```bash theme={null}
cmake --build build --target install
```

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

```bash theme={null}
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/villagesql
cmake --build build --target install
```

## 贡献

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