概述

  YSLib 项目提供一系列工具脚本。这些脚本主要集中位于 ToolsTools/Scripts 。其余特定局部用途的脚本可能位于其它目录。

解释环境

  脚本解释器要求宿主环境(符合 YSLib 源码 YF_Hosted 定义支持的平台,指具有操作系统的环境)。

  除非另行指定,脚本以文件的形式部署。

脚本文件

  脚本文件总是使用以下约定的扩展名。

  除了 Windows 命令解释器使用的 .cmd 文件以及 NPLA1 脚本使用的 .txt 文件,所有脚本使用 Shebang 明确需要使用的解释环境(详见 Shell 脚本的说明)。

  Windows 命令解释器脚本因为实现限制使用本机 ANSI 代码页的编码,约定为兼容 ASCII 。

  NPLA1 脚本约定使用带有 BOM 的 UTF-8 编码(去除 BOM 的脚本可能兼容 ASCII )。详见 stage 1 SHBuild 中关于 NPL 支持的说明

外部环境

  • 除非另行指定,脚本不假定自身的存储位置。
    • 一般地,这允许脚本的内容不总是可通过文件系统访问。这包括执行时脚本的来源被移除和不公开以文件的形式部署等情形。
  • 对文件系统中的脚本:
    • 脚本文件总是普通文件或可解析到普通文件的有效的符号链接。
    • 除非另行指定,不假定脚本文件所在的位置或其父路径可写。

  项目中提供的脚本在版本库中具有固定的相对路径。除解释环境适用的公共的约定(如提供一般类 UNIX 系统使用的文件系统布局的 FHS(文件系统层次结构标准)),脚本不预设绝对路径的假定。

警告 小心处理路径。当前脚本直接或间接使用的所有涉及文件系统递归操作均不假设检查遍历的目标之间是否重复,若使用不恰当的目录链接,可能造成未预期的行为(如复制指向父目录的目录链接时可引起无限递归)。部署时应提前确保不存在这样的链接。

  脚本实现假定没有可能冲突的并发文件访问。

接口约定

  脚本变量可能被读取和加载。除非另行指定,非导出的变量和名称以 _ 结尾的变量,都不是公开接口。

路径

  路径(path) 是由有限的路径组件构成的序列。在不引起歧义时,路径即指文件系统路径。文件系统的路径组件能以字符串形式表示。

  在支持相对路径的环境中,是否支持相对路径取决于具体脚本。

  内部的路径的分隔符使用 / 。通过脚本提供的 SHBuild_2w 等函数(见以下有关章节),可转换为带有不同路径分隔符的路径字符串。这种转换通常仅在必要时(如明确作为外部工具的输入)使用。

  字符串形式的路径(即路径字符串)可能是保证不以分隔符结尾的文件名和确保以分隔符结尾的目录路径字符串。目录路径指目录路径字符串或其对应的非字符串形式的路径。

  两个路径字符串的拼接可构成新的路径字符串。这两个路径字符串分别是路径前缀和路径后缀。除非另行指定,作为路径前缀使用的路径字符串是文件名。这要求通过串接路径后缀构成访问前缀指定的目录的新的路径时,路径后缀需要以分隔符起始。

注意 YBase 的 ystdex::path 和 YFramework 的 YSLib::IO::Path 等数据结构表示根路径外无视结尾分隔符的非字符串形式的路径,因为有效的分隔符仅在根路径中出现。这些实现一般不检查分隔符的合法性,如其中具有包含分隔符的路径组件,也可能正常转换为字符串形式的合法路径。当前脚本只使用字符串形式的路径。

Shell 脚本

  扩展名 .sh 的脚本文件是 shell 脚本文件。大多数脚本需要使用 GNU bash 运行,如:

#!/usr/bin/bash

  需要考虑兼容性时,一般使用以下替代:

#!/usr/bin/env bash

  其它可以直接兼容 POSIX shell 的 .sh 脚本使用 Shebang 如:

#!/usr/bin/sh

  需要考虑兼容性时,一般使用以下替代:

