准备

外部依赖项构建

　　这个步骤是可选的。若已获取二进制的库文件，可以跳过。

　　YSLib 发布的文件和对应使用的外部依赖项（包括二进制的库文件）可以从归档仓库下载。

　　进入 3rdparty 对应库的目录查看 Readme 文件说明。按此说明进行构建，一般方法为：

  • 自行获取指定的公开发行的源代码
  • 复制 3rdparty 库的目录中的文件到源代码，替换源代码中的原始文件
  • 运行指定的构建脚本命令行

库和示例程序构建

　　以下主要描述构建项目的默认目标：库和示例程序 YSTest 。对特定的构建方式，支持附加的其它目标。

注意 除了 SHBuild 外，当前没有实现子项目间的依赖管理。由于非正式版不保证二进制兼容性，直接增量构建可能在更新代码后失败。此时可手动清理构建生成的中间目录即 build。

　　另见构建文档。

使用构建工具和脚本

　　这是宿主平台的建议构建方式，支持所有的构建目标。

　　基本使用详见 SHBuild 和 Sysroot 。

　　b600 起用于发布和测试的二进制文件使用 SHBuild 构建。

　　当前版本的构建使用以下方式：

  • 调用 Tools/install-sysroot.sh 构建 Sysroot 。
    • 确保环境变量 SHBuild_UseDebug 和 SHBuild_UseRelease 的值非空。
    • 确保环境变量 SHBuild_NoStatic 、SHBuild_No3rd 和 SHBuild_NoDev 的值为空。
  • 在 Sysroot 部署完成后，设置环境变量 PATH 包含 Sysroot 布局下的二进制目录。
    • 对配置名 debug-static、debug、release-static 和 release ，以配置名作为第一参数分别调用 YSTest/SHBuild-YSTest.sh 构建示例项目 YSTest 的各个配置。
    • 类似地，调用 YDE/install-all.sh 构建 YDE 中所有包的各个配置。

Microsoft Visual Studio

　　源代码包含 Microsoft Visual Studio 2012/2013 解决方案 .sln 文件。可以直接生成解决方案。注意若修改被依赖项目代码后直接生成，依赖项目也不会重新编译，需要手动清除或重新编译。

　　当前包含了平台中立项目（便于源代码管理，不实际生成）、DS 项目 、MinGW32 项目和 Android 项目，但仅支持生成使用 make 的平台（ DS 和 Android ，需要对应的工具链支持）。因为正确支持的语言特性不足，Visual Studio 使用的编译器不能正常生成 Win32 项目。

　　使用 Microsoft Visual Studio 打开文件，需特定的环境变量以保证使用 makefile 的项目可构建。以下（使用 兼容 bash 的）路径仅为示例：

　　DS 项目：

DEVKITPRO=/opt/devkitpro

　　Android 项目：

ANDROID_SDK = /d/Android/sdk
PATH = /d/clang-android/bin:/c/Program\ Files/Java/jdk1.8.0_211/bin:$PATH

注意 Visual Studio 项目使用的 makefile 命令行依赖 bash 以及时检测到错误停止生成，可参见先决条件配置宿主环境。

　　支持生成的 Visual Studio 项目包含依赖性，不需要另行设置；也支持清理命令。

Code::Blocks

　　从 b217 (2011-06-13) 起支持。

　　源代码包含 Code::Blocks 工作空间 .workspace 文件，建议使用 Code::Blocks 12.11 或以上版本打开。

注意 打开工作空间后直接生成，其中的项目不都能成功构建，因为并非所有项目都保证能生成。项目名没有平台后缀的不用于构建，仅作为项目原型便于开发。

　　当前包含了平台中立项目（项目名不含下划线，便于源代码管理，不实际生成）、DS 项目和 MinGW32 项目，支持构建 DS 项目和 MinGW32 项目，每个分别包含 debug 和 release 配置。除此之外，MinGW32 项目还支持 debug_DLL 配置和 release_DLL 配置，用于生成动态链接库或使用动态链接库生成可执行文件。

　　对于 DS 可以分别编译其它各个项目，但不能运行。可以在工具菜单添加 DeSmuME 命令行运行。

　　b599 (2015-05-21) 起支持通过脚本 GenerateProjects.sh 生成 .cbp 文件。和 Visual Studio 不同，项目文件的内容不保证最新。这些文件以后仅保证在发布版本更新。

　　b600 前用于发布和测试的二进制文件使用此方式构建。因为编译时使用的文件路径不同等原因，构建的二进制文件和 SHBuild 不完全等价。

make 命令行

　　和 Visual Studio 类似，Code::Blocks 项目文件仅用于查看项目文件，当前不作为首要的构建途径被支持。

　　虽然 Code::Blocks 具有模块化设计，但仍有一些欠缺可配置性及文档的逻辑被集成在核心（使用 C++ 实现，且不容易改动）而造成问题，如：

  • 头文件搜索使用字符串匹配。
    • 这直接导致在编辑器中无法定位宏名形式的 #include 的路径。
    • 这种形式实际被 YFramework 及 FreeType 使用。
  • 在运行时环境插入 PATH 环境变量的前缀，不保证和构建时相同也不可由用户指定去除。
    • 前缀包括 . 、链接器和调试器的可执行文件所在的路径。
    • 因为是前缀，当前路径及链接器和调试器可执行文件的路径直接污染环境变量，无法通过其它设置去除。
    • 当这些路径具有和构建时不同版本的动态库时，使用 Code::Blocks 运行程序会使用错误的动态库。
    • 因此，使用 Code::Blocks 运行程序时，为了使用正确的动态库，不同的版本的动态库不能和工具链共存。

　　由于这些自身的局限性，Code::Blocks 不适合作为现代的集成开发环境，没有在现状以外其它的改进支持的计划。

　　使用 make 构建适用于使用 Makefile 的平台，当前包括 DS 和 Android 。

　　设 $Configuration 是生成配置名称，则

　　在各个项目目录下运行

make -r BUILD=$Configuration

　　即可生成。

　　在各个项目目录下运行

make -r BUILD=$Configuration rebuild

　　即可重新生成。

　　在各个项目目录下运行

make -r BUILD=$Configuration clean

　　即可清除生成。

注意 因为不同子项目的 makefile 之间不追溯依赖关系，直接运行 makefie 需明确依赖顺序，参见项目依赖性。

　　和其它构建方式类似，YFramework 依赖于 YBase 。对 DS 项目，注意附加的项目依赖性以确定生成顺序：

  • YSTest/DS_ARM9 依赖 YFramework 。
  • YSTest 依赖 YSTest/DS_ARM7 和 YSTest/DS_ARM9 。