// ... read src, write result to dst ...
out.set_length(src.size());
}
```
使用 `.param(COMPLEX)` 和 `.returns(COMPLEX)` 进行注册：
```cpp theme={null}
.func(make_func<&complex_conjugate_impl>("complex_conjugate")
.returns(COMPLEX)
.param(COMPLEX)
.build())
```
有关完整的 `CustomArg`/`CustomResult` API（包括用于参数化类型的 `CustomArgWith` 和 `CustomResultWith
`），请参阅 [开发指南](/docs/zh/mysql-8.4/0.0.4/development#typed-wrappers-recommended)。
### 确定性函数
默认情况下，VDF 注册为非确定性函数。非确定性函数在三个 SQL 上下文中被禁用：生成列、CHECK 约束和表达式默认值（列上的 `DEFAULT (expr)`）——将任何这些功能与非确定性 VDF 一起使用都会返回错误。如果您的函数对于相同的输入始终产生相同的输出且无副作用，您可以通过在构建器链中添加 `.deterministic()` 将其声明为确定性函数。
优化器可能会利用此信息，在每条语句中仅评估一次该函数，并在行之间重用该值，而不是逐行调用。因此，错误地将非确定性函数标记为确定性函数可能导致服务器对应该产生不同输出的输入返回相同的结果。仅当您的函数确实不依赖外部状态、随机性或时间时，才添加 `.deterministic()`。
**构建器签名：** `.deterministic(bool d = true)`——无参形式默认为 `true`。
**示例：**
```cpp theme={null}
.func(make_func<&complex_add_impl>("complex_add")
.returns(COMPLEX)
.param(COMPLEX)
.param(COMPLEX)
.deterministic()
.build())
```
由于 `complex_add` 被声明为确定性函数，因此可用于生成列定义中：
```sql theme={null}
-- Deterministic VDFs can be used in generated columns
CREATE TABLE t (
a COMPLEX,
b COMPLEX,
result COMPLEX GENERATED ALWAYS AS (complex_add(a, b)) STORED
);
-- STORED vs VIRTUAL follows standard MySQL generated column rules
```
### 自定义缓冲区大小
对于返回变长数据的函数，请指定所需的缓冲区大小：
```cpp theme={null}
make_func<&large_result_impl>("large_result")
.returns(STRING)
.param(INT)
.buffer_size(65536) // Request 64KB buffer
.build()
```
写入前检查可用缓冲区空间：
```cpp theme={null}
void large_result_impl(StringArg input, StringResult out) {
if (input.is_null()) { out.set_null(); return; }
size_t needed = calculate_output_size(input.value());
auto buf = out.buffer();
if (needed > buf.size()) {
out.error("Output exceeds buffer size");
return;
}
// Write output into buf.data()
out.set_length(actual_output_length);
}
```
请根据函数的最大输出大小，通过 .buffer\_size() 请求足够的缓冲区大小。
在实现函数之前，请查阅 [扩展 API 参考](/docs/zh/mysql-8.4/0.0.4/extension-api-reference) 以了解完整的 VDF 契约：空值检查、结果类型、缓冲区大小和错误处理。
## 步骤 4：创建自定义类型
自定义类型允许您定义新的列类型——例如 COMPLEX、UUID 或
VECTOR——这些类型可与 ORDER BY、索引和聚合函数配合使用。
如果您的扩展仅注册函数，请跳至步骤 5。
请参阅 [创建自定义类型](/docs/zh/mysql-8.4/0.0.4/custom-types) 获取完整的实现指南。如果您的类型需要参数（例如 VECTOR(1536)），
请参阅 [参数化类型](/docs/zh/mysql-8.4/0.0.4/development#parameterized-types)。
步骤 5：更新构建配置
编辑 CMakeLists.txt 以将您的扩展构建为 VEB 文件：
```cmake theme={null}
cmake_minimum_required(VERSION 3.18)
project(my_extension)
# Find VillageSQL Extension Framework
find_package(VillageSQLExtensionFramework QUIET)
# The framework detects build flags via 4 methods (in order):
# 1. Explicit MYSQL_INCLUDE_FLAGS/MYSQL_CXXFLAGS
# 2. VillageSQL_BUILD_DIR (reads CMakeCache.txt from VillageSQL build)
# 3. VSQL_BASE_DIR (uses mysql_config)
# 4. Default - mysql_config from PATH
# Build shared library with your source files
add_library(extension SHARED
src/extension.cc
src/my_functions.cc
)
# Create VEB archive
VEF_CREATE_VEB(
NAME my_extension
LIBRARY_TARGET extension
MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/manifest.json
)
# Install VEB to VillageSQL extensions directory
install(FILES ${VEB_OUTPUT} DESTINATION ${INSTALL_DIR})
```
**配置说明：**
* `VillageSQLExtensionFramework` 提供用于构建扩展的 CMake 辅助工具
* `VEF_CREATE_VEB()` 将您的库、清单和元数据打包为 `.veb` 归档文件
* 框架会自动检测 MySQL/VillageSQL 构建标志
* 库目标名称通常为 `extension`（可以是任意名称）
* VEB 名称必须与您的 `manifest.json` 名称匹配
* 默认情况下，扩展针对稳定的 ABI 头文件进行构建。设置 `-DVSQL_USE_DEV_ABI=ON` 可改为针对不稳定的开发头文件构建
***
## 步骤 6：创建构建目录
创建单独的构建目录：
```bash theme={null}
mkdir build
cd build
```
## 步骤 7：使用 CMake 和 Make 进行构建
配置并构建您的扩展：
```bash theme={null}
# Configure the build
cmake ..
# Or, if building against VillageSQL source:
cmake .. -DVillageSQL_BUILD_DIR=/path/to/villagesql/build
# Or, to build against the unstable dev ABI headers:
cmake .. -DVSQL_USE_DEV_ABI=ON
# Build the extension
make
```
这将生成：
* 编译后的共享库（`.so` 文件）
* VEB 包（`.veb` 文件）- 包含清单和库的 tar 归档文件
### 验证构建结果
检查您的 VEB 文件内容：
```bash theme={null}
make show_veb
```
您应该看到：
```
manifest.json
lib/myext.so
```
## 步骤 8：安装与测试
### 选项 A：安装到 VillageSQL 扩展目录
使用 install 目标将 VEB 复制到您的 VillageSQL 安装目录：
```bash theme={null}
make install
```
这会将 `.veb` 文件复制到通过 `VillageSQL_VEB_INSTALL_DIR` 配置的目录中。
### 选项 B：手动安装
手动复制 VEB 文件：
```bash theme={null}
# Find the VEF directory
mysql -u root -p -e "SHOW VARIABLES LIKE 'veb_dir';"
# Copy the VEB file
sudo cp my-awesome-extension.veb /path/to/veb_dir/
```
### 测试您的扩展
1. **连接到 VillageSQL**：
```bash theme={null}
mysql -u root -p
```
2. **安装扩展**：
```sql theme={null}
INSTALL EXTENSION my_awesome_extension;
```
3. **验证安装**：
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
4. **测试您的函数**：
```sql theme={null}
SELECT my_reverse('Hello, World!');
-- Output: !dlroW ,olleH
SELECT count_vowels('VillageSQL');
-- Output: 3
```
## 创建测试
添加测试文件以验证您的扩展是否正常工作：
1. **在 `mysql-test/t/` 中创建测试文件**：
```sql theme={null}
-- mysql-test/t/my_basic.test
SELECT my_reverse('abc');
SELECT my_reverse('');
SELECT my_reverse(NULL);
```
2. **生成预期结果**：
```bash theme={null}
cd /path/to/villagesql/build/mysql-test
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test --record
```
3. **运行测试**：
```bash theme={null}
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test
```
## 故障排除
### 扩展无法加载
检查错误日志并验证 VEB 内容：
```bash theme={null}
make show_veb
tail -f /var/log/mysql/error.log
```
### 未找到函数
验证安装和注册情况：
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
### 构建错误
```bash theme={null}
# Verify mysql_config is available
which mysql_config
mysql_config --version
# Check compiler version
gcc --version # or clang --version
# Verify CMake version (3.18+ required)
cmake --version
```
## 示例扩展
从现有的 VillageSQL 扩展中学习：
复数数据类型实现
用于创建扩展的最小模板
## 后续步骤
了解如何安装和管理扩展
类型包装器、聚合函数、系统变量和测试
生命周期、缓存、性能和安全模型
从源代码构建 VillageSQL
## 资源
* [VillageSQL Extension Template](https://github.com/villagesql/vsql-extension-template)
* [MySQL UDF API Documentation](https://dev.mysql.com/doc/extending-mysql/8.4/en/adding-loadable-function.html)
* [CMake Documentation](https://cmake.org/documentation/)
* [VillageSQL Community Discord](https://discord.gg/KSr6whd3Fr)