# 集成指南

本文面向把 EUI-NEO 接入外部 C++ 项目的用户。普通应用只需要两个文件：

```text
CMakeLists.txt
main.cpp
```

EUI-NEO 会通过 `eui_neo_configure_app()` 自动加入窗口入口、输入处理、渲染后端、平台链接选项和运行资源；应用不需要引用 `core/`，也不需要自行编写窗口主循环。

## 选择接入方式

| 方式                 | 适合场景                    | EUI-NEO 来源            |
| -------------------- | --------------------------- | ----------------------- |
| FetchContent（推荐） | 新项目、希望 CMake 自动下载 | CMake 在配置时拉取源码  |
| `3rd/EUI-NEO` 源码 | 需要调试或固定源码副本      | 项目目录中的源码        |
| Release SDK          | 正式项目、固定发布版本      | 已安装的库和 CMake 配置 |

三种方式最终使用同一个目标和同一个应用入口：

```cmake
add_executable(my_app main.cpp)
eui_neo_configure_app(my_app)
```

## 统一的 `main.cpp`

下面的应用代码适用于三种接入方式：

```cpp
#include "eui_neo.h"

namespace app {

const DslAppConfig& dslAppConfig() {
    static const DslAppConfig config = DslAppConfig{}
        .title("My App")
        .pageId("my_app")
        .windowSize(960, 640);
    return config;
}

void compose(eui::Ui& ui, const eui::Screen& screen) {
    ui.column("root")
        .size(screen.width, screen.height)
        .padding(32.0f)
        .content([&] {
            ui.text("title")
                .text("Hello EUI-NEO")
                .fontSize(28.0f)
                .build();
        })
        .build();
}

} // namespace app
```

## 方式一：FetchContent（推荐）

项目结构：

```text
my-project/
├─ CMakeLists.txt
└─ main.cpp
```

`CMakeLists.txt`：

```cmake
cmake_minimum_required(VERSION 3.14)
project(my_app LANGUAGES C CXX)

include(FetchContent)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(eui_neo_repository "https://github.com/sudoevolve/EUI-NEO.git")
execute_process(
    COMMAND git ls-remote ${eui_neo_repository} HEAD
    RESULT_VARIABLE eui_neo_github_status
    OUTPUT_QUIET ERROR_QUIET
    TIMEOUT 8
)
if(NOT eui_neo_github_status EQUAL 0)
    set(eui_neo_repository "https://atomgit.com/sudoevolve/EUI-NEO.git")
endif()

FetchContent_Declare(eui_neo
    GIT_REPOSITORY ${eui_neo_repository}
    GIT_TAG main
    GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(eui_neo)

add_executable(my_app main.cpp)
eui_neo_configure_app(my_app)
```

示例使用 `main` 分支以便每次配置时获取最新代码。需要可复现构建时，请将 `GIT_TAG` 固定为正式版本或具体 commit。

上面的配置会先检测 GitHub；如果 GitHub 不可访问，会自动切换到 AtomGit 国内镜像。无需额外传入 CMake 变量。

如果需要手动准备源码，也可以直接克隆镜像，再使用“方式二”的本地源码接入：

```sh
git clone https://atomgit.com/sudoevolve/EUI-NEO.git 3rd/EUI-NEO
```

构建运行：

Windows（Visual Studio）：

```powershell
cmake -S . -B build
cmake --build build --config Release --parallel
.\build\Release\my_app.exe
```

