# 准备

* 参见[开发说明](Development.zh-CN.md)
* 参见[项目依赖性](ProjectDependencies.zh-CN.md)了解 YSLib 子项目之间的联系

# 外部依赖项构建

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

　　YSLib 发布的文件和对应使用的外部依赖项（包括二进制的库文件）可以[从归档仓库下载](Archives.zh-CN.md)。

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

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

# 库和示例程序构建

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

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

　　另见[构建文档](BuildDocumentation.zh-CN.md)。

## 使用构建工具和脚本

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

　　基本使用详见 [SHBuild](Tools/SHBuild.zh-CN.md) 和 [Sysroot](Sysroot.zh-CN.md) 。

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

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

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

## Microsoft Visual Studio

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

**注释** 早期支持可追溯到 Microsoft Visual Studio 2012 。当前仅对提交时的正式发布的 Microsoft Visual Studio 最新版本和前一个正式版本提供支持。这里的支持仅包括集成开发环境可打开其中的文件，不保证其中的构建工具可用。

　　当前包含了平台中立项目（便于源代码管理，不实际生成）、DS 项目 、MinGW32 项目和 Android 项目，但仅支持生成使用 make 的平台（ DS 和 Android ，需要对应的工具链支持）。

　　因为正确支持的语言特性不足或存在缺陷，Visual Studio 使用的工具链不保证正常生成其中的 Win32 项目，仅有以下不依赖 YSLib 主要输出目标的项目被支持：

* `Tools/CreationTimeManager`
* `Tools/PredefinedMacroDetector`

　　使用 Microsoft Visual Studio 打开文件，需特定的环境变量以保证使用 makefile 的项目可构建。以下（使用兼容 [shell 语言](Development.zh-CN#shell-脚本)的）路径仅为示例：

　　DS 项目：

```shell
DEVKITPRO=/opt/devkitpro
```

　　Android 项目：

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

**注意** Visual Studio 项目使用的 makefile 命令行依赖 `bash` 以便及时检测到错误停止生成，可参见[先决条件](Prerequisitions.zh-CN.md)配置[宿主环境](Terminology.zh-CN.md#环境)。

　　支持生成的 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](Tools/Scripts.zh-CN.md#toolsscriptsgenerateprojectssh) 生成 `.cbp` 文件。

　　和 Visual Studio 不同，生成 `.cbp` 的项目文件的内容不保证随[提交版本](Releases.zh-CN.md#迭代阶段)保持最新。这些文件以后仅保证在[发布版本](Releases.zh-CN.md)更新。

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

　　因为编译时使用的文件路径和可能存在动态确定的个别选项不同等原因，构建的二进制文件和通过 SHBuild 和 Sysroot 环境构建的输出不完全等价，但受支持的功能相同。

## make 命令行

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

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

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

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

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

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

　　在各个项目目录下运行

```shell
make -r BUILD=$Configuration
```

　　即可生成。

　　在各个项目目录下运行

```shell
make -r BUILD=$Configuration rebuild
```

　　即可重新生成。

　　在各个项目目录下运行

```shell
make -r BUILD=$Configuration clean
```

　　即可清除生成。

**注意** 因为不同子项目的 makefile 之间不追溯依赖关系，直接运行 makefie 需明确依赖顺序，参见[项目依赖性](ProjectDependencies.zh-CN.md)。

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

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