OSDN -- 开发和下载开源软件
简体中文翻译状态 translation status for zh
  • R/O
  • SSH
Fork

YSLib-wiki: 提交

The wiki source of YSLib documentation.


Commit MetaInfo

修订版2b9e9c31e82eea1602f16c07b64d847f60221367 (tree)
时间2023-09-20 23:18:03
作者FrankHB <frankhb1989@gmai...>
CommiterFrankHB

Log Message

tools/scripts.zh-cn.md: 更新说明：
补充变量可设置为只读和内部名称的约定；
更新函数和变量初值的说明；
修复函数 shbuild_checkuname 和 shbuild_install_link 的说明；
修复版本控制系统支持中的列表缩进；
修复 tools/scripts/shbuild-yslib-build.txt 外部构建配置的说明。

更改概述

    差异

    diff -r 35437388e17c -r 2b9e9c31e82e Tools/Scripts.zh-CN.md
    --- a/Tools/Scripts.zh-CN.md Fri Sep 15 13:37:50 2023 +0800
    +++ b/Tools/Scripts.zh-CN.md Wed Sep 20 22:18:03 2023 +0800
    @@ -2,7 +2,13 @@
    22
    33 　　YSLib 项目提供一系列工具脚本。这些脚本主要集中位于 `Tools` 和 `Tools/Scripts` 。其余特定局部用途的脚本可能位于其它目录，这些脚本可能依赖版本库内的工具脚本或 YSLib 安装时部署的工具脚本。
    44
    5-　　关于脚本的解释环境和其它一般规则，参见[关于脚本的开发说明](../Development.zh-CN.md#脚本)。
    5+　　关于脚本的解释环境和其它一般规则，参见[关于脚本的开发说明](../Development.zh-CN.md#脚本)。关于 shell 脚本，同时参见 [shell 语言使用规约](../Development.zh-CN.md#shell-语言使用规约)。
    6+
    7+　　本文档附加约定，除非另行指定：
    8+
    9+* 公开的 shell 脚本和 NPLA1 脚本被 [`Tools/install-sysroot.sh`](#toolsinstall-sysrootsh) 分别部署到安装路径下的 `bin` 和 `share/NPLA1` 目录下。
    10+* 除[用于构建选项的环境配置](#环境配置)外，提供的 shell 变量可能设置为只读。
    11+* 脚本引入不具有后缀 `_` 的名称若不是被导出的变量，可在脚本之间使用，满足关于名称的约束，但不保证接口稳定性。
    612
    713 **注释** 维护者和开发者需要阅读开发说明，以保持脚本程序符合文档的描述。其中的一些信息（如关于环境变量等运行时环境的描述）也可能提供对脚本的非开发者用户有帮助的说明，作为[运行环境](../Run.zh-CN.md)中说明的补充。
    814
    @@ -16,29 +22,71 @@
    1622
    1723 　　一部分工具脚本也可被部署到 [Sysroot](../Sysroot.zh-CN.md) 。在 [stage 2 SHBuild](SHBuild.zh-CN.md#多阶段构建) 安装后运行的脚本可依赖安装的 Sysroot 实例的文件系统布局。支持维护版本库的开发脚本应保证在此之前（不依赖 Sysroot 的实例或仅依赖构建 stage 1 后可用的有限环境）可用。
    1824
    19-　　除非另行指定，公开的脚本 shell 和 NPLA1 脚本被 [`Tools/install-sysroot.sh`](#toolsinstall-sysrootsh) 分别部署到安装路径下的 `bin` 和 `share/NPLA1` 目录下。
    25+## 环境配置
    2026
    21-## 公共构建配置变量
    27+　　一些环境变量可能被可选地在外部环境或在调用脚本的其它脚本中指定。若没有被指定为非空值，则可被特定上下文按需初始化。初始化后的值可能被断言非空，断言失败则非正常地退出脚本。
    28+
    29+　　这些变量可能指定外部环境的配置。
    30+
    31+　　在[开发文档中的环境变量](../Development.zh-CN.md#环境变量)的基础上，以下各节补充指定适用于多个脚本的变量。在对应的脚本的文档中可能补充描述。
    32+
    33+　　一些环境变量具有特定的命名模式：
    34+
    35+* [开发文档](../Development.zh-CN.md)中的环境变量具有相同前缀的外部扩展环境变量：
    36+ * 具有前缀 `SHBuild_` ：可能适用于所有构建脚本流程。
    37+ * **注释** 具有前缀 `SHBuild_S1_` 和 `SHBuild_S2_` 的名称不指定环境变量，而是函数名称。
    38+ * 具有前缀 `YSLib_` ：指定和 YSLib 库相关的环境和配置。
    39+ * **注释** 这些前缀的变量通常在开发文档中指定。仅在个别脚本中适用或不在 shell 脚本（而仅在 NPLA1 脚本）适用时，在本文档指定扩展。
    40+* 具有前缀 `SS_` ：[公共构建配置变量](#公共构建配置变量)。
    41+ * **注释** 环境变量名称中的 `SS` 前缀表示 SHBuild Settings 。
    42+* 具有前缀 `S1_` ：在 [stage 1 SHBuild](SHBuild.zh-CN.md#多阶段构建) 构建流程中作用的变量。
    43+ * **注释** 环境变量名称中的 `SS` 前缀表示 Stage 1 。
    44+* 具有前缀 `CFLAGS` 、`CXXFLAGS` 和 `LDFLAGS` 等：指定构建工具使用的选项。
    45+ * **注释** 在 shell 环境中这主要通过 [`Tools/Scripts/SHBuild-common-options.sh`](#toolsscriptsshbuild-common-optionssh) 配置。
    46+
    47+### 公共构建配置变量
    2248
    2349 　　以下配置行为的环境变量可在多个构建脚本中被支持且具有一致的含义：
    2450
    25-* 除非另行指定，以下变量的值当且仅当非空表示启用特性。
    2651 * `SS_DebugEnv` 启用脚本执行时系统环境相关的调试输出。
    2752 * `SS_DirectExtract` 启用直接解压缩。
    2853 * `SS_NoParallel` 不使用并行命令调用。
    2954 * `SS_Offline` 离线模式：不使用互联网。
    3055 * `SS_Verbose` 启用详细消息输出。
    31-* 具体作用可能在具体脚本的说明中详细描述。
    3256
    33-**注释** 环境变量名称中的 `SS` 前缀表示 SHBuild Settings 。
    57+　　除非另行指定，这些变量的值当且仅当非空表示启用特性。
    58+
    59+　　具体作用可能在具体脚本的说明中详细描述。
    60+
    61+### Stage 1 共享变量
    62+
    63+　　以下变量影响 stage 1 的多个构建脚本的行为。
    64+
    65+* `S1_BuildConf` 内部配置名称。
    66+ * 通常指定不同的值对应不共享的构建配置组合。
    67+ * **注释** 可影响默认构建目录。
    68+* `S1_BuildDir` Stage 1 SHBuild 构建和输出文件目录路径。
    69+* `S1_CacheFile` 缓存文件名。
    70+* `S1_DistDir` Stage 1 SHBuild 可执行程序目录路径。
    71+* `S1_SHBuild` Stage 1 SHBuild 可执行文件路径。
    72+ * **注释** Win32 平台实际的可执行文件可隐含后缀 `.exe` 。
    3473
    3574 ## Tools/install-sysroot.sh
    3675
    3776 　　Sysroot 安装脚本。用于直接构建和部署基础环境。
    3877
    39-　　构建时会调用 `Tools/Scripts` 目录下的脚本，按需构建 [stage 1 SHBuild](SHBuild.zh-CN.md#多阶段构建) 后间接调用 `SHBuild` 构建 `YBase` 和 `YFramework` 的静态库和动态库，再构建依赖于动态库的 `SHBuild` 。
    78+　　构建时会调用 `Tools/Scripts` 目录下的脚本，按需构建 [stage 1 SHBuild](SHBuild.zh-CN.md#多阶段构建) 后间接调用 `SHBuild` 构建 `YBase` 和 `YFramework` 的静态库和动态库，再构建依赖于动态库的 `SHBuild` ：
    4079
    41-　　构建使用变量 `SHBuild_BuildDir` 指定的路径作为中间输出目录，默认为 YSLib 版本库根目录下的 `build/$(SHBuild_GetBuildName)` 目录。
    80+* 按需初始化[变量 `SHBuild_ToolDir`](../Development.zh-CN.md#环境变量) 。
    81+* 包含脚本 [`Tools/Scripts/SHBuild-common.sh`](#toolsscriptsshbuild-common) 以按需初始化确定默认构建位置依赖的环境变量。
    82+* 设置[变量 `S1_BuildConf`](#stage-1-共享变量) 的值，并调用[函数 `SHBuild_S1_InitConf`](#函数-SHBuild_S1_InitConf) 初始化必要的变量，以允许判断是否在预期位置存在 stage 1 SHBuild 。
    83+* 按需构建 stage 1 SHBuild 。
    84+* 间接调用 stage 1 SHBuild 构建 `YBase` 和 `YFramework` 的静态库和动态库。
    85+* 再构建依赖于动态库的 `SHBuild` 。
    86+
    87+　　构建使用[变量 `SHBuild_BuildDir`](../Development.zh-CN.md#环境变量) 指定的路径作为中间输出目录。
    88+
    89+**注释** 另见 [`Tools/Scripts/SHBuild-bootstrap.sh`](#toolsscriptsshbuild-bootstrapsh) 。
    4290
    4391 　　构建脚本同时可安装文件，完成 Sysroot 所需文件的部署。安装的起始目标位置由称为**安装路径**的目录路径指定，其字符串形式去除结尾分隔符的目录文件名为**安装路径前缀**。安装过程在必要时可创建 Sysroot 根目录、安装路径指定的目录及其子目录。安装路径的确定方式详见以下的使用方式。
    4492
    @@ -58,7 +106,6 @@
    58106
    59107 ```bash
    60108 : ${SHBuild_SysRoot:="$YSLib_BaseDir/sysroot"}
    61-SHBuild_PrepareBuild
    62109 : ${SHBuild_BuildDir:="$YSLib_BaseDir/build/$(SHBuild_GetBuildName)"}
    63110 ```
    64111
    @@ -147,7 +194,11 @@
    147194
    148195 　　编译 [stage 1 SHBuild](SHBuild.zh-CN.md#多阶段构建) 时被包含的脚本。
    149196
    150-　　其中指定了静态链接需要依赖的 YSLib 源文件以及头文件路径等。
    197+　　其中指定静态链接需要依赖的 YSLib 源文件以及头文件路径等的必要变量。
    198+
    199+　　按需设置[变量 `S1_BuildConf`](#stage-1-共享变量) 的值，以确保部分变量之后在包含 [`Tools/Scripts/SHBuild-YSLib.sh`](#toolsscriptsshbuild-yslib.sh) 时能被按需初始化。
    200+
    201+* **注释** 有的脚本如 [`Tools/install-sysroot.sh`](#toolsinstall-sysrootsh) 在此之前应已初始化部分变量。其它脚本可能依赖这里的初始化。
    151202
    152203 ## Tools/Scripts/SHBuild-build.sh
    153204
    @@ -230,12 +281,24 @@
    230281
    231282 　　使用 `$*` 形式传递字符串，此时 `IFS` 是默认值。
    232283
    233-　　换行符由变量 `SHBuild_EOL` 指定。当前默认值通过检查 `$COMSPEC` 是否定义，以确保 Windows 环境（包括 MSYS ）使用 CR+LF ，其它情况使用 LF 。
    284+　　换行符由变量 `SHBuild_EOL` 指定。若值为空，则首先初始化为全局只读变量。当前默认值通过检查 `$COMSPEC` 是否定义，以确保 Windows 环境（包括 MSYS ）使用 CR+LF ，其它情况使用 LF 。
    234285
    235286 　　这个函数在可用时可用于代替 `echo` ，以取得对环境更好的适应性。
    236287
    237288 **注意** 具体的检查逻辑实现可能在以后改变。
    238289
    290+### 函数 SHBuild_Puts_Err
    291+
    292+　　同[函数 `SHBuild_Puts`](#函数-shbuild_puts)，但重定向标准输出到标准错误。
    293+
    294+### 函数 SHBuild_Puts_Exit
    295+
    296+　　第一参数指定错误码，以之后的参数调用[函数 `SHBuild_Puts_Exit`](#函数-shbuild_puts_exit)，然后以错误码退出。
    297+
    298+### 函数 SHBuild_Puts_Verbose
    299+
    300+　　当[变量 `SS_Verbose`](#公共构建配置变量) 的值非空时，调用[函数 `SHBuild_Puts`](#函数-shbuild_puts)。
    301+
    239302 ### 函数 SHBuild_AssertNonempty
    240303
    241304 　　断言第一参数为名称的变量非空，否则显示出错并退出。
    @@ -256,7 +319,15 @@
    256319
    257320 　　断言第一参数为名称的变量非空，若空则使用 `eval` 对后续求值并初始化第一参数指定的只读变量。
    258321
    259-　　若发生初始化则在标准输出中显示。
    322+　　初始化时在当前 shell 中求值初值。
    323+
    324+　　若发生初始化且[变量 `SS_Verbose`](#公共构建配置变量) 的值非空，则在标准输出中显示。
    325+
    326+**已知限制** 当前实现使用临时文件 `/tmp/InitReadonly` 暂存作为初值的调用结果。需确保这个临时文件所在的目录和这个文件可写。
    327+
    328+**原理**
    329+
    330+　　保证当前 shell 中求值允许初值中调用可能修改当前 shell 环境的 shell 函数。这使一个 `SHBuild_InitReadonly` 调用中，间接的嵌套调用可使用先前已通过同一个调用者初始化的变量。
    260331
    261332 ### 函数 SHBuild_2m
    262333
    @@ -316,20 +387,20 @@
    316387
    317388 ### 函数 SHBuild_CheckUName
    318389
    319-　　调用 `SHBuild_CheckedCall` 初始化只读变量 `SHBuild_Env_OS` 和 `SHBuild_Env_Arch` 的值。
    390+　　调用 `SHBuild_CheckedCall` 按需初始化只读变量 `SHBuild_Env_OS` 和 `SHBuild_Env_Arch` 的值。
    320391
    321392 　　变量 `SHBuild_Env_OS` 的值通过分类系统的值（一般即 `SHBuild_Env_uname` 的值）标识操作系统：
    322393
    323-* `OS_X` ：输入匹配 \*Darwin\* ，用于标识 OS X 系统
    324-* `Win32` ：输入匹配 \*MIGW\* 或 \*MSYS\* ，用于标识 Windows （桌面）系统
    325-* `Linux` ：输入匹配 \*Linux\* ，用于标识 Linux 系统。
    326-* `unknown` ： 不支持的系统。
    394+* `OS_X` ：输入匹配 `*Darwin*` ，用于标识 OS X 系统。
    395+* `Win32` ：输入匹配 `*MINGW*` 或 `*MSYS*` ，用于标识 Windows 系统。
    396+* `Linux` ：输入匹配 `*Linux*` ，用于标识 Linux 系统。
    397+* `unknown` ：不支持的系统。
    327398
    328399 　　变量 `SHBuild_Env_Arch` 的值通过分类输入的处理器体系结构的值（一般即 `SHBuild_Env_uname_m` 的值）标识体系结构：
    329400
    330-* `x86_64` ：输入匹配 x86_64 或 i*86-64 。
    331-* `i*86` ：输入匹配 i*86 ，使用原值。
    332-* `aarch64` ：输入是 aarch64 。
    401+* `x86_64` ：输入匹配 `x86_64` 或 `i*86-64` 。
    402+* `i*86` ：输入匹配 `i*86` ，使用原值。
    403+* `aarch64` ：输入是 `aarch64` 。
    333404 * `unknown` ：不支持的体系结构。
    334405
    335406 　　若同时指定环境变量 `SHBuild_Env_Arch` 和 `SHBuild_Env_OS` ，不进行[自动环境检测](../Prerequisitions.zh-CN.md)，不依赖 `uname` 。
    @@ -363,9 +434,9 @@
    363434
    364435 ### 函数 SHBuild_Platform_Detect
    365436
    366-　　通过参数指定的操作系统和体系结构名，并结合环境变量，确定平台名称，检查非空并返回。
    437+　　通过参数指定的操作系统和体系结构名，结合环境变量，确定平台名称，检查非空并返回。
    367438
    368-　　第一个和第二个参数分别指定操作系统名和体系结构名，接受的取值参见函数 `SHBuild_CheckUName` 。
    439+　　第一和第二参数分别指定操作系统名和体系结构名，接受的取值参见[函数 `SHBuild_CheckUName`](#函数-shbuild_checkuname) 。
    369440
    370441 　　当前 `Win32` 系统外的结果和 `SHBuild_CheckUName` 初始化 `SHBuild_Env_OS` 的结果一致。处理如下：
    371442
    @@ -383,23 +454,34 @@
    383454
    384455 ### 函数 SHBuild_PrepareBuild
    385456
    386-　　准备构建环境。初始化以下变量使之具有非空值：
    457+　　准备构建环境。按以下方式初始化变量使之具有非空值：
    387458
    388-* `SHBuild_Env_TempDir`
    389-* `SHBuild_Env_Arch`
    390-* `SHBuild_Env_OS`
    391-* `SHBuild_Host_Arch`
    392-* `SHBuild_Host_OS`
    459+* 调用[函数 `SHBuild_GetTempDir`](#函数-shbuild_gettempdir) 初始化 `SHBuild_Env_TempDir` 。
    460+* 调用[函数 `SHBuild_CheckUName`](#函数-shbuild_checkuname) 初始化 `SHBuild_Env_OS` 和 `SHBuild_Env_Arch` 。
    461+* 初始化 `SHBuild_Host_OS` 为 `SHBuild_Env_OS` 的值。
    462+* 当变量 `SHBuild_Host_OS` 的值是 `Win32` 时，且环境变量 `MSYSTEM` 的值是 [MSYS2 支持的环境](https://www.msys2.org/docs/environments/)支持的值，初始化 `SHBuild_Host_Arch` 对应的目标体系结构；否则，初始化 `SHBuild_Host_Arch` 为 `SHBuild_Env_Arch` 的值。
    393463
    394464 ### 函数 SHBuild_GetBuildName
    395465
    396466 　　取用于进一步初始化构建路径的构建名称。
    397467
    398-　　首先断言变量 `SHBuild_Env_Arch` 和 `SHBuild_Env_OS` 非空。结果为以变量 `SHBuild_Env_OS` 和 `SHBuild_Env_Arch` 的值作为参数调用函数 `SHBuild_Platform_Detect` 的结果。
    468+　　首先调用[函数 `SHBuild_PrepareBuild`](#函数-shbuild_preparebuild) 按需初始化变量 `SHBuild_Env_Arch` 和 `SHBuild_Env_OS` 为非空值。
    469+
    470+　　结果为以变量 `SHBuild_Env_OS` 和 `SHBuild_Env_Arch` 的值作为参数调用[函数 `SHBuild_Platform_Detect`](#函数-shbuild_platform_detect) 的结果。
    399471
    400472 ### 函数 SHBuild_BuildGCH
    401473
    402-　　接受第一个参数指定的路径的头文件安装到第二个参数指定的路径下并使用第三个参数指定的命令行构建 GNU 预编译头。
    474+　　构建 GNU 预编译头文件，依次执行：
    475+
    476+* 以第二参数指定的路径附加 `.gch` 后缀确定输出路径。
    477+* 检查输出路径是否已存在文件，若存在则视为目标已被构建，输出消息并跳过以下步骤。
    478+* 确保输出路径所在的目录被创建。
    479+* 输出开始构建的消息。
    480+* 硬链接第一参数指定输入的头文件路径到第二参数指定的安装路径。
    481+* 按第一参数指定的输入路径和输出路径调用第三个参数指定构建命令。
    482+* 输出构建完成的消息。
    483+
    484+**已知限制** 构建命令仅支持 GNU 兼容工具链。
    403485
    404486 ### 函数 SHBuild_CheckPCH
    405487
    @@ -458,15 +540,53 @@
    458540
    459541 ### 函数 SHBuild_Install_Link
    460542
    461-　　接受 2 个表示路径的参数，安装前者指定的可执行文件到后者为符号链接。
    543+　　接受 2 个表示路径的参数，安装前者指定的文件到后者为符号链接。
    462544
    463545 　　首先删除目标，其次调用 Windows 命令解释器的 `mklink` ，若失败调用 `ln` 。
    464546
    465547 **注意** `mklink` 需要 Windows Vista 后的命令解释器(`cmd`) 的支持。符号链接需要文件系统（如 NTFS ）支持。权限不足可能导致 `mklink` 创建符号链接失败，可在组策略改变相关默认行为。在一些版本的系统上，可能需要[进一步的配置](https://support.microsoft.com/en-us/kb/2856739/en-us)以通过链接执行文件。
    466548
    549+### 函数 SHBuild_LoadCache
    550+
    551+　　加载环境缓存。
    552+
    553+　　函数接收 2 个参数，分别是缓存文件路径和被缓存的变量名的正则表达式模式的数组。
    554+
    555+　　加载缓存通过解析文件内容验证后包含实现。
    556+
    557+　　文件的内容应为可执行的 shell 赋值代码。当前检查支持的格式如下：
    558+
    559+* 每行一个条目，忽略首尾空白符。
    560+* 若条目的形式是 `if ... then; ASSIGNMENT; fi` ，简化为 `ASSIGNMENT` 进行下一步检查，忽略其余部分。
    561+* 进一步地，若条目的形式是 `declare -X VAR=...` ，其中 `X` 是匹配正则表达式模式 `(-|[Aairx]+)` 的属性之一，简化为 `VAR` 进行下一步检查，忽略其余部分。
    562+* 进一步地，`VAR` 应为合法的标识符，匹配正则表达式模式 `[A-Za-z_][A-Za-z_0-9]*` 。
    563+
    564+　　若任意检查失败，则缓存格式无效，内容不会被加载；否则，包含缓存文件，以执行其中的赋值代码。
    565+
    566+　　函数的返回值如下：
    567+
    568+* `0` ：成功。
    569+* `1` ：内容无效。
    570+* `2` ：指定的缓存文件无法读取。
    571+
    572+### 函数 SHBuild_SaveCache
    573+
    574+　　保存环境缓存。
    575+
    576+　　函数接受的参数及其含义和[函数 `SHBuild_LoadCache`](#函数-shbuild-loadcache) 一致。
    577+
    578+　　首先打开文件，然后解析 `declare -p` 结果，把其中变量名匹配第二参数中任意的正则表达式且内容满足 函数 `SHBuild_LoadCache` 格式要求的行写入指定的缓存文件。
    579+
    580+**注释** 格式要求不要求支持所有属性。不支持的属性被忽略。
    581+
    582+　　函数的返回值如下：
    583+
    584+* `0` ：成功。
    585+* `2` ：指定的缓存文件无法写入。
    586+
    467587 ### 函数 SHBuild_GetSystemPrefix
    468588
    469-　　按参数指定的平台名称字符串返回系统前缀字符串。
    589+　　转换参数指定的平台名称字符串为系统前缀字符串。
    470590
    471591 　　系统前缀用于在文件系统中安装部署。
    472592
    @@ -480,19 +600,45 @@
    480600
    481601 　　本函数的结果符合 [Sysroot](../Sysroot.zh-CN.md) 中关于 Sysroot 的目录布局的约定。
    482602
    603+**注释** 参数典型地来自调用[函数 `SHBuild_Platform_Detect`](#函数-shbuild_platform_detect) 的结果。
    604+
    605+### 函数 SHBuild_S1_InitConf
    606+
    607+　　初始化 [stage 1 Sysroot](../Sysroot.zh-CN.md) 构建配置，依次执行：
    608+
    609+* 断言[变量 `SHBuild_ToolDir`](../Development.zh-CN.md#环境变量) 非空。
    610+* 按需初始化[变量 `YSLib_BaseDir`](../Development.zh-CN.md#环境变量) ，默认值为 `"$SHBuild_ToolDir/../.."` 。
    611+ * **注释** Stage 1 环境下总是可通过脚本所在目录推断 YSLib 源代码和存储库中的其它源文件的位置。
    612+* 尝试以切换当前目录的方式访问 `$YSLib_BaseDir` 。
    613+* 按需初始化[变量 `SHBuild_BuildDir`](../Development.zh-CN.md#环境变量) ，默认值为 YSLib 版本库根目录下的 `build/$(SHBuild_GetBuildName)` 。
    614+* 确保变量 `SHBuild_BuildDir` 指定的目录被创建，并尝试以切换当前目录的方式访问。
    615+* 若[变量 `S1_BuildDir`](#stage-1-共享变量) 的值为空，断言[变量 `S1_BuildConf`](#stage-1-共享变量) 的值非空。
    616+ * **注释** 这排除以下的初始化默认值使用非预期路径。
    617+* 按需初始化变量 `S1_BuildDir` ，默认值为 `"$SHBuild_BuildDir/.$S1_BuildConf"` 。
    618+* 按需初始化[变量 `S1_DistDir`](#stage-1-共享变量) ，默认值为 `"$S1_BuildDir/.stage1"` 。
    619+* 按需初始化[变量 `S1_SHBuild`](#stage-1-共享变量) ，默认值为 `"$S1_DistDir/SHBuild"` 。
    620+* 确保变量 `S1_BuildDir` 指定的目录被创建，并尝试以切换当前目录的方式访问。
    621+* 确保变量 `S1_DistDir` 指定的目录被创建，并尝试以切换当前目录的方式访问。
    622+
    623+　　以上变量初始化后只读。
    624+
    483625 ### 函数 SHBuild_S2_Prepare
    484626
    485-　　初始化 [stage 2 Sysroot](../Sysroot.zh-CN.md) 环境。
    627+　　准备 [stage 2 Sysroot](../Sysroot.zh-CN.md) 环境，依次执行：
    486628
    487-　　函数可使用一个参数作为变量 `SHBuild_SysRoot` 的默认值。
    488-
    489-　　初始化这个变量后，断言其值非空，以其值作为创建目录，若指定的目录已存在则忽略。然后，初始化变量 `SHBuild_SystemPrefix`（参见 `Tools/Scripts/SHBuild-YSLib-build.txt` 的说明）。之后，初始化变量 `SR_Prefix` 的值为 `"$SHBuild_SysRoot$SHBuild_SystemPrefix"` 。
    629+* 确保变量 `SHBuild_SysRoot` 的初始化。
    630+ * 使用第一参数作为这个变量的默认值。若变量这个未被设置，则以默认值赋值。
    631+* 断言这个变量的值非空，以其值作为创建目录，若指定的目录已存在则忽略。
    632+* 初始化变量 `SHBuild_SystemPrefix` 。
    633+ * **注释** 参见 [`Tools/Scripts/SHBuild-YSLib-build.txt`](#toolsscriptsshbuild-yslib-buildtxt) 的说明。
    634+* 初始化变量 `SR_Prefix` 的值为 `"$SHBuild_SysRoot$SHBuild_SystemPrefix"` 。
    490635
    491636 ### 函数 SHBuild_S2_Prepare_Build
    492637
    493-　　初始化 stage 2 Sysroot 构建环境。
    638+　　准备 stage 2 Sysroot 构建环境，依次执行
    494639
    495-　　函数可使用一个参数。以这个参数调用 `SHBuild_S2_Prepare` ，然后导出变量 `SHBuild` 的值为 `"$SR_Prefix/bin/SHBuild"` 。
    640+* 以第一参数调用 `SHBuild_S2_Prepare` 。
    641+* 导出变量 `SHBuild` 的值为 `"$SR_Prefix/bin/SHBuild"` 。
    496642
    497643 ## Tools/Scripts/SHBuild-common-options.sh
    498644
    @@ -774,18 +920,34 @@
    774920 * `LD`
    775921 * 默认值为变量 `CXX` 的值。
    776922
    777-　　关于 `MSYSTEM` 指定的环境和使用的工具链的对应关系，参见 [MSYS2 支持的环境](https://www.msys2.org/docs/environments/)；关于支持的 `MSYSTEM` 的值和 MSYS2 环境，另见函数 `SHBuild_Platform_Detect` 。
    923+　　关于 `MSYSTEM` 指定的环境和使用的工具链的对应关系，参见 [MSYS2 支持的环境](https://www.msys2.org/docs/environments/)；关于支持的 `MSYSTEM` 的值和 MSYS2 环境，另见[函数 `SHBuild_Platform_Detect`](#函数-shbuild_platform_detect) 。
    778924
    779-　　以下只读变量在初始化配置时被初始化：
    925+　　以下只读变量在初始化配置时被按需初始化并断言非空：
    780926
    781-* `SHBuild_CXX_Name` ：C++ 编译器名称，在确定 `CXXFLAGS` 和 `AR` 等配置变量的默认值值前初始化。参见函数 `SHBuild_CheckCXX` 。
    782-* `SHBuild_CXX_Version` ：C++ 编译器版本号。参见函数 `SHBuild_CXX_GetVersion` 。
    927+* `SHBuild_CC_Name` ：C 编译器名称。
    928+ * 在调用函数 `SHBuild_CC_GetVersion` 时被首先初始化。
    929+ * 初值是 `$CC` 作为参数调用函数 `SHBuild_CheckCC` 的结果。
    930+* `SHBuild_CC_Version` ：C 编译器版本号。
    931+ * 当前未使用。
    932+ * 初值是调用函数 `SHBuild_CC_GetVersion` 的结果。
    933+* `SHBuild_CXX_Name` ：C++ 编译器名称。
    934+ * 在调用[函数 `SHBuild_CXX_GetVersion`](#函数-shbuild_cxx_getversion) 时被首先初始化。
    935+ * 在脚本 [`Tools/Scripts/SHBuild-common-toolchain.sh`](#toolsscriptsshbuild-common-toolchainsh) 确定 `AR` 的默认值值前初始化。
    936+ * 在脚本 [`Tools/Scripts/SHBuild-common-options.sh`](#toolsscriptsshbuild-common-optionssh) 确定 `CXXFLAGS` 等其它配置变量的默认值值前初始化。
    937+ * 初值是 `$CXX` 作为参数调用函数 `SHBuild_CheckCXX` 的结果。
    938+* `SHBuild_CXX_Version` ：C++ 编译器版本号。
    939+ * 在脚本 `Tools/Scripts/SHBuild-common-toolchain.sh` 确定 C++ 版本号前初始化。
    940+ * 初值是调用函数 `SHBuild_CXX_GetVersion` 的结果。
    941+
    942+　　上述按需初始化使用[函数 `SHBuild_InitReadonly`](#函数-shbuild_initreadonly)。
    943+
    944+**注释** 可通过外部执行环境指定这些变量具有非空值而跳过初始化。
    783945
    784946 　　**这个脚本是公开的工具**，被安装脚本部署。
    785947
    786948 ### 函数 SHBuild_CheckCompiler
    787949
    788-　　尝试调用以参数指定的编译器，并按检查结果选择和输出参数的值。
    950+　　尝试以参数指定的编译参数和输入调用参数指定的编译器，并按检查结果选择和输出参数的值。
    789951
    790952 　　检查编译器时，首先排除参数指定的编译器不可执行的情形，然后通过尝试编译以参数指定的源程序进行。
    791953
    @@ -801,25 +963,33 @@
    801963
    802964 　　结果是以下之一：
    803965
    804-* 空值（第一参数指定不可执行的路径）
    805-* 第三参数（检查成功时的结果）
    806-* 第四参数（检查失败时的结果）
    966+* 空值（第一参数指定不可执行的路径）。
    967+* 第三参数（检查成功时的结果）。
    968+* 第四参数（检查失败时的结果）。
    807969
    808970 ### 函数 SHBuild_CheckCC
    809971
    810-　　尝试调用参数指定的编译器以检查 C 编译器风格。结果是以下之一：
    972+　　尝试调用参数指定的编译器以检查 C 编译器风格。
    811973
    812-* 空值（不支持的编译器）
    813-* `Clang`
    814-* `GCC`
    974+　　第一参数指定编译器可执行文件路径。
    975+
    976+　　结果是以下之一：
    977+
    978+* 空值（不支持的编译器）。
    979+* `Clang` 。
    980+* `GCC` 。
    815981
    816982 ### 函数 SHBuild_CheckCXX
    817983
    818-　　尝试调用参数指定的编译器以检查 C++ 编译器名称。结果是以下之一：
    984+　　尝试调用参数指定的编译器以检查 C++ 编译器名称。
    819985
    820-* 空值（不支持的编译器）
    821-* `Clang++`
    822-* `G++`
    986+　　第一参数指定编译器可执行文件路径。
    987+
    988+　　结果是以下之一：
    989+
    990+* 空值（不支持的编译器）。
    991+* `Clang++` 。
    992+* `G++` 。
    823993
    824994 ### 函数 SHBuild_CC_Test
    825995
    @@ -833,6 +1003,8 @@
    8331003
    8341004 　　测试 `"$CC"` 指定的编译器 C 编译器命令行编译最小程序是否可成功调用。
    8351005
    1006+　　参数指定编译选项。
    1007+
    8361008 　　以 `SHBuild_CC_Test` 实现编译器调用。
    8371009
    8381010 　　使用的最小程序是 `int main(void){return 0;}` 。
    @@ -849,6 +1021,8 @@
    8491021
    8501022 　　测试 `"$CXX"` 指定的编译器 C++ 编译器命令行编译最小程序是否可成功调用。
    8511023
    1024+　　参数指定编译选项。
    1025+
    8521026 　　以 `SHBuild_CXX_Test` 实现编译器调用。
    8531027
    8541028 　　使用的最小程序是 `int main(){}` 。
    @@ -895,23 +1069,28 @@
    8951069
    8961070 　　包含脚本依次执行：
    8971071
    898-* 初始化变量 [`SHBuild_ToolDir`](../Development.zh-CN.md#环境变量) 。
    899-* 初始化变量 [`YSLib_BaseDir`](../Development.zh-CN.md#环境变量) 。
    900-* 初始化变量 `SHBuild_PCH_stdinc_h` 。
    901-* 包含脚本 [`Tools/Scripts/SHBuild-common-options.sh`](#toolsscriptsshbuild-common-optionssh) 。
    902-* 赋值变量 `INCLUDE_PCH` 为指定版本库下 `YBase/include/stdinc.h` 的路径字符串。
    903-* 赋值变量 `INCLUDES` 为版本库目录下的适合作为编译器选项使用的头文件目录列表。
    904-* 定义函数。
    1072+* 按需初始化[变量 `SHBuild_ToolDir`](../Development.zh-CN.md#环境变量) 。
    1073+* 包含脚本 [`Tools/Scripts/SHBuild-common.sh`](#toolsscriptsshbuild-common) 以按需初始化确定默认构建位置依赖的环境变量。
    1074+* 调用[函数 `SHBuild_S1_InitConf`](#函数-shbuild_s1_initconf) 初始化 stage 1 SHBuild 配置。
    1075+* 初始化缓存：
    1076+ * 按需初始化[变量 `S1_CacheFile`](#stage-1-共享变量) ，默认值为 `"$S1_BuildDir/config.cache"` 。
    1077+ * 初始化缓存配置并调用[函数 `SHBuild_LoadCache`](#函数-shbuild_loadcache) 加载缓存。
    1078+* 初始化 stage 1 公共构建资源和配置：
    1079+ * 按需初始化[变量 `SHBuild_PCH_stdinc_h`](#变量-shbuild_pch_stdint_h) 。
    1080+ * 包含脚本 [`Tools/Scripts/SHBuild-common-options.sh`](#toolsscriptsshbuild-common-optionssh) 以按需初始化构建工具使用的选项。
    1081+ * 初始化变量 `INCLUDE_PCH` 为指定版本库下 `YBase/include/stdinc.h` 的路径字符串。
    1082+ * 初始化变量 `INCLUDES` 为版本库目录下的适合作为编译器选项使用的头文件目录列表。
    1083+* 定义函数（参见以下各节）。
    9051084
    9061085 **注意** 这个脚本包含 `INC_SHBuild_YSLib` 守卫变量检查，默认重复包含只被执行一次。
    9071086
    9081087 ### 变量 SHBuild_PCH_stdinc_h
    9091088
    910-　　预编译头文件名称，默认为 "`stdinc.h`" 。
    1089+　　预编译头文件名称，默认值为 `"$S1_BuildDir/stdinc.h"` 。
    9111090
    9121091 ### 函数 SHBuild_S1_InitializePCH
    9131092
    914-　　初始化 stage 1 使用的预编译头文件。
    1093+　　初始化 stage 1 使用的预编译头文件：即调用：
    9151094
    9161095 ```
    9171096 SHBuild_CheckPCH "$INCLUDE_PCH" "$SHBuild_PCH_stdinc_h"
    @@ -926,7 +1105,7 @@
    9261105
    9271106 　　调用方式详见 [stage 1 SHBuild 中关于 NPL 支持的说明](SHBuild.zh-CN.md)。
    9281107
    929-　　可通过外部环境变量配置脚本行为。
    1108+　　可通过[外部环境变量](#环境配置)配置脚本行为。
    9301109
    9311110 ### 版本控制系统支持
    9321111
    @@ -941,9 +1120,9 @@
    9411120 　　命令可用需要满足以下条件：
    9421121
    9431122 * 被检查的命令应在 `$PATH` 中。
    944- * 若在 Windows 中使用 shell ，可能需要提前设置环境以确保继承环境变量。
    945-　　* **注意** MSYS2 提供的 `mercurial` 包的可执行文件是脚本而不是可执行文件，不被 NPLA1 脚本调用的 Windows 命令行支持。
    946-　　* **注释** 不使用 `HG` 环境变量，因为可能设置为不被支持的 `hg` 程序路径。事实上，MSYS2 的包 `mercurial` 安装到 `/etc/profile.d/mercurial.sh` 设置 `HG` 为脚本，覆盖从其它位置继承的 `hg.exe` 。
    1123+ * 若在 Windows 中使用 shell ，可能需要提前设置环境以确保继承环境变量。
    1124+ * **注意** MSYS2 提供的 `mercurial` 包的可执行文件是脚本而不是可执行文件，不被 NPLA1 脚本调用的 Windows 命令行支持。
    1125+ * **注释** 不使用 `HG` 环境变量，因为可能设置为不被支持的 `hg` 程序路径。事实上，MSYS2 的包 `mercurial` 安装到 `/etc/profile.d/mercurial.sh` 设置 `HG` 为脚本，覆盖从其它位置继承的 `hg.exe` 。
    9471126 * 且当前工作目录求在对应的版本库中，同时确定仓库的顶层目录路径。
    9481127 * 对 Git ，要求存在工作区。　
    9491128
    @@ -1089,7 +1268,7 @@
    10891268
    10901269 　　脚本使用 [`Tools/Scripts/SHBuild-YSLib-common.txt`](#toolsscriptsshbuild-yslib-commontxt) 中提供的一些函数。
    10911270
    1092-　　脚本支持 `SHBuild_` 为前缀的环境变量指定构建和部署目标：
    1271+　　脚本支持以下[外部扩展环境变量](#环境配置)指定构建和部署目标：
    10931272
    10941273 * `SHBuild_UseDebug` 非空时启用构建和安装 debug 配置的库。
    10951274 * `SHBuild_UseRelease` 非空时启用构建和安装 release 配置的库。
    @@ -1130,7 +1309,7 @@
    11301309 * 默认值以 `-I` 起始，使用版本库目录下的 `3rdparty/freetype/include` 目录带有适当引号的完整路径。
    11311310 * [环境变量 `SHBuild_VCS_hg` 或 `SHBuild_VCS_git`](../Development.zh-CN.md#环境变量) 指定构建时的版本控制系统，作用参见以下说明。
    11321311
    1133-　　在 stage 2 环境中构建其它目标时接受以下外部环境变量（部分被 SHBuild 直接以环境变量的方式接受）：
    1312+　　在 stage 2 环境中构建其它目标时接受以下[外部环境变量](#环境配置)（部分被 SHBuild 直接以环境变量的方式接受）：
    11341313
    11351314 * `INCLUDES` ：包含路径，和非 SHBuild 中的 `Makefile` 惯用法含义类似。
    11361315 * `LDFLAGS` ：链接命令行选项。
    @@ -1142,7 +1321,7 @@
    11421321
    11431322 　　在 stage 1 构建 YFramework 前，通过选择的版本控制系统指定确定版本字符串，可在被构建的 YFramework 库中引用。
    11441323
    1145-　　确定版本字符串时，检查对应的命令，具体方式详见以上关于版本控制系统支持的描述。若检查都失败，则版本字符串为空串。否则，使用第一个检查成功的命令生成对应的版本字符串。
    1324+　　确定版本字符串时，检查对应的命令，具体方式详见关于[版本控制系统支持](#版本控制系统支持)的描述。若检查都失败，则版本字符串为空串。否则，使用第一个检查成功的命令生成对应的版本字符串。
    11461325
    11471326 **已知限制** 若使用 `git` 生成版本字符串，当前同时依赖 `sed` 命令。
    11481327
    Show on old repository browser