> ## 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 可让您获得最新功能，并允许您根据特定环境自定义构建。

## 前置条件

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

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

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

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

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

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

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

## 步骤 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`，
  并使用您自己的软件包管理器安装等效的软件包。
</Note>

<h2 id="step-3-configure-with-cmake">
  步骤 3：使用 CMake 进行配置
</h2>

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

```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 -DCMAKE_INSTALL_PREFIX="$HOME/mysql"
```

在 macOS 上，请添加 `-DWITH_SSL=system`，以便 CMake 找到 Homebrew 提供的 OpenSSL：

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" -DWITH_SSL=system
```

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

### 解释 CMake 选项

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

### 其他 CMake 选项

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

```bash theme={null}
cmake "$HOME/villagesql-server" -DCMAKE_INSTALL_PREFIX=/usr/local/mysql
```

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

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

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

```bash theme={null}
cmake "$HOME/villagesql-server" -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
```

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

  ```bash theme={null}
  rm CMakeCache.txt
  ```
</Note>

## 步骤 4：编译代码

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

**构建服务器和客户端（推荐用于开发）：**

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

`mysql` 目标会构建在[步骤 7](#step-7-connect-with-mysql-client)中用于连接的客户端；
仅执行 `make -j10 mysqld` 只会构建服务器，届时步骤 7 将没有客户端可运行。

**构建全部内容：**

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

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

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

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

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

如果以 root 用户运行（例如在 Docker 中），MySQL 需要 `--user=root` 参数：

```bash theme={null}
# Initialize as root
"$HOME/build/villagesql/bin/mysqld" --user=root --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>`
</Note>

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

```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 能够干净地停止服务器 —— 在终端中交互式运行时非常有用。若要在后台运行，请在 `mysqld` 命令中添加 `--daemonize`。
</Tip>

<h2 id="step-7-connect-with-mysql-client">
  步骤 7：使用 MySQL 客户端连接
</h2>

打开新终端并使用 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 VillageSQL Server for MySQL monitor.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>
```

### 验证安装

检查您是否正在运行 VillageSQL：

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

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

```
9.7.2-villagesql-0.0.6-dev-5a64e122090
```

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

### 更改 root 密码

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

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

### 创建开发用户

用于日常开发，请创建一个非 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>
  连接到特定数据库：`mysql -u developer -p -D my_database`
</Tip>

如需进行 GDB 调试、运行测试或为服务器代码库做出贡献，请参阅 [服务器开发指南](/docs/zh/mysql-9.7/stable/server-development)。

## 故障排除

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

请再次运行安装脚本。[步骤 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 端口
* 查看 `$HOME/mysql-data/data/*.err` 中的错误日志

### 扩展安装失败

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

## 后续步骤

<CardGroup cols={3}>
  <Card title="使用扩展" icon="puzzle-piece" href="/docs/zh/mysql-9.7/stable/install">
    了解如何安装、更新和管理 VillageSQL 扩展。
  </Card>

  <Card title="创建扩展" icon="code" href="/docs/zh/mysql-9.7/stable/create">
    为 VillageSQL 构建您自己的自定义扩展。
  </Card>

  <Card title="快速入门" icon="rocket" href="/docs/zh/mysql-9.7/stable/index">
    VillageSQL 快速入门指南。
  </Card>
</CardGroup>