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

### 安装依赖项

**Ubuntu/Debian：**

```bash theme={null}
sudo apt install cmake libssl-dev libncurses5-dev pkg-config bison \
                 libtirpc-dev rpcsvc-proto build-essential zlib1g-dev
```

**macOS（使用 Homebrew）：**

如果尚未安装，请先安装 Homebrew：

```bash theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

然后安装依赖项：

```bash theme={null}
brew install cmake openssl pkgconf bison libtirpc rpcsvc-proto
```

## 步骤 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：使用 CMake 进行配置

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

**Linux：**

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

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

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

### 解释 CMake 选项

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

### 其他 CMake 选项

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

Linux：

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

macOS：

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

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

Linux：

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

macOS：

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

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

Linux：

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

macOS：

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

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

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

## 步骤 3：编译代码

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

**仅构建服务器（推荐用于开发）：**

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

**构建全部内容：**

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

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

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

**Linux：**

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

**macOS：**

```bash theme={null}
ls ~/build/villagesql/bin/mysqld
```

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

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

**Linux：**

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

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

**macOS：**

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

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

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

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

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

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

**Linux：**

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

**macOS：**

```bash theme={null}
ls ~/mysql-data/data/mysql
```

## 步骤 5：启动服务器

启动 VillageSQL 服务器：

**Linux：**

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

**macOS：**

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

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

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

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

**Linux：**

如果使用 --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
```

**macOS：**

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

```bash theme={null}
~/build/villagesql/bin/mysql -u root
```

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

```bash theme={null}
~/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 提交哈希：

```
8.4.10-villagesql-0.0.5
```

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

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

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

**Linux:**

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

**macOS:**

```bash theme={null}
# Ctrl-D to exit
~/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-8.4/0.0.5/server-development)。

## 故障排除

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

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

### 服务器无法启动

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

### 扩展安装失败

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

## 后续步骤

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

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

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