OSDN -- Desarrollar y descargar software de código abierto
Translation Status of Español translation status for es
  • R/O
  • SSH
Fork

YSLib-wiki: Commit

The wiki source of YSLib documentation.


Commit MetaInfo

Revisión0614ee20d829ca7f3b429cd8cdfa20be0ff32f2d (tree)
Tiempo2020-12-31 20:38:12
AutorFrankHB <frankhb1989@gmai...>
CommiterFrankHB

Log Message

tools/scripts.zh-cn.md: 添加守卫变量检查并更新 Tools/Scripts/SHBuild-YSLib.sh 的说明；添加 NPLA1 构建脚本支持 sanitizer 附加检查的说明。

Cambiar Resumen

Diferencia incremental

diff -r 372d725bb766 -r 0614ee20d829 Tools/Scripts.zh-CN.md
--- a/Tools/Scripts.zh-CN.md Sat Dec 26 20:56:50 2020 +0800
+++ b/Tools/Scripts.zh-CN.md Thu Dec 31 19:38:12 2020 +0800
@@ -142,6 +142,8 @@
142142
143143 　　**这个脚本是公开的工具**，被 `Tools/install-sysroot.sh` 部署到安装路径下的 `bin` 目录下。
144144
145+**注意** 这个脚本包含 `INC_SHBuild_common` 守卫变量检查，默认重复包含只被执行一次。
146+
145147 ### 函数 SHBuild_Popd
146148
147149 　　同 `bash` 内建 `popd` 但不回显标准输出。
@@ -609,13 +611,40 @@
609611
610612 　　使用 SHBuild 编译并动态链接构建 SHBuild 。依赖 `/usr/lib` 中存在的 YFramework.dll 和 YBase.dll 。
611613
614+## Tools/Scripts/SHBuild-YSLib.sh
615+
616+　　作为 stage 1 SHBuild 公共配置脚本被不同的 stage 1 构建脚本包含。
617+
618+　　包含脚本依次执行：
619+
620+* 初始化变量 [`SHBuild_ToolDir`](../Development.zh-CN.md) 。
621+* 初始化变量 [`YSLib_BaseDir`](../Development.zh-CN.md) 。
622+* 初始化变量 `SHBuild_PCH_stdinc_h` 。
623+* 包含脚本 Tools/Scripts/SHBuild-common-options.sh 。
624+* 赋值变量 `INCLUDE_PCH` 为版本库的 YBase/include/stdinc.h 。
625+* 赋值变量 `INCLUDES` 为版本库目录下的适合作为编译器选项使用的头文件目录列表。
626+* 定义函数。
627+
628+**注意** 这个脚本包含 `INC_SHBuild_YSLib` 守卫变量检查，默认重复包含只被执行一次。
629+
630+### 变量 SHBuild_PCH_stdinc_h
631+
632+　　预编译头文件名称，默认为 "`stdinc.h`" 。
633+
634+### 函数 SHBuild_S1_InitializePCH
635+
636+　　初始化 stage 1 使用的预编译头文件。
637+
638+```
639+SHBuild_CheckPCH "$INCLUDE_PCH" "$SHBuild_PCH_stdinc_h"
640+```
641+
612642 ## Tools/Scripts/SHBuild-YSLib*.txt
613643
614644 　　构建 YSLib 用的 NPLA1 脚本，包含以下文件：
615645
616646 * Tools/Scripts/SHBuild-YSLib-common.txt ：被 `Tools/Scripts/SHBuild-YSLib-build.txt` 加载的 NPLA1 脚本。
617647 * Tools/Scripts/SHBuild-YSLib-build.txt ：使用 SHBuild 构建 debug 或 release 配置的 YBase 和 YFramework 库的 NPLA1 脚本，被 `Tools/install-sysroot.sh` 调用，其中 SHBuild 默认为 stage 1 SHBuild 。
618-* Tools/Scripts/SHBuild-YSLib.sh ：当前被保留。
619648
620649 　　调用方式详见 [stage 1 SHBuild 中关于 NPL 支持的说明](SHBuild.zh-CN.md)。
621650
@@ -623,19 +652,22 @@
623652
624653 ### Tools/Scripts/SHBuild-YSLib-common.txt
625654
626-　　`Tools/Scripts/SHBuild-YSLib-common.txt` 包含一些公共的库，包括支持类似 `Tools/Scripts/SHBuild-common-options.sh` 和 `Tools/Scripts/SHBuild-common-toolchain.sh` 的选项以环境变量的方式配置，但 C 编译器相关的选项除外（不使用而被忽略）。除[关于 shell 和 NPLA1 脚本之间的一般差异](../Development.zh-CN.md)外，和 `Tools/Scripts/SHBuild-common-options.sh` 和 `Tools/Scripts/SHBuild-common-toolchain.sh` 的不同为：
655+　　`Tools/Scripts/SHBuild-YSLib-common.txt` 包含一些公共的库，包括支持类似 `Tools/Scripts/SHBuild-common-options.sh` 和 `Tools/Scripts/SHBuild-common-toolchain.sh` 的选项以环境变量的方式配置，但 C 编译器相关的选项除外（不使用而被忽略）。
656+
657+　　除[关于 shell 和 NPLA1 脚本之间的一般差异](../Development.zh-CN.md)外，和 `Tools/Scripts/SHBuild-common-options.sh` 和 `Tools/Scripts/SHBuild-common-toolchain.sh` 的不同为：
627658
628659 * 通过调用函数进入**构建环境变量检测**并在之后进入回调函数中构建。
629660 * 按需初始化变量。构建环境变量检测可能延迟访问以避免不必要初始化的值。配置时为确定变量的默认值的检查的调用顺序可能不同。
630661 * 使用 debug 模式时，`CXXFLAGS_OPT_DBG` 设置为 `-O0 -g -D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC` ，不再被环境变量覆盖。
631662 * 生成变量默认值的选项之间的空白符可能不同（通常可确保为一个空格）。
632- * 附加支持构建应用的配置，在导出的 `LDFLAGS` 的值中添加 `LIBS_RPATH`（参见以下有关内说明）的值。
663+ * 附加支持构建应用的配置，在导出的 `LDFLAGS` 的值中添加 `LIBS_RPATH`（参见以下相关说明）的值。
664+ * 附加检查 [sanitizer](https://github.com/google/sanitizers/wiki) （参见以下相关章节的说明）。
633665 * 支持更多变量和默认值。除非另行指定，这些变量在构建环境变量检测中使用。参见以下各节。
634666 * 提供部分和 shell 脚本不同的函数，详见版本库中的 `doc/NPL.txt` 。
635667
636668 　　这个脚本被 `Tools/Scripts/SHBuild-YSLib-build.txt` 加载，并被 `Tools/install-sysroot.sh` 间接调用。
637669
638-　　可以在外部调用这个脚本的命令行设置变量以覆盖直接指定构建环境变量检测确定的选项，如：
670+　　脚本支持外部调用这个脚本的命令行设置变量的默认值，以覆盖直接指定构建环境变量检测确定的选项，如：
639671
640672 ```
641673 CXX=clang++ CXXFLAGS='-std=c++11 -O2' Tools/install-sysroot.sh
@@ -673,6 +705,18 @@
673705
674706 　　可执行文件名后缀。在 Win32 默认为 `.exe` ，其它平台默认不设置。
675707
708+### Sanitizer 检查支持
709+
710+　　构建环境变量检测支持 sanitizer ：若在变量 `CFLAGS`、`CXXFLAGS`、`LDFLAGS` 或 `SHBuild_CXXFLAGS` 中包含启用被支持的 sanitizer 的选项 （以 `-fsanitizer=address` 起始），配置最终在 `CFLAGS`、`CXXFLAGS` 和 `LDFLAGS` 最后添加自动调整的选项。
711+
712+　　构建配置支持 ASan、 TSan、 MSan、 UBSan 和 LSan 。Sanitizer 自身支持的系统和编译器详见 sanitizer 的文档。
713+
714+　　ASan 使用的选项要求和建议参见 [FAQ](https://github.com/google/sanitizers/wiki/AddressSanitizer#faq) 。
715+
716+**注意** [GCC 不支持 MSan](https://gcc.gnu.org/legacy-ml/gcc/2014-10/msg00006.html) 。 MSan 要求标准库[使用带 MSan 的选项构建](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo)，否则[会有假阳性结果](https://github.com/google/sanitizers/issues/542)。
717+
718+**注意** 具体调整的选项参见脚本具体实现，不保持构建版本之间稳定。* **注意** 构建脚本不保证构建的二进制程序的具体可用性。构建的程序可能因为程序及 sanitizer 实现的缺陷运行时出错，可能另需具体排查原因修复。
719+
676720 ### SHBuild 附加构建选项环境变量
677721
678722 　　若回调函数中调用 SHBuild 构建，可在此之前设置**扩展环境变量**并调用函数 `SHBuild_Extend_CallVariables` 以更新被 SHBuild 使用的环境变量 `LDFLAGS` 和 `LIBS` 的值。这些影响 SHBuild 工具调用构建工具的命令行的 **SHBuild 附加构建选项环境变量**，包括：
Show on old repository browser