====== 配置 Nop 平台开发环境指南 ======

开始使用 Nop 平台前，需要配置好本地开发环境。以下是完整步骤。

===== 环境要求 =====

^ 工具 ^ 版本 ^ 说明 ^
| JDK | 17+ | 不支持 JDK 8 |
| Maven | 3.9.3+ | 项目自带 mvnw 包装器 |
| Git | 任意 | 克隆源码 |
| IDEA | 2023+ | 配合 nop-idea-plugin |

===== 第一步：安装 JDK =====

建议使用 OpenJDK 17 或更高版本。某些 JDK 版本（如 graalvm 17.0.9）编译时会报 IndexOutOfBound 异常，建议先用标准 OpenJDK。

**Ubuntu/Debian：**

<code bash>
sudo apt install openjdk-17-jdk
java -version
</code>

**Windows：** 从 [[https://adoptium.net/|Adoptium]] 下载安装包，安装后设置 JAVA_HOME 环境变量。

===== 第二步：克隆源码 =====

<code bash>
git clone https://gitee.com/canonical-entropy/nop-entropy.git
cd nop-entropy
</code>

国内用户建议用 Gitee 镜像，速度更快。GitHub 镜像同样可用：

<code bash>
git clone https://github.com/entropy-cloud/nop-entropy.git
</code>

**注意：** Windows 下路径不要太深（不要放在 Downloads 深层目录下），建议直接放在 D:\nop 或 C:\nop 这种短路径，避免 Windows 路径长度限制。

===== 第三步：编译安装 =====

项目使用 Maven Wrapper（mvnw），不需要预先安装 Maven。首次运行会自动下载所需版本。

<code bash>
# 完整编译安装（跳过测试，单线程模式）
./mvnw clean install -DskipTests

# 如果希望并行编译加快速度
./mvnw clean install -DskipTests -T 1C

# 如果遇到依赖解析失败
./mvnw clean install -DskipTests -U
</code>

**Windows PowerShell 用户**注意参数要用引号包裹：

<code powershell>
./mvnw clean install "-DskipTests" "-Dquarkus.package.type=uber-jar"
</code>

首次编译需要下载大量依赖，视网络情况可能需要 10-30 分钟。

===== 第四步：运行 Demo =====

编译成功后，可以运行 nop-auth-app 模块验证环境：

<code bash>
cd nop-auth/nop-auth-app
./mvnw compile quarkus:dev
</code>

启动后访问 http://localhost:8080，应该能看到 Nop 平台的登录页面。

默认管理员账号：nop / nop-test

===== 第五步：IDEA 配置 =====

**安装 nop-idea-plugin：**

  - 打开 IDEA，进入 Settings → Plugins
  - 选择 Install Plugin from Disk
  - 找到 nop-idea-plugin 目录下的构建产物
  - 重启 IDEA

插件提供以下功能：

  * DSL 文件语法高亮
  * 代码自动补全
  * 文件跳转（Ctrl+Click）
  * XLang 断点调试

**运行配置：**

  - 导入项目：File → Open → 选择 nop-entropy 根目录
  - 等待 Maven 索引完成
  - 找到 nop-auth-app 模块，运行 QuarkusApplication

===== 第六步：常见问题 =====

**编译失败：Could not resolve dependencies**

通常是本地 Maven 缓存问题：

<code bash>
# 清理本地缓存后重试
rm -rf ~/.m2/repository/io/github/entropy-cloud
./mvnw clean install -DskipTests -U
</code>

**PowerShell 乱码：**

<code powershell>
$OutputEncoding = [Console]::OutputEncoding = [Text.Encoding]::UTF8
</code>

**编译内存不足：**

<code bash>
export MAVEN_OPTS="-Xmx2g"
./mvnw clean install -DskipTests
</code>

**IDEA 无法识别 DSL 文件：** 确保已安装 nop-idea-plugin 并重启 IDEA。

===== 下一步 =====

环境配置完成后，建议从以下内容入手：

  * [[https://gitee.com/canonical-entropy/nop-entropy/tree/master/docs/tutorial/tutorial.md|官方开发示例文档]]
  * 阅读 [[../reversible_computing|可逆计算理论]] 了解平台的设计原理
  * 查看 [[../reversible_computing_implementation/overview|实现机制概览]] 了解各模块的关系