准备

外部依赖项构建

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

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

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

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

库和示例程序构建

  以下描述构建项目的默认目标:库和示例程序。

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

  另见构建文档

SHBuild

  宿主平台的建议方式。

  详见 SHBuildSysroot

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

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 。