Yaade项目在FreeBSD系统上的构建与运行指南

Yaade是一款基于Kotlin和React开发的API开发与测试工具，本文将详细介绍如何在FreeBSD系统上完成Yaade项目的构建与运行过程。

系统环境准备

在FreeBSD系统上构建Yaade项目前，需要先安装必要的依赖包。使用root权限执行以下命令：

pkg -y install npm-node18 gradle openjdk17 kotlin

这条命令会安装Node.js 18、Gradle构建工具、OpenJDK 17以及Kotlin编译器，这些都是Yaade项目构建所必需的基础环境。

项目获取与初始化

获取项目源代码并设置Java环境变量：

git clone https://github.com/EsperoTech/yaade.git
export JAVA_VERSION=17

这里特别指定了Java版本为17，因为Yaade项目需要Java 17环境支持。环境变量的设置确保了后续构建过程中使用正确的Java版本。

项目构建步骤

Yaade项目采用前后端分离的架构，构建过程分为服务器端和客户端两部分。

服务器端构建

进入服务器目录并执行Gradle构建：

cd yaade/server/
./gradlew clean assemble

Gradle会下载所有必要的依赖并编译Kotlin代码。clean命令确保从头开始构建，避免缓存带来的问题。

客户端构建

客户端基于React技术栈，需要先安装Node.js依赖：

cd ../client/
npm install

安装完成后执行构建：

npm run build

这个命令会使用TypeScript编译器(tsc)和Vite构建工具生成生产环境可用的静态资源。

资源整合

构建完成后，需要将客户端生成的静态资源移动到服务器端资源目录：

rm -rf server/src/main/resources/webroot
mv client/dist server/src/main/resources/webroot

这一步确保了服务器能够正确提供前端页面服务。

完整服务器构建

回到服务器目录执行完整构建：

cd server
./gradlew clean build

这次构建会将前端资源打包到最终的服务器jar文件中。

运行配置

在FreeBSD系统上直接运行Yaade可能会遇到类加载问题，需要手动配置类路径。以下是推荐的运行方式：

准备运行环境

创建运行目录并复制必要的文件：

mkdir -p ~/yaade/libs
cp build/libs/dependencies/*.jar ~/yaade/libs/
cp -r build/resources/main ~/yaade/resources
cp -r build/classes/kotlin/main ~/yaade/classes
cp -r build/classes/java/main ~/yaade/classes
cp build/libs/*.jar ~/yaade/libs/

设置环境变量

配置Java类路径和内存参数：

export CLASSPATH=$HOME/yaade/classes:$HOME/yaade/resources:$HOME/yaade/libs
export YAADE_HEAP_SIZE=""

启动应用

进入运行目录并启动主类：

cd $HOME/yaade
java com.espero.yaade.MainKt

常见问题解决

在FreeBSD上运行可能会遇到"kotlin/coroutines/Continuation"类找不到的错误。这通常是由于Kotlin运行时库未正确加载导致的。确保以下几点：

1. 所有依赖的jar文件都已复制到~/yaade/libs目录
2. CLASSPATH环境变量设置正确，包含了所有必要的路径
3. 使用的Java版本为17或更高

如果问题仍然存在，可以尝试使用Gradle的application插件提供的启动脚本，或者考虑使用Docker容器来运行Yaade应用，这样可以避免系统环境差异带来的问题。

总结

本文详细介绍了Yaade项目在FreeBSD系统上的完整构建和运行流程。虽然过程略显复杂，但遵循这些步骤应该能够在FreeBSD上成功运行Yaade。对于生产环境部署，建议考虑使用容器化技术简化部署过程并提高可移植性。