#!/usr/bin/env sh

  为简化脚本代码,用户需要保证调用 shell 脚本时,环境应满足以下条件,否则行为未指定:

  • 使用满足要求的 Shell 语言实现:
    • 对 bash 脚本:
      • 满足版本要求:当前 Bash 最低版本为 4.0 。
      • 不使用 POSIX 兼容模式。
      • 保证能使用 mapfilebash 内建命令。
    • 对其它 POSIX shell 脚本:
      • 使用符合 POSIX 的 shell ,或使用以上要求相同的 bash 运行 shell 脚本。
  • 变量 IFS 未设置或设置为默认值 :
  • bash-p 选项启用时效果相同。
    • 用户应保证不设置 CDPATH-p 忽略的环境变量及 $BASH_ENV 等启动文件以避免未预期的不同行为。
  • 脚本文件不是目标在不同目录中的符号链接。
    • 对 bash 脚本,允许使用变量 BASH_SOURCE 的值(如 ${BASH_SOURCE[0]}${BASH_SOURCE%/*} 等形式) 较可靠地判断脚本文件的路径。此时,隐含需要附加假定通过脚本文件路径确定其它资源的位置。
    • 部分脚本可能有更进一步的使用限制或不依赖 . 命令及命令解释器调用的差异。此时,可直接使用 "$0" 判断路径。
  • 不使用和脚本中函数名冲突的别名。
    • 在 bash 中,这默认不需要关注,需使用 shopt -s expand_aliases 显式启用引起冲突的功能。

  脚本实现中的调用不受以上限制。

  若脚本可以确保兼容 POSIX shell ,使用后者而不是前者。

  如果对应解释器位于其它目录,可以符号链接到上面指定的路径。

  除非另行指定,本文档约定使用的路径字符串的分隔符为 / ,不连续出现在路径中,且不在结尾出现。例外:

  • 平台相关的绝对路径转义可出现 //
  • 构成路径的路径前缀可能以分隔符结尾,直接表示上层目录。

注意 当前版本库中的文件不保证跟踪权限。在一些环境中可能因为可执行权限问题导致无法立即执行脚本,参见这里的说明

  正式支持的发布版本中的公开 Shell 脚本应保证用 ShellCheck 0.7 或以上版本(任选)检查没有诊断消息。检查的命令行为 shellcheck -x -P SCRIPTDIR 跟随文件名。除非另行指定,使用明确的方式避免引起检查的问题而不是使用指令消除检查的结果,如使用 ${BASH_SOURCE[0]} 代替 $BASH_SOURCE 以避免 ShellCheck 警告 SC2128 。

Shell 语言使用规约

  除非另行指定,已定义的 shell 函数假定不被其它变量覆盖。这允许实现省略 readonly -fdeclare -g -r -f 声明,且允许使用相同的定义覆盖以简化调试。

  除非另行指定,脚本不区分未设置的环境变量和已设置但具有空值的环境变量。这两种情形脚本都可能指定一个非空的初始值,称为变量的默认值(default value)

  除非另行指定,返回非数值的 shell 函数使用 echo 输出返回的值。

  非生成的代码中不使用包含 __ 的名称。

  公开函数的函数名及公开的变量名不以 _ 结尾,否则以一个 _ 结尾。

  对 SHBuild 相关工具使用的函数,使用前缀 SHBuild

  函数出错且无法恢复时退出脚本。

  版本库中的提供的脚本一般应能通过 ShellCheck 检查。对需要使用 ShellCheck 指令指定脚本起始构造的检查时,在之前添加一行空命令(对 bash 脚本使用 : ,非 bash 脚本命令使用 true )以避免非预期地使指令作用于整个脚本。

环境变量

  Shell 脚本可使用以下能通过外部环境指定值的环境变量:

  • 用于指定入口位置:
    • SHBuild :外部 SHBuild 可执行文件路径。
      • 具体默认值和特定脚本被设计适应的部署环境相关(例如,视不同情形,脚本可使用 BASH_SOURCE"$0" )。
    • SHBuild_ToolDir :工具目录中的脚本目录,由脚本根据版本库所在目录确定。
  • 用于指定版本库中的资源:
    • SHBuild_BaseDir : SHBuild 目录,是工具目录(参见以下有关章节)中提供 SHBuild 源代码的目录。
    • YSLib_BaseDir :YSLib 目录,即版本库的工作目录。
  • 用于指定输出目录:
    • SHBuild_BuildDir :构建使用的中间输出文件路径。
      • 对不依赖 Sysroot 或 YSLib/YSTest 目录下的项目构建脚本,默认值是在完整的版本库中和 "$YSLib_BaseDir/build/$SHBuild_Host_Platform" 相同的目录;否则,默认值是当前工作目录 .
    • SHBuild_SysRoot :输出的 Sysroot 根路径。
      • 默认值是 "$YSLib_BaseDir/sysroot"
  • 用于配置构建环境:
    • SHBuild_Env_Arch :构建系统架构。
      • 由脚本 Tools/Scripts/SHBuild-common.sh 的函数 SHBuild_CheckUName 指定默认值和初始化。
    • SHBuild_Env_OS :构建系统操作系统。
      • 初始化和确定值的方式同 SHBuild_Env_Arch
    • SHBuild_Host_Arch :宿主架构。
      • 由脚本 Tools/Scripts/SHBuild-common.sh 的函数 SHBuild_PrepareBuild 初始化。
      • 默认值同 SHBuild_Env_Arch 初始化后的值。
    • SHBuild_Host_OS :宿主操作系统。
      • 初始化的方式同 SHBuild_Host_Arch
      • 默认值同 SHBuild_Env_OS 初始化后的值。
    • SHBuild_Host_Platform :宿主平台前缀。
      • 由脚本 Tools/Scripts/SHBuild-common.sh 中的函数 SHBuild_Platform_Detect 指定默认值和初始化。
    • SHBuild_SystemPrefix :系统前缀,在 Sysroot 根路径下决定安装路径。
      • 值由脚本 Tools/Scripts/SHBuild-common.sh 中的函数 SHBuild_GetSystemPrefix 确定。
    • SHBuild 构建使用的变量:详见 SHBuild 的帮助信息。
    • 其它构建脚本使用的变量:详见以下具体脚本的说明。

  一般地,部署的 shell 脚本需引用其它脚本时,以如下方式使用指定入口的环境变量:

  • 若脚本只支持 Sysroot ,以 SHBuild 在 Sysroot 的安装位置推断其它脚本的路径。
  • 若脚本只支持工具目录中的脚本目录布局,以 SHBuild_ToolDir 指定。
    • 这隐含目录在版本库中的布局,可以此初始化 YSLib_BaseDir 等变量的默认值。
  • 若脚本同时支持 Sysroot 中部署的位置和工具目录中的脚本目录布局:则不使用以上的变量。
    • 引用其它脚本文件时可直接指定包含,如:. "$(dirname "${BASH_SOURCE[0]}")/SHBuild-common.sh"

  除指定入口的环境变量,是否支持外部可覆盖默认值的上述环境变量是可选的,取决于各个脚本的具体支持。

NPLA1 脚本

  NPLA1 脚本可被 SHBuild 调用。SHBuild 支持特定的选项作为 NPLA1 的脚本解释器。脚本解释器支持 NPLA1 脚本文件。此外,在 shell 脚本中,NPLA1 脚本代码可能以字符串的形式存储和被 SHBuild 调用。

环境变量

  NPLA1 脚本可使用和 shell 脚本通用的环境变量,如 SHBuild

  除 stage 1 外,shell 脚本使用环境变量 NPLA1_ROOT 指定的根目录作为 SHBuild 加载 NPLA1 脚本使用的起始目录。

  脚本(包括直接或间接调用 NPLA1 脚本的其它脚本)除默认值外不需要依赖 Sysroot 的安装路径下的目录和文件布局,环境变量 SHBuildNPLA1_ROOT 可分别指定相互无依赖的路径。当仅指定 SHBuild 时,通过指定的 SHBuild 路径推断 NPLA1_ROOT 默认值,此时使用假定符合 Sysroot 约定的相对路径。

  NPLA1 脚本可使用以上约定含义和默认值的 shell 环境变量,但部分变量初始化方式可能不同:

  • 对 NPLA1 脚本,在 Tools/Scripts/SHBuild-YSLib-common.txt 中直接初始化变量 SHBuild_Env_ArchSHBuild_Env_OS

NPLA1 函数

  NPLA1 脚本可提供部分 shell 脚本中的同名函数。除非另行指定,这些函数的调用接口以及功能和 shell 脚本中的同名函数一致,但实现和以下行为不保证相同:

  • 出错时的诊断方式;
  • 缓存的变量及相关的输出提示信息;
  • 性能;
  • 影响的非公开环境变量等其它外部环境状态。

  作为公开接口的 NPLA1 函数另见 doc/NPL.txt 中的描述。

构建脚本

  一些开发脚本被用于构建。构建脚本的一般形式提供配置和生成阶段的自动化功能。

  配置阶段设置交互环境(典型地,通过执行命令前设置的环境变量)。

  生成阶段调用合适的工具完成构建。

  配置阶段的接口可能对外隐藏,此时使用默认配置进行构建。

  一些公用的构建脚本可适用于整个项目。其它的构建脚本可构建具体子项目中的目标。

  构建脚本可以是 makefile 或其它可执行的脚本。其中,makefile 可能使用以上约定含义的 shell 环境变量,但不保证可被外部指定覆盖脚本中指定的默认值。

Tools

  未归类的工具目录。这个目录的脚本是可用于整个项目或非特定子项目的工具脚本,如公用的构建脚本。

  工具脚本位于版本库目录 Tools 及其子目录 Scripts 下。

  工具主要用于开发,包括构建和版本库维护。

  一部分工具脚本也可被部署到 Sysroot 。在 stage 2 SHBuild 安装后运行的脚本可依赖安装的 Sysroot 实例的文件系统布局。支持维护版本库的开发脚本应保证在此之前(不依赖 Sysroot 的实例或仅依赖构建 stage 1 后可用的有限环境)可用。

Tools/install-sysroot.sh

  Sysroot 安装脚本。用于直接构建和部署基础环境。

  构建时会调用 Tools/Scripts 目录下的脚本,按需构建 stage 1 SHBuild 后间接调用 SHBuild 构建 YBaseYFramework 的静态库和动态库,再构建依赖于动态库的 SHBuild

  当前所有部署都指定到 YSLib 版本库根目录下的 build/$SHBuild_Host_Platform 目录,其中 $SHBuild_Host_Platform 是宿主平台目录名,调用 SHBuild-common.sh 中的函数 SHBuild_CheckHostPlatform 后确保非空。

  构建脚本同时可安装文件,完成 Sysroot 所需文件的部署。安装的起始目标位置由称为安装路径的目录路径指定,其字符串形式去除结尾分隔符的目录文件名为安装路径前缀。安装过程在必要时可创建 Sysroot 根目录、安装路径指定的目录及其子目录。安装路径的确定方式详见以下的使用方式。

  部署时使用 stage 1 SHBuild 更新文件和目录,在必要时创建符号链接或硬链接,若失败则改为普通复制。仅当被部署的文件为中间目标启用硬链接,以免后续操作意外覆盖源文件。注意在 Windows 上创建符号链接可能因为权限不足失败,取决于用户和组策略。建议使用系统管理权限运行以避免可能的权限问题。

基本使用

  脚本中使用以下配置传递至 SHBuild

: ${SHBuild_BuildOpt:="-xj,6"}
: ${SHBuild_LogOpt:="-xlogfl,128"}
: ${SHBuild_Opt:="${SHBuild_LogOpt} ${SHBuild_BuildOpt}"}

  因此可以直接用 export 或直接在命令行指定变量覆盖默认行为,如

SHBuild_BuildOpt=-xj,2 Tools/install-sysroot.sh

  使用 2 个并行线程构建。

  脚本也支持变量配置构建使用的路径:

: ${SHBuild_SysRoot="$YSLib_BaseDir/sysroot"}
: ${SHBuild_BuildDir:="$YSLib_BaseDir/build/$SHBuild_Host_Platform"}

  其中,各个变量的作用参见以上 shell 环境变量的说明。

  在 stage 1 SHBuild 构建调用 NPLA1 脚本 Tools/Scripts/SHBuild-YSLib*.txt ,调用方式和接受的配置(构建目标等)、具体默认设置和注意事项见对应 shell 脚本的文档相关章节。

Tools/Scripts

  这个目录的脚本可用于整个项目或项目核心部分的构建工具使用。

  当前有以下脚本忽略重复的 .source 命令:

  • SHBuild-common.sh

  以前缀 SHBuild_ 起始的名称保留使用。

  其中,前缀 SHBuild_Env_ 总是表示环境配置的只读变量名。这些变量若未被指定,可在第一次访问时(具体时机未指定)初始化为:

  • SHBuild_Env_Arch :参见函数 SHBuild_CheckUName
  • SHBuild_Env_OS :参见函数 SHBuild_CheckUName
  • SHBuild_Env_TempDir :缓存函数 SHBuild_GetTempDir 的输出。
  • SHBuild_Env_uname :缓存命令 uname 的输出。
  • SHBuild_Env_uname_m :缓存命令 uname -m 的输出。

Tools/Scripts/GenerateProjects.sh

  调用 ProjectGenerator 生成项目文件。

  当前支持生成所有 .cbp 文件。

  要求可使用 hggit 命令取版本库根目录,否则不保证输出到正确的路径。

变量 ProjectGenerator

  调用 RevisionPatcher 的命令。默认直接使用 which ProjectGenerator 的结果,一般要求可执行文件在环境变量 PATH 中。

Tools/Scripts/PatchRevision.sh

  开发过程中使用 RevisionPatcher 维护源文件中版本号的脚本。

  当前只支持 Mercurial 版本库的已添加或修改的未提交文件。

  脚本首先把未提交的这些修改导出为补丁备份到版本库根目录的 bak.patch ,然后使用这些内容调用 RevisionPatcher 取得文件和对应的新的版本号列表,最后使用 sed 查找对应文件并更新版本号。

  若没有找到 \version r 模式的版本号前缀则忽略写入版本号。写入的版本号不影响换行符。

变量 PatchBegin

  匹配版本号的起始行,应为一个表示行数的正整数。默认值为 "1"

变量 PatchBegin

  匹配版本号的结束行,应为一个表示行数的正整数。默认值为 "20"

变量 RevisionPatcher

  调用 RevisionPatcher 的命令。默认直接使用 which RevisionPatcher 的结果,一般要求可执行文件在环境变量 PATH 中。

Tools/Scripts/SHBuild-bootstrap.sh

  编译 stage 1 SHBuild 时被包含的脚本。

  其中指定了静态链接需要依赖的 YSLib 源文件以及头文件路径等。

Tools/Scripts/SHBuild-build.sh

  编译 stage 1 SHBuild 的脚本。

  使用变量 SHBuild_Output 指定输出路径。默认值为 SHBuild ,即在当前工作目录下生成名为 SHBuild 的可执行文件(视宿主平台不同可能带后缀如 Win32 带 .exe )。

  调用函数 SHBuild_CheckPCH 检查预编译头:若变量 SHBuild_NoPCH 非空则跳过预编译头,否则使用预编译头包含标准库头。预编译的头文件目标由 YBase 下的 stdinc.h ,之后构建时包含预编译头路径为 $SHBuild_PCH_stdinc_h 。后者的默认路径为当前工作目录下的 stdinc.h

已知缺陷 不自动更新预编译头。

Tools/Scripts/SHBuild-BuildApp.sh

  应用程序构建脚本。这个脚本被保留,不再具有实际功能。

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 bin 目录下。

Tools/Scripts/SHBuild-BuildPkg.sh

  包构建脚本。当前只支持构建应用程序,具体步骤和使用的参数参见 Tools/Script/SHBuild-BuildApp.txt

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 bin 目录下。

Tools/Scripts/SHBuild-common.sh

  被应用程序构建脚本包含的脚本,提供公共基础功能。

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 bin 目录下。

函数 SHBuild_Put

  使用 printf 输出非格式字符串。

函数 SHBuild_Puts

  使用 printf 输出非格式的换行的字符串。

  换行符由变量 SHBuild_EOL 指定。当前默认值通过检查 $COMSPEC 是否定义,以确保 Windows 环境(包括 MSYS )使用 CR+LF ,其它情况使用 LF 。

注意 具体的检查逻辑实现可能在以后改变。

函数 SHBuild_AssertNonempty

  断言第一参数为名称的变量非空,否则显示出错并退出。

  使用 eval 实现。

函数 SHBuild_CheckedCall

  断言第一参数为名称的变量非空,若空则使用 eval 对后续求值并初始化第一参数指定的只读变量。若发生初始化则在标准输出中显示。

函数 SHBuild_InitReadonly

  检查第一参数为名称的命令存在,否则显示出错并退出。

  使用 hash 实现以优化性能。

函数 SHBuild_CheckUName

  调用 SHBuild_CheckedCall 初始化只读变量 SHBuild_Env_OSSHBuild_Env_Arch 的值。

  变量 SHBuild_Env_OS 的值通过分类系统的值(一般即 SHBuild_Env_uname 的值)标识操作系统:

  • OS_X :输入匹配 *Darwin* ,用于标识 OS X 系统
  • Win32 :输入匹配 *MIGW* 或 *MSYS* ,用于标识 Windows (桌面)系统
  • Linux :输入匹配 *Linux* ,用于标识 Linux 系统。
  • unknown : 不支持的系统。

  变量 SHBuild_Env_Arch 的值通过分类输入的处理器体系结构的值(一般即 SHBuild_Env_uname_m 的值)标识体系结构:

  • x86_64 :输入匹配 x86_64 或 i*86-64 。
  • i*86 :输入匹配 i*86 ,使用原值。
  • aarch64 :输入是 aarch64 。
  • unknown :不支持的体系结构。

  若同时指定环境变量 SHBuild_Env_ArchSHBuild_Env_OS ,不进行自动环境检测,不依赖 uname

函数 SHBuild_PrepareBuild

  初始化环境,并描述宿主平台的变量 SHBuild_Host_ArchSHBuild_Host_OS 具有非空的初始值。

函数 SHBuild_2m

  接受 1 个表示路径的参数,调用 cygpath 转换路径到 Windows 混合风格路径。

  当 cygpath 不存在时返回原路径。

函数 SHBuild_2u

  接受 1 个表示路径的参数。

  调用 cygpath 转换 Windows 路径到 UNIX 路径。

  当 cygpath 不存在时返回原路径。

函数 SHBuild_2w

  接受 1 个表示路径的参数,调用 cygpath 转换 UNIX 路径到 Windows 路径。

  当 cygpath 不存在时返回原路径。

函数 SHBuild_Install

  接受 2 个表示路径的参数,安装前者指定的文件到后者。

  首先调用 rsync ,若失败调用 cp

注意 防火墙可能导致 rsync 超时失败。

函数 SHBuild_InstallDir

  接受 2 个表示路径的参数,安装前者指定的目录到后者。

  首先调用 rsync ,若失败调用 cp

注意 防火墙可能导致 rsync 超时失败。

函数 SHBuild_Install_Exe

  接受 2 个表示路径的参数,安装前者指定的可执行文件到后者。

  首先调用 SHBuild_Install ,然后在目标上设置可执行权限。

函数 SHBuild_Install_HardLink

  接受 2 个表示路径的参数,安装前者指定的文件到后者为硬链接。

  首先删除目标,其次调用 Windows 命令解释器的 mklink ,若失败调用 ln

函数 SHBuild_Install_HardLink_Exe

  接受 2 个表示路径的参数,安装前者指定的可执行文件到后者为硬链接。

  首先调用 SHBuild_Install_HardLink ,然后在目标上设置可执行权限。

注意 mklink 需要 Windows Vista 后的命令解释器(cmd) 的支持。硬链接需要文件系统(如 NTFS )支持。

函数 SHBuild_Install_Link

  接受 2 个表示路径的参数,安装前者指定的可执行文件到后者为符号链接。

  首先删除目标,其次调用 Windows 命令解释器的 mklink ,若失败调用 ln

注意 mklink 需要 Windows Vista 后的命令解释器(cmd) 的支持。符号链接需要文件系统(如 NTFS )支持。权限不足可能导致 mklink 创建符号链接失败,可在组策略改变相关默认行为。在一些版本的系统上,可能需要进一步的配置以通过链接执行文件。

函数 SHBuild_Pushd

  同 bash 内建 pushd 但不回显标准输出。

函数 SHBuild_Popd

  同 bash 内建 popd 但不回显标准输出。

函数 SHBuild_EchoEscape

  当标准输出使用终端时调用 echo -ne 输出参数指定的 ANSI 转义序列。

已知缺陷 不检查 $TERM 支持。

函数 SHBuild_EchoVar

  接受 2 个参数 x 和 y ,以特定颜色显示为 x = y 的形式。

函数 SHBuild_EchoVar_N

  接受 1 个参数 x ,调用 SHBuild_EchoVar 显示为 x = $x 的形式。

  右侧求值时会替换参数中的 ._

函数 SHBuild_GetTempDir

  取临时目录的路径。

  依次检查以下环境变量的值,若非空则作为结果:

  • TMPDIR
  • TEMP
  • TMP

  若这些环境变量都没有非空值,则使用经过 SHBuild_2m 转换的 /tmp(被 POSIX.1 要求支持)作为结果。

注意 以上过程在所有平台上都一致。这是自适应环境的基本接口,因此不对环境变量的值的合法性进行判断。若结果不表示一个可访问的目录,在访问以此构造的文件路径时可能引发错误。应用程序一般需自行检查或保证使用的环境中这些路径可访问。

说明 以上检查中,支持的环境变量符合惯例(en-US) 。检查环境变量的顺序(偶然地)和一些类似功能的实现(如 MySQL 在 Windows 上)一致,和其它一些特定平台的 API(如 Win32 API )及另一些不作为公开行为的实现(如 libiberty 的 choose_tmpdir )可能不一致。被支持的环境变量可用性举例:

已知限制 不检查路径是否表示实际可写的目录。另见文件访问约定。

  当前脚本实现假定临时目录可写,不满足条件时,文件操作可能失败。脚本使用的临时文件前也不保证检查文件可写。若此文件不可写(例如,在之前被 root 等高权限用户创建),则依赖文件可写的操作可能失败。对构建脚本,这可能导致依赖临时文件进行检查判断失效,而使错误的选项被使用。

  一般地,脚本可使用特定的例程(如 Shell 脚本可选地使用在许多环境中可用的 mktemp 命令)随机化文件名减少冲突。若需要更可靠地避免上述问题,可在运行脚本前清理临时目录,或预先设置 SHBuild_GetTempDir 访问的环境变量指定确保可写的空目录,同时避免并发调用脚本导致不安全并发访问此目录中的临时文件。脚本不使用其它方法确定直接使用的临时目录,但脚本间接调用的外部工具仍可能导致不安全的访问,而无法保证可靠。

函数 SHBuild_GetSystemPrefix

  按参数指定的平台名称字符串返回系统前缀字符串。

  系统前缀用于在文件系统中安装部署。

  通常系统前缀因为之前仍有非空的其它前缀(如 SHBuild_SysRoot 指定的值)而不是绝对路径的前缀。因此,系统前缀以 / 起始而不需要考虑所在的环境是否符合 FHS 的问题。

  当前支持的结果包括:

  • 参数为 MinGW64 时,结果为 /mingw64
  • 参数为 MinGW32 时,结果为 /mingw32
  • 否则,结果为 /usr

  本函数的结果符合 Sysroot 中关于 Sysroot 的目录布局的约定。

函数 SHBuild_Platform_Detect

  通过参数指定的操作系统和体系结构名,并结合环境变量,确定平台名称,检查非空并返回。

  当前支持的结果包括:

  • MinGW64
  • MinGW32
  • 第一个参数指定的操作系统名

  当前 Win32 系统外的结果和 SHBuild_CheckUName 初始化 SHBuild_Env_OS 的结果一致。否则,处理如下:

  • 若环境变量 MSYSTEM 设置为 MINGW64MINGW32 ,结果对应为 MinGW64MinGW32
  • 否则,若操作系统名为 Win32
    • 若体系结构为 x86_64 ,则结果为 MinGW64
    • 否则,结果为 MinGW32
  • 否则,结果为操作系统名。

函数 SHBuild_CheckHostPlatform

  调用 SHBuild_CheckUName ,且当变量 SHBuild_Host_Platform 非空时初始化它的值。

  变量 SHBuild_Host_Platform 的值表示宿主平台目录名,用于初始化路径等。初始化的值为以变量 SHBuild_Env_OSSHBuild_Env_Arch 的值作为参数调用函数 SHBuild_Platform_Detect 的结果。

函数 SHBuild_BuildGCH

  接受第一个参数指定的路径的头文件安装到第二个参数指定的路径下并使用第三个参数指定的命令行构建 GNU 预编译头。

函数 SHBuild_CheckPCH

  检查是否设置了非空的 SHBuild_NoPCH ,否则调用 SHBuild_BuildGCH 并生成 GNU 风格预编译头文件并设置内部变量 SHBuild_IncPCH 为合适的命令行选项用于包含生成的预编译头文件。

  支持两个参数,同 SHBuild_BuildGCH 的前两个参数。

Tools/Scripts/SHBuild-common-options.sh

  被应用程序构建脚本包含的基础功能,提供默认的编译器和链接器命令行选项。

  若某个变量提供默认值且执行脚本时没有非空值,则设置为脚本提供的默认值。

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 bin 目录下。

  包含 Tools/Scripts/SHBuild-common-toolchain.sh 确定工具链。

注意 G++ 和 Clang++ 不完全兼容。以下部分变量通过 Tools/Scripts/SHBuild-common-toolchain.sh 中的例程判断 G++ 和 Clang ,并自动使用不同的选项默认值。因此直接通过名称和符号链接等方式伪装会失效而可能导致错误。

  以下所有变量仅在空(包括未设置)时提供默认值,按顺序被指定。可在外部设置为非空值以避免被本脚本中的值覆盖。以下仅列出部分相对不容易变动的默认值,其它默认值参见脚本源代码。若不需要默认值,可以提前设置非空值或在 . 指令后直接设置其它(可能为空的)值。

变量 SHBuild_Debug

  默认为空。

  非空时,指定变量的值:

CXXFLAGS_OPT_DBG='-O0 -g -D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC'
LDFLAGS_OPT_DBG=' '

变量 C_CXXFLAGS_GC

  C/C++ 编译器生成二进制节 GC 选项,默认值为 -fdata-sections -ffunction-sections

  设置后会被检查是否支持,参见下文。

变量 LDFLAGS_GC

  链接器生成二进制节 GC 选项,默认值为 -Wl,--gc-sections

  设置后会和 C_CXXFLAGS_GC 通过 $CXX 作为编译器编译链接简单程序测试是否支持。若不支持,此变量和 C_CXXFLAGS_GC 都会被置空。

已知限制 Windows 上的工具链可能缺乏 /dev/null 的必要支持,因此此项检查使用的输出路径指定为 /tmp/null

变量 LDFLAGS_STRIP

  链接器剥离符号选项,默认值为 -s

变量 C_CXXFLAGS_ARCH

  C 和 C++ 编译器共用的体系结构相关选项,默认值为空。

  不限制具体形式,使用 G++ 时可以是 -march=native

变量 C_CXXFLAGS_PIC

  C 和 C++ 编译器共用的 PIC ( Position Independent Code ,位置无关代码)生成选项,默认值在 Win32 上为空,其它平台上为 -fPIC

  用于保证生成的对象文件可被用于生成动态库。

变量 C_CXXFLAGS_COMMON

  C 和 C++ 编译器共用的公共选项,默认值为 -pipe $C_CXXFLAGS_GC $C_CXXFLAGS_ARCH -pedantic-errors

变量 C_CXXFLAGS_OPT_LV

  C 和 C++ 编译器优化等级选项,默认值为 -O3

变量 C_CXXFLAGS_WARNING

  C 和 C++ 编译器共用的警告命令行选项,默认值包括以下列表中的内容:

  • -Wall
  • -Wcast-align
  • -Wdeprecated
  • -Wdeprecated-declarations
  • -Wextra
  • -Wfloat-equal
  • -Wformat=2
  • -Winvalid-pch
  • -Wmissing-declarations
  • -Wmissing-include-dirs
  • -Wmultichar
  • -Wno-format-nonliteral
  • -Wredundant-decls
  • -Wshadow
  • -Wsign-conversion

  使用符合项目要求支持的 Clang++ 和 G++ 应支持这些选项。

变量 C_CXXFLAGS_IMPL_WARNING

  和特定实现相关的 C 和 C++ 编译器共用的警告命令行选项,默认值包括若干特定实现的选项。

变量 CXXFLAGS_IMPL_WARNING

  和特定实现相关的 C++ 编译器警告命令行选项,默认值包括若干特定实现的选项。

变量 CXXFLAGS_IMPL_COMMON

  和特定实现相关的 C++ 编译器一般命令行选项,默认值包括若干特定实现的选项。

  默认值按以下方式检查和指定线程参数:

  • 通过 -dumpspecs 的内容检查是否匹配 mthreads: 。若成功,编译器和链接器选项添加 -mthreads
  • 否则,检查带有 -mthread 选项的构建。若(直接调用编译器驱动)构建通过,则链接器选项添加 -mthreads ,并检查编译。
    • 若编译不通过,则编译器选项添加 -D_MT ,否则添加 -mthreads
  • 否则,若通过 -dumpspecs 的内容检查匹配 no-pthread: 且带有 -pthread 时无法构建,则保持编译器和链接器选项不变。
  • 否则,编译器和链接器选项添加 -pthread

注意 当前不检查失败原因。参见函数 SHBuild_GetTempDir 的已知限制。

  当前暂不支持判断其它环境。

变量 CXXFLAGS_IMPL_OPT

  和特定工具相关的 C++ 编译器优化命令行选项,默认值包括若干特定实现的选项。

变量 CFLAGS_STD

  指定 C 标准的编译器命令行选项,默认值为 -std=c11

变量 CFLAGS_WARNING

  C 编译器警告命令行选项,默认值为 $C_CXXFLAGS_WARNING $C_CXXFLAGS_IMPL_WARNING

变量 CFLAGS_COMMON

  C 编译器一般命令行选项,默认值为 $C_CXXFLAGS_COMMON $CFLAGS_STD $CFLAGS_WARNING

变量 CXXFLAGS_STD

  指定 C++ 标准的编译器命令行选项,默认值为 -std=c++11

变量 CFLAGS_WARNING

  C 编译器警告命令行选项,默认值包含以下列表中的内容:

  • 变量 CFLAGS_WARNING 的内容
  • -Wctor-dtor-privacy
  • -Wnon-virtual-dtor
  • -Woverloaded-virtual
  • -Wsign-promo
  • 变量 CXXFLAGS_IMPL_WARNING 的内容

变量 CXXFLAGS_COMMON

  C++ 编译器一般命令行选项,默认值为 $CXXFLAGS_STD $C_CXXFLAGS_COMMON $CXXFLAGS_WARNING $CXXFLAGS_IMPL_COMMON

变量 CXXFLAGS_OPT_DBG

  C++ 编译器优化和调试相关的命令行选项。在未设置非空的 SHbuild_Debug 时,默认值包含以下列表中的内容:

  • 变量 C_CXXFLAGS_OPT_LV 的内容
  • 变量 CXXFLAGS_OPT_UseAssert 没有被设置非空值时包含 -NDEBUG
  • 变量 CXXFLAGS_IMPL_OPT 的内容
  • -fomit-frame-pointer

变量 CFLAGS

  C 编译器使用的命令行选项,默认值为 $C_CXXFLAGS_PIC $CFLAGS_COMMON $C_CXXFLAGS_COMMON_IMPL_ $CXXFLAGS_OPT_DBG 。其中,C_CXXFLAGS_COMMON_IMPL_ 是根据支持的编译器在内部定义的非公开变量。

注意 当前和 C++ 编译器选项共用 CXXFLAGS_OPT_DBG

变量 CXXFLAGS

  C++ 编译器使用的命令行选项,默认值为 $C_CXXFLAGS_PIC $CXXFLAGS_COMMON $C_CXXFLAGS_COMMON_IMPL_ $CXXFLAGS_OPT_DBG 。其中,C_CXXFLAGS_COMMON_IMPL_ 是根据支持的编译器在内部定义的非公开变量。

变量 LDFLAGS_OPT_DBG

  链接器优化和调试相关的命令行选项。在未设置非空的 SHbuild_Debug 时,默认值为 $LDFLAGS_STRIP $LDFLAGS_IMPL_OPT $LDFLAGS_GC

变量 LDFLAGS_DYN_BASE

  指定动态库基础链接选项,默认值和平台相关:若为 Win32 环境则使用 -shared -Wl,--dll 否则为 -shared

变量 LDFLAGS_DYN_EXTRA

  指定动态库附加链接选项,默认值等价于 -Wl,--no-undefined,--dynamic-list-data,--dynamic-list-cpp-new,--dynamic-list-cpp-typeinfo

变量 LDFLAGS_DYN

  指定动态库链接选项,默认值为 $LDFLAGS_DYN_EXTRA $LDFLAGS_DYN

变量 LIBS_RPATH

  用于指定在运行时 ELF 映像需要的动态库的路径的链接器选项。在 Win32 默认不设置,其它平台默认值为 -Wl,-rpath,'\$ORIGIN:\$ORIGIN/../lib'

变量 LIBPFX

  库前缀。在 Win32 默认不设置,其它平台默认值为 lib

变量 DSOSFX

  动态库文件名后缀。在 Win32 默认为 .dll ,其它平台默认值为 .so

变量 EXESFX

  可执行文件名后缀。在 Win32 默认为 .exe ,其它平台默认不设置。

变量 LDFLAGS

  链接器使用的命令行选项,默认值依次包含以下内容:

  • 变量 C_CXXFLAGS_PIC 的内容。
  • 和变量 CXXFLAGS_IMPL_COMMON 中等价的线程命令行选项。
  • 变量 LDFLAGS_OPT_DBG 的内容。
  • 生成可执行程序时且要求按需调整链接器参数时,附加的值:
    • 当需要生成 Win32 子系统程序时,附加 -mwindows
  • 动态可执行程序时,变量 LIBS_RPATH 的内容。
  • 动态链接库时,变量 LDFLAGS_DYN 的内容。

  默认使用 -Wl, 传递链接器特定的命令行。

Tools/Scripts/SHBuild-common-toolchain.sh

  被应用程序构建脚本包含的基础功能,提供默认的编译器和链接器等工具的名称。

  支持 GCC/G++ 和 Clang/Clang++ 。

  支持 ar 及与其兼容的工具 gcc-ar/llvm-ar 的自动检测。对 Clang++ 和 G++ ,分别使用 llvm-argcc-ar

  以下可在环境外部配置,在值确定后被导出:

  • CC
    • 默认值为 gcc
  • CXX
    • 默认值为 g++
  • AR
    • 默认值为变量 CXX 指定的 C++ 编译器确定的自动检测结果;若非 Clang++ 和 G++ ,则使用 ar
  • ARFLAGS
    • 默认值为 rcs
  • LD
    • 默认值为变量 CXX 的值。

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 bin 目录下。

函数 SHBuild_CheckCC

  尝试调用参数指定的编译器以检查 C 编译器风格。结果是以下之一:

  • Clang
  • GCC
  • 空值(不支持的编译器)

函数 SHBuild_CheckCXX

  尝试调用参数指定的编译器以检查 C++ 编译器风格。结果是以下之一:

  • Clang++
  • G++
  • 空值(不支持的编译器)

Tools/Scripts/SHBuild-self-host.sh

  SHBuild 自举测试用脚本。

  使用 SHBuild 编译并静态链接构建 SHBuild 。和 stage 1 SHBuild 类似,直接使用 YSLib 源文件。

Tools/Scripts/SHBuild-self-host-DLL.sh

  SHBuild 自举测试用脚本。

  使用 SHBuild 编译并动态链接构建 SHBuild 。依赖 /usr/lib 中存在的 YFramework.dll 和 YBase.dll 。

Tools/Scripts/SHBuild-YSLib*.txt

  构建 YSLib 用的 NPLA1 脚本,包含以下文件:

  • Tools/Scripts/SHBuild-YSLib-common.txt :被 Tools/Scripts/SHBuild-YSLib-build.txt 加载的 NPLA1 脚本。
  • Tools/Scripts/SHBuild-YSLib-build.txt :使用 SHBuild 构建 debug 或 release 配置的 YBase 和 YFramework 库的 NPLA1 脚本,被 Tools/install-sysroot.sh 调用,其中 SHBuild 默认为 stage 1 SHBuild 。
  • Tools/Scripts/SHBuild-YSLib.sh :当前被保留。

  调用方式详见 stage 1 SHBuild 中关于 NPL 支持的说明

  可通过外部环境变量配置脚本行为。

Tools/Scripts/SHBuild-YSLib-common.txt

  Tools/Scripts/SHBuild-YSLib-common.txt 包含一些公共的库,包括支持类似 Tools/Scripts/SHBuild-common-options.shTools/Scripts/SHBuild-common-toolchain.sh 的选项以环境变量的方式配置,但 C 编译器相关的选项除外(不使用而被忽略)。和 Tools/Scripts/SHBuild-common-options.shTools/Scripts/SHBuild-common-toolchain.sh 的不同为:

  • 生成变量默认值的选项之间的空白符可能不同(通常可确保为一个空格)。
  • 按需初始化变量。配置时为确定变量的默认值的检查的调用顺序可能不同。
  • 使用 debug 模式时,CXXFLAGS_OPT_DBG 设置为 -O0 -g -D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC ,不再被环境变量覆盖。
  • 附加支持构建应用的配置,在导出的 LDFLAGS 的值中添加 LIBS_RPATH 的值。

  这个脚本被 Tools/Scripts/SHBuild-YSLib-build.txt 加载,并被 Tools/install-sysroot.sh 间接调用。

  可以在外部调用这个脚本的命令行设置变量以覆盖直接指定需要的选项,如:

CXX=clang++ CXXFLAGS='-std=c++11 -O2' Tools/install-sysroot.sh

  使用预编译头选项和缺陷同 Tools/Scripts/SHBuild-build.sh 。其中的特性未指定使用 shell 实现,和后者可能存在 shell 环境中可见的差异。

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 var/NPLA1 目录下。

Tools/Scripts/SHBuild-YSLib-build.txt

  这个脚本当前包括和安装相关的流程,实现 Tools/install-sysroot.sh 在 stage 1 SHBuild 构建后的主要逻辑。

  脚本支持 SHBuild_ 为前缀的环境变量指定构建和部署目标:

  • SHBuild_UseDebug 非空时启用构建和安装 debug 配置的库。
  • SHBuild_UseRelease 非空时启用构建和安装 release 配置的库。
  • SHBuild_NoStatic 非空时跳过静态库构建。
  • SHBuild_NoDynamic 非空时跳过动态库构建。
  • SHBuild_No3rd 非空时跳过第三方库安装。
    • 外部依赖项中的库,只安装启用的配置决定的必要的外部依赖。启用的配置由 SHBuild_UseDebugSHBuild_UseRelease 指定。
  • SHBuild_NoDev 非空时跳过可选的开发工具构建和安装。
  • SHBuild_Rebuild_S1 非空时跳过文件存在性检查,总是重新构建 stage 1 SHBuild 。
  • SHBuild_NoDev 非空时跳过 stage 2 SHBuild 后的开发工具构建和安装。

  以下配置行为的环境变量(其中 SS 表示 SHBuild Settings )被支持:

  • SS_DebugEnv 值非空时启用脚本执行时系统环境相关的调试输出,当前包括:
    • 对环境变量修改时输出修改的变量名和对应的值。
  • SS_Verbose 值非空时启用详细消息输出,当前包括:
    • LDFLAGS 变量中附加 -mwindows 时提示。

  以下构建时的中间变量可被外部配置,当外部没有配置或为空值时使用默认值:

  • SHBuild_YF_Libs_freetype :freetype 库链接参数。
    • 默认值为 -lfreetypepkg-config --libs freetype2 的输出结果。
      • 其中存在 Sysroot libfreetype.a 时默认值为前者。
  • SHBuild_YF_Libs_FreeImage :FreeImage 库链接参数。
    • 默认值为 -lFreeImaged-lFreeImage ,对应 debug 和非 debug 配置。

  Tools/Scripts/SHBuild-YSLib-build.txt 也可能使用其它变量用于传递参数给被调用的命令,包括一些 SHBuild 预期的变量;后者作为公开接口,但其具体含义和使用不保证在不同版本间稳定

  在 stage 1 构建时,接受以下环境变量:

  • INCLUDES_freetype 指定覆盖包含路径的编译器命令行选项,默认值以 -I 起始,使用版本库目录下的 3rdparty/freetype/include 目录带有适当引号的完整路径。

  在 stage 2 构建时接受以下外部环境变量(部分被 SHBuild 直接以环境变量的方式接受):

  • INCLUDES 包含路径,和非 SHBuild 中的 Makefile 惯用法含义类似。
  • LDFLAGS 链接命令行选项。
  • LIBS 作为命令行选项的链接时使用的库路径。
  • LIBS_RPATH 非 Windows 平台使用的 rpath 路径。

Tools/Scripts/SHBuild-BuildApp.txt

  NPLA1 应用程序构建脚本。可利用此工具脚本调用 SHBuild 构建特定配置(configuration) 下使用 YSLib 库和基础环境开发的应用程序。

  这个脚本是公开的工具,被 Tools/install-sysroot.sh 部署到安装路径下的 var/NPLA1 目录下。

基本原理

  配置是特定用途的一组程序输出的集合。常见软件配置可以区分目标平台,是否为调试配置等。

  脚本通过设置特定的环境变量并调用 SHBuild 递归扫描指定目录完成构建。其中调用命令由环境变量 SHBuild 指定。若变量 SHBuild 为空,则假定使用脚本程序在 Sysroot 中,由 Sysroot 的布局确定的 SHBuild 的位置作为变量 SHBuild 的默认值。

  脚本支持区分 debug 和非 debug 配置以及静态和 DLL 配置。详见以下说明。

  debug 配置总称 debug 模式。非 debug 配置总称 release 模式。

调用方式

  无参数调用时,显示帮助文本。以第一参数指定配置名称,执行脚本直接一次性配置后构建。之后可选的其它参数被脚本传递给 SHBuild ,详见以下的操作说明。

使用须知

  脚本依赖 Sysroot 。

  这个脚本被 Tools/Scripts/SHBuild-BuildPkg.sh 调用。

  当前只支持构建,不支持部署。

  构建时调用的工具链命令行及配置详见 Tools/Scripts/SHBuild-YSLib-common.txt 的说明。

  需要先确保源代码可访问。注意源代码目录会被递归扫描,建议在目录中只包含所有需要构建的源文件或被包含的文件。

操作说明

  一般步骤:

  • 新建一个 GNU bash 脚本(以下称为用户构建脚本 ),调用此脚本(若无法在 PATH 找到,需要使用完整路径)。
  • 以源代码所在目录的路径作为参数,执行通过此脚本包含的 SHBuild_BuildApp 函数,等待构建完成。
  • 直接包含后的脚本仍可使用无参数调用用户构建脚本查看选项和说明。

  简化操作:也可以不创建用户构建脚本,直接在命令行中执行,例子见入门

  若有必要,在调用本脚本之前设置 SHBuild_BuildDir 变量为指定输出文件所在的目录的完整路径,如:

export SHBuild_BuildDir=$(dirname "$0"`/../build)

  上述命令行指定相对于用户构建脚本上一层目录的 build 子目录下作为基准输出路径。若不显式设置此变量,工具脚本会指定其默认值为用户构建脚本所在的目录。

  调用本脚本。脚本会自动加入必要的参数调用 SHBuild ,传递的参数依次具体如下:

  • 中间变量 SHBOPT 的值,包括根据配置决定的目录设置选项、 -xid,include -xmode,2 以及用户在脚本命令行指定的剩余选项 SHBOPT_BASE
  • 传递给本脚本的配置名称以外的可选参数。
  • SHBuild_BuildApp 的值,用于编译器的库配置(包含路径以及使用 DLL 需要的宏定义 -DYF_DLL -DYB_DLL ),由脚本根据静态或动态库配置自动确定,无需重复输入类似选项。

特别注意 脚本执行以输出基准路径作为当前工作目录,需要以此为基准指定源文件路径( SHBuild 使用的 SRCPATH 参数)。

  通过脚本命令行间接传递给 SHBuild 的参数 SHBOPT_BASE 以及函数 SHBuild_BuildApp 的参数都可以进一步对构建过程进行调整,如 -xj,2 指定 2 个并行线程构建。

注意 以 SHBuild 作为 NPLA1 脚本解释器时,传递的参数可能会被 SHBuild 截获,而不被继续传递给 脚本中调用的 SHBuild 。为避免这种情形,在 -xcmd,RunNPLFile 和本的脚本文件名选项后,可加上 -- 分隔其余命令行参数。

配置设置

  传递给 SHBuild 指定使用 .配置名称 相对路径(无需另外指定 -xd, 参数)。如 -cdebug 指定输出路径为 .debug 。省略此项默认配置名为 shbuild

  脚本根据以下规则自动检测配置:

  • 若配置名称以 debug 起始,或环境变量的 SHBuild_Debug 值非空,则视为使用 debug 配置。
  • 若配置名称以 static 结束,活环境变量 SHBuild_Static 的值非空,则视为使用 static 配置。

环境变量

  环境变量 SHBuild_DebugSHBuild_Static 可按上述自动检测配置过程指定配置类型。

  默认情况下, release 配置会在链接器命令行加入 -mwindows和 debug 配置编译的程序行为不保证相同。设置非空变量 SHBuild_NoAdjustSubsystem 禁用此行为。

  脚本使用包含 YSLib 库的编译器命令行。若有必要,可设置 SHBuild 使用的变量 SHBuild_CFLAGSSHBuild_CXXFLAGS 作为前缀。

  脚本已经导出了用于链接器的包含使用 YSLib 库命令行参数的变量 LDFLAGSLIBS 。若有必要,可设置变量 SHBuild_LDFLAGSSHBuild_LIBS 作为前缀。