Linux/macOS：

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
./build/my_app
```

## 方式二：使用 `3rd/EUI-NEO` 源码

项目结构：

```text
my-project/
├─ 3rd/
│  └─ EUI-NEO/
├─ CMakeLists.txt
└─ main.cpp
```

`CMakeLists.txt`：

```cmake
cmake_minimum_required(VERSION 3.14)
project(my_app LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_subdirectory(3rd/EUI-NEO)

add_executable(my_app main.cpp)
eui_neo_configure_app(my_app)
```

这种方式适合调试框架源码、离线构建，或需要对 EUI-NEO 做本地修改的项目。

## 方式三：Release SDK / `find_package`

从 GitHub Releases 下载与平台和架构匹配的 SDK，解压或安装到固定目录。SDK 包含头文件、库、CMake 配置和运行资源，外部项目不需要携带 EUI-NEO 源码。

项目中的 `CMakeLists.txt`：

```cmake
cmake_minimum_required(VERSION 3.14)
project(my_app LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(EuiNeo CONFIG REQUIRED)

add_executable(my_app main.cpp)
eui_neo_configure_app(my_app)
```

配置和构建：

```sh
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/eui-neo-sdk -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
```

Windows 使用 Visual Studio 生成器时：

```powershell
cmake -S . -B build -DCMAKE_PREFIX_PATH="C:/path/to/eui-neo-sdk"
cmake --build build --config Release --parallel
.\build\Release\my_app.exe
```

## 后端选择

默认配置是 GLFW + OpenGL。每种后端组合使用独立构建目录：

```sh
# SDL2 窗口后端
cmake -S . -B build-sdl2 -DEUI_WINDOW_BACKEND=sdl2

# Vulkan 渲染后端
cmake -S . -B build-vulkan -DEUI_RENDER_BACKEND=vulkan

# SDL2 + Vulkan
cmake -S . -B build-sdl2-vulkan \
    -DEUI_WINDOW_BACKEND=sdl2 \
    -DEUI_RENDER_BACKEND=vulkan
```

- GLFW 通常由 EUI-NEO 的内置依赖提供。
- SDL2 需要系统 SDL2 开发包；`FetchContent` 模式下 CMake 可按依赖配置拉取 SDL2。
- Vulkan 构建机需要 Vulkan SDK 和对应的 `glslangValidator`；目标机需要 Vulkan loader 与显卡驱动。
- Linux 如果不需要系统托盘，可以配置 `-DEUI_ENABLE_TRAY=OFF`，避免额外的 GTK/GLib 开发依赖。

## 构建仓库自带示例

这属于 EUI-NEO 仓库开发，不是外部项目接入。配置仓库时打开对应选项：

```sh
cmake -S . -B build \
    -DEUI_BUILD_APPS=ON \
    -DEUI_BUILD_USER_APPS=ON
cmake --build build --target gallery --parallel
```

复杂应用应放在 `apps/<name>/app.cpp`；外部单文件项目仍建议使用 `main.cpp`。

## 运行资源

`eui_neo_configure_app(my_app)` 会把 EUI-NEO 的 `assets/` 复制到可执行文件旁边。应用自己的图片、字体、JSON、fragment 和 SPIR-V 文件仍需由应用的 CMake 目标自行部署。

运行时使用 `eui::platform::resolveResourcePath("assets/...")` 查找资源时，不要求从项目根目录启动程序。

## 常见问题

### Windows 找不到入口点

必须调用：

```cmake
eui_neo_configure_app(my_app)
```

不要手动添加 `core/app/glfw_app_main.cpp` 或 `core/app/sdl2_app_main.cpp`。Visual Studio 构建后，程序通常位于：

```text
build/Release/my_app.exe
```

### Linux/macOS 找不到程序

单配置生成器通常输出到：

```text
build/my_app
```

请确认使用了对应的构建目录，并在 macOS 上通过 `./build/my_app` 启动，而不是 Windows 的 `.exe` 路径。

### Debug 标题显示统计信息

Debug 构建默认会在窗口标题显示 FPS、CPU/GPU 和渲染统计。可以在配置中关闭：

```cpp
const DslAppConfig& dslAppConfig() {
    static const DslAppConfig config = DslAppConfig{}
        .title("My App")
        .showDebugStatsInTitle(false);
    return config;
}
```

### 进一步阅读

- [README 快速开始](../README.zh-CN.md#快速开始)
- [开发与发布](开发与发布.md)
- [Shadertoy 图元](Shadertoy.md)