概述

　　Sysroot 是具有特定逻辑布局根目录兼容的目录，一般在文件系统中实现。

　　Sysroot 主要用于本机程序的开发环境构建和部署，以后也可能用于交叉构建。

　　在利用 Sysroot 开发之前有必要了解开发注意事项：

　　Sysroot 使用的文件系统路径满足运行环境对外部文件的路径的约定。

　　当前 Sysroot 仅支持 MinGW 和 Linux 环境。

　　关于本文档讨论以外的脚本的其它行为，参见脚本的有关说明。

布局

　　在满足前述要求的前提下，Sysroot 部署实例使用局部 FHS 目录布局，具体子目录布局如下：

  • .shbuild ：使用 SHBuild 构建时的临时目录（可以在部署后手动删除）。
  • 系统前缀字符串指定的作为安装路径前缀的最后一个路径组件的目录文件名（如 usr ）：被部署的用户空间目录，其中的内容使用 Linux 等现代 UNIX 变体类似的约定：
    • bin ：二进制文件。
    • include ：头文件。
    • lib ：库文件。
    • share ：共享的数据文件。
      • share/NPLA1 ：NPLA1 脚本部署位置。
    • var ：程序运行时可修改的数据。

　　其中，除 var 外，这些目录中的内容在安装或维护部署情形外通常应保持只读。

　　对 MSYS2 支持的宿主和目标平台，系统前缀字符串指定的路径和 MSYS2 构建系统的 /etc/msystem 脚本指定的 MSYSTEM_PREFIX 的值一致，直接构成环境路径前缀。

  • 对 MinGW32 和 MinGW64 ，这也对应 MSYS2 支持的子系统路径。
  • MSYS2 可能支持其它平台的组合，可能直接可用，但并不保证每个配置都提供支持和被测试。详见先决条件中关于平台的描述。

　　上述 bin 目录可以加入环境变量 PATH 中以便其中的程序被命令行执行。当前若使用 YDE 构建脚本，这是必要的。

　　依赖 Sysroot 的程序可预期以上布局符合约定，且功能允许时可访问这些子目录或其它文件，而不被要求能在不符合预期的环境下正常运行。这些程序可能根据上述子目录中的内容判断需要的不同操作。安装或者维护 Sysroot 布局的程序提供附加的保证，不依赖全部或者部分路径符合预期，而在必要时可创建文件使布局满足这些预期。具体的操作可在不同程序的功能描述中明确。

　　没有在此约定的 Sysroot 中的子目录和其它文件路径为未来的版本保留：这些路径不被当前版本使用，但可能被之后的版本使用。依赖 Sysroot 的程序和用户应注意避免占用保留路径引起变更版本时引起的兼容问题。

注意 Sysroot 实例的布局不是版本库文件布局。关于部署文件时有关被部署的文件的要求，参见版本库文件布局中的相关约定。

原理

　　文件系统子目录的约定和 FHS 类似。

　　对 NPLA1 文件，因为脚本并非二进制文件而对体系结构中立，使用 share 子目录。脚本不被视为可能依赖具体体系结构的二进制库文件（位于 lib 为前缀的子目录）。若未来需要部署二进制文件或作为库的二进制可执行文件，可部署到 lib 和 libexec 等子目录。这也类似 Guile 等语言实现使用的惯例；但当前没有指定其中的下级子目录。

　　在程序中实现局部 FHS 目录布局可能需要特定宿主环境的支持，以定位可执行文件映像路径，例如：

　　若不存在这样的支持，则需在运行时配置中指定。

安装脚本

　　YSLib 项目提供生成可打包的 Sysroot 的安装脚本，位于 Tools/Scripts/install-sysroot.sh 。输出的 Sysroot 的默认位置为版本库根目录下的 sysroot 目录。安装 Sysroot 时构建和部署多个项目，详见以下各节。

基本安装

　　使用 SHBuild 构建和部署运行环境，包括库和工具。

建议阅读以下关于选项以及脚本说明后再运行命令。

　　可进入 bash 运行以下 GNU bash 脚本：

Tools/install-sysroot.sh

　　直接在默认输出位置构建和部署基础环境。

注意 当前构建脚本默认使用 uname 判断构建系统的体系结构。对 MSYS2 等环境，结果为基本系统的体系结构而不一定和作为构建目标的宿主系统相同。如使用 64 位基本系统构建 32 位目标，需确保环境变量 MSYSTEM 设置为 MINGW32（在启动 MSYS2 提供的 shell 入口时应正确设置，但直接调用 bash 并不保证），或使用以下命令代替：

