环境配置

工欲善其事，必先利其器。这一节我们来把 HiEasyX 的运行环境搭建好。整个过程并不复杂，跟着步骤来就行。

前置条件

在开始之前，请确认你的系统满足以下条件：

项目	要求
操作系统	Windows 10 / 11
EasyX 版本	2023-7-23 或更高
编译器	Visual Studio 2019 / 2022 / 2026，或 MinGW-w64
C++ 标准	C++20 及以上

💡 如何查看 EasyX 版本？

在代码中调用 GetEasyXVer() 即可返回版本字符串。如果低于 2023-7-23，建议去 EasyX 官网 下载最新安装包。

---

方式一：Visual Studio 手动配置

这是最直观的方式，适合不想折腾 CMake 的同学。

步骤 1：准备源码

假设你已经下载了 HiEasyX 的源代码，目录结构大致如下：

HiEasyX/
├── include/           ← 头文件在这里
│   ├── hex.h
│   ├── hex_window.h
│   └── ...
├── source/            ← 源文件在这里
│   ├── hex.cpp
│   ├── hex_window.cpp
│   └── ...
└── example/           ← 示例代码

步骤 2：创建 VS 项目

1. 打开 Visual Studio，创建一个 空项目（Empty Project）。
2. 在"解决方案资源管理器"中，右键点击项目 → 属性。

步骤 3：配置头文件路径

在属性页中找到：

配置属性 → C/C++ → 常规 → 附加包含目录

添加 HiEasyX 的 include 目录路径，例如：

D:\HiEasyX\include

ℹ️ 为什么不用 NuGet？

HiEasyX 目前未发布 NuGet 包，因此需要手动添加源码。好处是你可以直接调试和修改框架源码，对学习很有帮助。

步骤 4：添加源文件到项目

在"解决方案资源管理器"中：

1. 右键点击源文件过滤器 → 添加 → 现有项。
2. 进入 HiEasyX 的 source 目录，选中所有 .cpp 文件并添加。
3. （可选）同样将 example/EasyX 里的示例添加进去，方便学习。

步骤 5：确认字符集为 Unicode

在属性页中找到：

配置属性 → 高级 → 字符集

确保设置为 使用 Unicode 字符集。HiEasyX 内部统一使用宽字符串（std::wstring），这一步非常重要。

步骤 6：链接 EasyX

如果你已经通过 EasyX 安装程序配置好了 Visual Studio，这一步可以跳过。否则需要在链接器 → 输入 → 附加依赖项中添加：

EasyXa.lib   // 或 EasyXw.lib，取决于你的字符集

---

方式二：CMake 配置（推荐）

如果你喜欢用 CLion、VS Code，或者需要跨项目复用，CMake 是更好的选择。

最小 CMakeLists.txt 示例

cmake_minimum_required(VERSION 3.20)
project(MyHiEasyXApp)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 假设 HiEasyX 源码和项目同级目录
set(HIEASYX_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../HiEasyX")

# 收集所有 HiEasyX 源文件
file(GLOB_RECURSE HIEASYX_SOURCES
    "${HIEASYX_DIR}/source/*.cpp"
    "${HIEASYX_DIR}/source/impl/EasyX/*.cpp"
)

add_executable(${PROJECT_NAME}
    main.cpp
    ${HIEASYX_SOURCES}
)

target_include_directories(${PROJECT_NAME} PRIVATE
    "${HIEASYX_DIR}/include"
)

# Windows Unicode 定义
target_compile_definitions(${PROJECT_NAME} PRIVATE UNICODE _UNICODE)

💡 关于 GLOB_RECURSE

上面的 file(GLOB_RECURSE ...) 会自动收集 source 目录下所有 .cpp 文件，省去了手动维护列表的麻烦。不过要注意：新增或删除源文件后，需要重新触发 CMake 配置才能更新。

构建命令（Ninja + Clang）

如果你使用 Clang 编译器，注意终端必须继承 VS 开发者命令提示符的环境变量，否则找不到 MSVC 的系统头文件和库文件：

# PowerShell 中执行
& cmd /c 'call "D:\Visual Studio\VC\Auxiliary\Build\vcvars64.bat" && cd /d D:\MyProject\build && cmake .. -G Ninja -DCMAKE_CXX_COMPILER=clang++ && ninja'

⚠️ 关键提醒

不要在普通的 PowerShell 窗口中直接运行 ninja 或 cmake，否则会遇到 could not open 'kernel32.lib' 或找不到 graphics.h 的错误。一定要先调用 vcvars64.bat！

---

验证安装是否成功

环境配置完成后，我们来写一段最简单的验证代码：

#include <include/hex.h>
#include <include/impl/EasyX/hex_impl_easyx.h>
#include <graphics.h>   // EasyX

int main() {
    initgraph(800, 600);
    HX::HXInitForEasyX();
    HX::SetBuffer(GetWorkingImage());
    HX::ApplyModernTheme(HX::HXThemeMode::ModernDark);

    bool running = true;
    while (running) {
        HX::HXBegin();

        ExMessage msg;
        while (peekmessage(&msg)) {
            HX::PushMessage(HX::GetHXMessage(&msg));
        }

        HX::WindowProfile wp;
        if (HX::Window(HXStr("验证窗口"), wp)) {
            HX::Text(HXStr("Hello HiEasyX! 环境配置成功！"));
        }

        HX::End();
        HX::Render();

        if (msg.message == WM_CLOSE) running = false;
    }

    closegraph();
    return 0;
}

如果能编译通过，并且运行时看到一个带有标题栏的深色窗口，里面显示 "Hello HiEasyX!"，那就说明环境配置完全正确了！🎉

ℹ️ 常见编译错误排查

错误信息	可能原因	解决方案
无法打开包括文件: "hex.h"	附加包含目录没设对	检查 include 路径是否指向了正确的目录
找不到 graphics.h	EasyX 未安装或编译器路径错误	重装 EasyX，确认 VS 版本匹配
HXStr 未定义	未定义 UNICODE 宏	在项目属性中设置"使用 Unicode 字符集"
无法解析的外部符号	源文件未添加到项目	确认所有 .cpp 都已加入编译
could not open 'kernel32.lib'	CMake 未在 VS 环境中运行	先执行 vcvars64.bat

→ 继续阅读：第一个程序