SHBuild_Host_Arch=i686 Tools/install-sysroot.sh

　　此处自动环境检测的机制同 shell 脚本 Tools/Scripts/SHBuild-common.sh 中的函数 SHBuild_PrepareBuild ，详见脚本的说明。

自动下载安装外部依赖项

　　通过设置环境变量 YSLib_DistDir 为非空的路径 ，可在构建前自动按需获取源代码外的二进制库外部依赖项。

已知问题 启用 LTO 的 release 配置的二进制文件可能依赖具体的工具链；具体参见 YSLib 项目文档的 doc/Dependencies.txt 。若使用不同的工具链，二进制文件不兼容，需要回退旧版不使用 LTO 构建的二进制库文件，而无法全自动支持 release 配置的构建。例如，对 Linux 平台，V0.9 后的归档的 External-0.9.7z 都启用了 LTO 而不能保证和用户使用的工具链匹配，此时可能需要手动构建和部署其中的 libFreeImage.a 文件到源代码的 YFramework/Linux/lib 目录下。

注意 用 debug 配置的二进制文件 libFreeImaged.a 覆盖 libFreeImage.a 可能成功，但这种方式不被支持。

构建和部署

　　构建过程包括 SHBuild 可用的多阶段构建。

　　构建时在 Sysroot 输出目录种保存中间输出。当前不清理这些中间输出。

　　通过脚本选项，在 stage 2 SHBuild 需要的库时，也可生成其它的 YSLib 库（静态库和调试版本的库）。

　　YSLib 库和依赖的外部的第三方库的二进制文件和对应的头文件在构建后被部署到 Sysroot ，并在之后用于构建 stage 2 SHBuild 。

　　完成构建 stage 2 SHBuild 后，脚本部署 stage 2 SHBuild 和脚本（参见以下节）到 Sysroot 。

脚本部署

　　在 stage 2 SHBuild 构建后，部署 SHBuild 同时安装（复制）版本库中的以下位置的 脚本文件（无视路径前缀）到 Sysroot 的对应安装路径：

  • NPLA1 脚本安装到 share/NPLA1 ：
    • Tools/Script/SHBuild-BuildApp.txt
    • Tools/Script/SHBuild-YSLib-common.txt
  • Shell 脚本安装到 bin ：
    • Tools/Script/SHBuild-common.sh
    • Tools/Script/SHBuild-common-options.sh
    • Tools/Script/SHBuild-common-toolchain.sh
    • Tools/Script/SHBuild-BuildApp.sh
    • Tools/Script/SHBuild-BuildPkg.sh

可选工具

　　通过脚本选项，在部署 stage 2 SHBuild 后，也可安装 Tools 下的其它工具：

构建中间文件

　　当前工具不对构建的中间文件显式管理。若需清理，可以手动删除对应的文件或所在的生成目录。一般生成的文件和源代码的目录结构对应。

　　若需要预编译头文件在后续重复构建时的性能提升，或者意图重新生成这些文件，可以手动清理这些文件。预编译头文件一般在对应项目生成其它的文件的顶层目录相同；可手动搜索构建目录中所有 .gch 文件并删除后再运行构建脚本。默认生成预编译头文件前硬链接被预编译的头文件并在同一个目录中生成，包括以下位置：

构建时的诊断

　　一些构建时的诊断可被安全忽略：

　　若不需要使用预编译头文件或仅需要避免警告，可参考脚本的说明设置变量跳过预编译头文件或添加忽略警告的选项。

Sysroot 开发指令

　　使用 Sysroot 开发，首先需安装 Sysroot 环境，参见以上安装脚本的说明。

应用程序构建脚本

　　YSLib 应用程序可使用 SHBuild 构建。为简化构建流程，使用应用程序构建脚本包装对 SHBuild 的调用。

　　应用程序构建脚本不限制实现使用的语言，但在版本库中提供的脚本应符合公共的约定；此外，具体脚本可能需要指定适当的 PATH 以确保外部的工具可被调用。

　　典型地，应用程序构建脚本是 shell 脚本，可依赖 Sysroot 环境已构建的 Sysroot 环境，并调用 NPLA1 脚本。

　　YSTest 支持使用脚本 /YSTest/SHBuild-YSTest.sh 构建，可作为例子参考。和其它在安装脚本部署的 stage 2 应用不同，当前默认情况下使用版本库中的 build 目录下的平台目录存放生成的文件（中间文件和生成的可执行程序示例）。

部署

　　除安装脚本外，当前不提供直接部署程序。

　　参照运行确定二进制依赖项位置和调整运行时的配置。