准备

• 参见构建
• 参见开发说明
• 配置满足先决条件的对应平台运行环境

平台环境

　　以下适用包含 YSLib 程序和其它程序的构建和运行环境。并非每一个程序都需要区分特定平台，一些程序的行为是平台中立的。

YSLib 程序

注意 示例程序最大化地使用了 YSLib 的平台模拟特性，支持特定的目标平台在运行时作为宿主平台对另一平台的平台模拟，即运行的原生示例程序和被模拟平台的原生程序保持基本相同的功能效果；但并不保证所有其它 YSLib 程序同样支持。

　　被正式支持的平台模拟列表如下：

• PC 模拟 DS

　　被非正式支持的平台模拟列表如下：

• Android 模拟 DS

硬件资源要求

　　占用的硬件资源不确定，取决于平台配置以及具体应用程序。

注意 特定平台可能有额外限制，详见各个平台运行时环境的说明。

环境变量

　　环境变量是程序的实现环境（典型地，如操作系统）的运行环境提供的一种机制。程序在运行时可能访问这些环境变量，以提供不同的行为，或在程序之间、程序与外部环境之间传递信息。

注释 非宿主实现的平台可能不支持环境变量。本项目的程序在这些平台上不使用环境变量。

　　没有依赖这些具体应用或其提供的实现环境时，如有可能，应当避免使用依赖这些具体的使用方式。

　　一些情形程序通过判断特定的环境变量配置功能。特别地，设置特定的环境变量为非空值可能启用功能。

　　一般地，只要环境变量被支持，一个环境变量总是能被设置为非空的字符串（至少本项目支持的平台能假定如此）。但是，访问环境变量的行为仍可能依赖具体平台的不同细节，而影响可移植性：

• 环境变量的名称可能是大小写敏感或不敏感的：名称仅有大小写不同的环境变量可能被视为不同或同一个。
  • 例如，Windows（指 Win32 环境，下同）的环境变量名对大小写不敏感。其它大部分实现环境对环境变量的大小写敏感。
  • 因此，作为公开接口提供的环境变量应当总是具有固定的、大小写敏感的拼写，且避免出现仅有不同大小写的可能因同名冲突的不同环境变量名。
• 环境变量可被设置为空值。具有空值的环境变量可能会或不会被视为没有被设置（或被取消设置）的环境变量。
  • 例如，设置 Windows 的某个环境变量为空值，效果即删除环境变量。其它大部分实现环境中，设置环境变量为空值，环境变量不被删除。
  • 一些环境可能指定不同的行为，如较新版本的 MSYS2 支持配置 MSYS=noemptyenvvalues 。
  • 特定的实现被设置的环境变量具有空值，如 PowerShell 。
  • 为避免这些不同实现的复杂性，不直接判断环境变量被设置，而访问环境变量并检查是否为空值。未设置的环境变量被视为具有空值。
• 环境变量名可能具有不同的限制。
  • 仅假定 ISO C 基本字符集的标识符（大小写拉丁字母、数字和下划线 _ ）可被用于环境变量名。
• 具体环境变量的访问方式可能和具体宿主平台中访问环境变量的具体程序相关，如：
  • POSIX shell 变量引用 XBD 环境变量，可使用 $VAR 访问变量 VAR 的值。
  • Windows set 命令 显示或设置环境变量，可使用 %VAR% 访问变量 VAR 的值。
  • Powershell 支持环境变量，可通过 $Env:VAR 访问变量 VAR 的值。
• 以下周知的(well-known) 环境变量因在各个被本项目支持的宿主实现平台普遍可用，而可被直接使用，但使用方式并非完全相同：
  • 原理 以下约定简化可移植的使用。
  • PATH 表示程序中执行（外部程序提供的）命令使用的搜索路径。
    • 对 Windows ，另见 path 命令（其中使用 %PATH% 引用环境变量 PATH ）。
    • 另见 POSIX 的规定。
    • PATH 的值可支持多个路径名称，其中分隔符不一定相同，如 Windows 使用 ; ，而 POSIX 使用 : 。
    • Windows 可能直接提供 Path 环境变量，而在 cmd.exe 中仍然被识别为 PATH 。此时，使用 PATH 。
  • 环境变量 COMSPEC 或 ComSpec (en-US) 指定命令解释器。
    • Windows 可能直接提供 ComSpec 环境变量，而在 cmd.exe 中仍然被识别为 COMSPEC 。此时，使用 COMSPEC 。

　　除非需要依赖具体实现环境或另行指定，本项目中提供的环境变量应当避免上述依赖差异。

应用程序变量

　　应用程序继承环境，可能根据环境变量指定不同的行为。

　　除非另行指定，以下环境变量若被本项目提供的程序支持，则具有一致的含义：

• NO_COLOR ：若这个环境变量被设置为非空值，宿主实现环境忽略终端支持的彩色和其它视觉效果格式（如下划线）特性。
  • 注释 NO_COLOR 的检查符合 no-color.org 的约定。
  • 注释 一些命令解释环境的实现直接支持 NO_COLOR ，如 PowerShell。

　　除标准库和系统配置外，YFramework 可使用特定的环境变量改变运行时行为，参见 YSLib 项目文档 doc/YFramework.txt 。

　　除非另行指定，程序可假定以上环境变量不变，即仅在程序初始化时检查一次。

　　提供给程序的环境变量可能被命令行工具的选项覆盖，如 SHBuild 构建模式中指定变量定义的选项 。

多任务环境

　　以下执行其它程序的约定在以下情形适用：

• 通过用户界面运行 YSLib 程序。
• 以上方式间接运行的其它程序。
  • 注释 例如，在程序中调用脚本，或者程序使用基于 std::system 等本机 API 实现的互操作。YSLib 安装程序可能间接调用其它程序。

　　除非另行指定，通过 YSLib 安装程序调用的程序或者依赖 YSLib 的命令行程序假定以下的外部环境和交互方式：

• 非宿主环境：执行其它程序的宿主(host) 未指定。
  • 被视为默认不支持外部程序。
  • 注释 程序使用 std::system 等实现定义的行为可能导致非预期但可被定义的结果。
• 宿主环境：
  • 以被执行的当前程序或脚本解释器作为执行其它程序的宿主。
    • 注释 一般由操作系统在用户空间规范提供约定，且系统的安装提供完整的环境。例如，Windows 提供 cmd.exe 作为命令行解释器，而 UNIX 系统提供 shell 程序解释 shell 语言命令和脚本。
  • 以宿主定义的规则解析命令行参数。
    • Windows ：命令行由程序实现指定。对未指定宿主程序的情形，视为和 cmd.exe 一致。
      • 注释 Windows 可通过 shell 程序传递命令，这不是默认假定的环境。
      • Windows ：对引号的解析，兼容未被文档指定的新规则，即仅在引号有效地块中 "" 转义未 "。
  • 使用环境变量的约定。
  • 若环境变量 SHELL 被设置，则：
    • 假定被正确设置至支持的 shell 程序的路径。
    • 假定 POSIX.1-2004 环境的命令可用。
    • 注释 在 shell 环境内部通常不需要检查。可能使用其它 POSIX 兼容 shell 兼容 POSIX shell 或 GNU bash 的运行环境。
  • 非 Windows 宿主平台：使用 POSIX shell 或 GNU bash 作为执行环境的 shell 。
  • Windows ：使用随系统分发的 cmd.exe 作为命令行解释器。
    • 不显式依赖环境变量 COMSPEC 或 ComSpec。
    • 对使用 MSYS2 或与之兼容的环境，使用环境变量 MSYSTEM 指定活动的环境和子系统。
  • 不要求支持嵌套不同的命令行环境最终重入到非 POSIX 兼容 shell 的情形。
    • 注释 若 SHELL 被设置为非空值，即视当前 shell 是 POSIX 兼容 shell 。
    • 原理 被继承的环境变量检查可能嵌套的命令行环境不可靠。可靠检查通常依赖进程间通信确定当前的程序，为减少复杂性，不被要求。
  • 以上环境变量在相关规范定义明确允许的情形以外，可被程序假定不被修改。
  • 运行其它程序时，不检查或隔离外部环境。
    • 警告 尽管 YSLib 项目提供的程序的大部分实现会避免明显的安全性问题，任何可能执行第三方程序仍然可能有潜在的安全性风险。因此，在完全审计环境并确保外部环境可信之前，不建议使用特权运行包括 YSLib 安装脚本内的这些程序。
      • 注释 利用方式如拦截在程序中已知会调用的外部命令（包括命令解释器），以及使用环境变量 IFS 等特定外部命令的机制注入。
  • 使用包含带有 Windows 环境变量展开语法（以 % 起始和结尾）的参数未指定。
    • 原理 Windows 命令行解释器脚本可使用 %% 转义，但这对交互式命令行环境的调用不适用。因此，包含这种形式的参数可因是否使用 Windows 命令行解释器表现不同的行为。
    • 注释 NPLA1 脚本可调用依赖 Windows 命令行解释器执行的命令。
• 原理 POSIX shell 和 cmd.exe 是平台默认分发的应用，通过构建平台或宿主平台直接区分是可行的。
  • 同时，一些语法兼容，使有些命令不需要区分两者。即便在一些基本语法上（如重定向错误流）不完全兼容，默认仍然可以通过特定的环境区分两者。
  • 环境变量 SHELL 在不同实现的支持情形不同，不适合提供统一的假定：
    • 环境变量 SHELL 在 POSIX.1-2017 的 基本定义中出现，而其含义决定若这个环境变量被定义，其值非空。相关原理解释了 SHELL 具有可被系统配置为非 POSIX shell 的含义。
    • 环境变量 SHELL 不是被定义的 shell 执行环境的一部分，不被要求影响 shell 的执行，但仍能判断系统配置。
    • 环境变量 SHELL 的值通常被初始化环境的启动程序（如传统的 login，仍被 BSD 和 Linux 等使用）设置。
    • GNU bash 确保启动时 SHELL 的值被设置。
    • 其它兼容 POSIX shell 可使用环境变量 SHELL 执行命令，但通常不设置它的值（如 Korn shell）。
  • 环境变量 COMSPEC 和 ComSpec 缺乏标准化，且会被继承。
    • 这通常仅用于判断在 Windows 同时使用兼容 POSIX shell 环境。
    • Windows 可能使用嵌套的兼容 POSIX 的 shell 而同时继承 COMSPEC 且被设置 SHELL 的情形。
    • 为避免复杂性，一般避免单独检查这些环境变量。
    • C 运行时实现使用 std::system 和 ::_wsystem 实际可能总是依赖 COMSPEC 和 cmd.exe ，因此成功互操作时已经隐含依赖了这项运行时配置。
• 注释 PowerShell 、PowerShell Core 或 pwsh 默认不被支持。
  • 原理 PowerShell 和上述命令行解释器支持的语法都不兼容，且不直接提供简便可靠的可移植的方式检查差异。
  • 注释 可靠检查 PowerShell 通常依赖进程间通信。

　　关于 YSLib 版本库内的及安装 YSLib 部署的脚本的运行环境，另见脚本运行的相关说明。

文件系统

　　为最大化可移植性，原则上 YSLib 的程序逻辑不依赖自身组件具有显式编码的具体文件路径，因此默认不要求在具体系统约定的周知(well-known) 的文件系统位置（如 Windows DLL 搜索路径中的目录和 FHS 定义的目录）部署。但具体平台配置可以自行限定目录布局作为默认运行时环境，如 Sysroot 。其中外部文件可有默认路径，参见以下相关章节。

　　YSLib 中的库使用的文件系统路径具有以下约束：

• 不依赖兼容 POSIX 的文件系统和路径表示。
  • 特别地，不依赖文件系统是否具有文件名的大小写敏感性。
  • 推论 为保证可移植性，文件系统路径大小写敏感，需要显式区分而加以明确。
  • 这样仍可兼容 FAT 等大小写不敏感的文件系统。
• 要求支持符合 YSLib 项目规范的开发（参见项目的 doc/ProjectRules.txt ）。

　　一般地，YBase 不要求文件系统访问；使用 YFramework 框架的程序，由 YFramework 中的框架初始化等逻辑引入文件系统访问。

二进制依赖项

　　按以上文件路径约定，构建得到的目标程序没有预设特定的位置限制，可按需转移。

　　运行程序前，应确保程序能找到二进制依赖项：

• 确保先决条件中的依赖项可以在 PATH 环境变量的目录被找到，或者复制到程序所在的目录。
• 对于静态链接 YFramework 和 YBase 程序，不需要其它二进制程序文件的部署。
• 使用 DLL 的程序可能依赖 YFramework.dll 和 YBase.dll ，或者 debug 配置的 YFrameworkd.dll 和 YBased.dll 。这些库已经在 sysroot 的 bin 目录下安装，因此可以直接把 bin 目录加入 PATH 环境变量，而不必复制或移动库文件。

说明 在任意被支持的平台上，YSLib 避免使用导致在特定平台上被特殊处理且无法可靠避免这种行为而确保兼容性一致的外部依赖项名称（若因为外部环境更新导致此类问题，则需在 YSLib 的新版本适当修改后支持）。例如，支持 API Set Schema 的 Windows 版本加载 DLL 时，LdrLoadDll 解析以 api- 或 EXT- 起始的文件名进行重定位 ，因此设计时确保外部依赖项对应的文件名不以这些前缀起始。

外部文件

　　外部文件包括：

• 在文件系统中部署的外部二进制依赖项。
• 配置文件：可被修改以改变程序的运行时行为。
• 其它数据文件。

　　数据文件提供程序运行时所需的必要或可选的信息。配置文件可能作为数据文件使用。

　　外部文件的路径应符合前述关于文件路径的约定。

文件格式

　　除非另行指定，使用以下文件格式：

• 配置文件是内容为 NPL 配置的 UTF-8 文本文件，具有 UTF-8 BOM
• 其它数据文件为二进制文件

文件系统布局

　　除配置文件可能指定默认的具体位置（详见下文）外，YFramework 程序的不需依赖特别的文件系统布局。

　　除非另行指定（暂无），YFramework 不创建文件系统目录。

　　Sysroot 提供类 UNIX 系统使用的布局作为可选项。

文件访问约定

　　除非另行指定，YFramework 对外部文件的访问适用本节约定。

注意 除非另行指定，程序访问配置文件的时机是未指定的。

基本要求

　　应确保外部文件满足以下条件，否则运行时出错，或在另行指定（暂无）的特定情形下不保证行为符合预期：

• 具有适当的（可读和可写）权限以允许程序访问其内容及元数据，或在必要时进行创建。
• 需要写入的文件所在的位置应该具有足够的空间。

文件映射和内存映像

　　文件读写使用 YCLib::MemoryMapping ，优先使用内存文件映射。在文件无法访问时，部分文件可能使用内存映像代替。

注意 除非使用内存映像，应确保外部文件的内容可读；否则，可在之后引发无法恢复的错误；参见当前实现使用的 YCLib::MemoryMapping 的注意事项。

共享文件

　　宿主平台使用协同锁(advisory lock) 对并发文件内容访问提供有限的共享保护，避免基于 YFramework 程序并发访问外部文件时的竞争。不使用强制锁(mandatory lock) 以利于提升性能。

注意 除检查文件创建外，不提供相关文件系统元数据并发访问保护。

注意 因为锁定非强制，宿主不保证其它机制访问文件的程序（如非 YFramework 程序）在这里产生冲突，有可能破坏文件内容。用户应避免对相关文件造成此类访问的破坏性编辑。

注意 因为访问顺序未指定，不同 YFramework 实例可能修改相同的文件（如配置文件）而导致外部可见的影响。

　　未来可能添加完整的对共享文件内容修改的传递和检查的机制。

配置生成和输入输出

　　配置文件可能提供默认内容，在外部文件不存在或读取失败时尝试创建。默认内容一般由框架直接提供。

• 自动生成并保存外部文件时需确保程序可在指定目录下创建文件。
  • 具体目录视具体文件而定。
  • 可在运行前部署正确的配置文件以避免自动生成。
• 若无法满足，生成保存在内存中的临时配置映像之后的修改不会保存到外部文件。
  • 注意 某些版本的 Windows （如 Windows Vista 以后的版本）在特定的目录（如 %PROGRAMFILES% ）中创建文件默认需要管理员权限。

公共配置文件

　　文件 yconf.txt 为 YFramework 程序的公共配置文件，在框架初始化时，先于其它配置文件之前处理。若不存在，提供默认内容。其位置是预先指定的，和平台相关。详见下一章对框架初始化的说明。

　　为避免 YFramework 程序在运行时出错或行为不符合预期，注意确保满足前述访问约定的要求。若无法在程序映像文件所在目录（详见以下关于框架初始化的说明）创建文件，配置不能保存到外部文件。

　　在 Win32 上一个正确的公共配置文件的内容可能是这样的：

YFramework
(
	DataDirectory "C:\Data\\"
)
(
	FontDirectory "C:\Windows\Font\\"
)
(
	FontFile "C:\Windows\Font\FZYTK.TTF"
)

　　这里指定的路径分别为数据目录路径、字体文件目录路径和字体文件路径。

数据目录

　　用于存放 YFramework 程序必要的数据以及运行时的配置。

　　通过 yconf.txt 中项 DataDirectory 的值指定数据目录的路径。

　　自动生成的配置中数据目录的默认路径如下：

• DS ：/Data 目录
• Win32 ：同默认生成配置文件所在的目录
• Android ：SD 卡目录（自动检测同上）下的 Data 目录
• 其它平台：当前工作目录

　　当前可用数据文件位于 YSLib 存储库的 Data 目录下，可自行复制到数据目录。

CHRLib 的 GBK 转换例程初始化

　　对使用 CHRLib 提供的 GBK 编码转换的程序，需保证数据目录下存在数据文件 cp113.bin 。

　　对 Win32 平台，CHRLib 初始化 GBK 转换例程读取数据文件失败时，首先尝试使用 NLS 替代：

• 通过读取注册表取得 NLS 文件路径，默认为系统目录下的 C_936.NLS（文件名大小写可能不同，这不影响加载）。
• 注意 并非所有 Windows 安装带有指定的 NLS 文件。
  • 具体支持的 NLS 文件名由注册表读取。这些文件在系统目录（%WINDIR%\System32 或 %WINDIR%\SysWOW64）存在。这些目录中是否存在注册表中指定文件的 NLS 文件首先和系统支持的语言相关。
  • 新近版本的 64 位 Windows 10 可能在 %WINDIR%\System32\C_936.NLS 但不存在 %WINDIR%\SysWOW64\C_936.NLS 。由于 64 位 Windows 默认对系统目录重定向，导致 32 位系统中直接读取系统目录找不到 NLS 文件。在 build 937 前，YFramework 初始化加载 NLS 文件时不特别处理这种情况，因此 NLS 不可用。
• 若 Win32 NLS 初始化仍然失败，则 CHRLib 初始化 GBK 转换例程失败。

　　对其它平台，数据文件读取失败则 CHRLib 初始化 GBK 转换例程失败。

　　初始化失败后，使用 CHRLib 转换 GBK 编码的程序在调用转换例程时抛出异常，可能导致程序非正常退出。

MIME 数据

　　数据目录下的配置文件 MIMEExtMap.txt 存储 MIME 数据。若不存在，提供默认内容。

字体目录和文件路径

　　只要其中之一有效即可（若没有成功指定字体文件路径，则默认字体文件路径不确定）。

　　自动生成的配置中字体文件的默认路径如下：

• DS ：/Font/FZYTK.ttf
• Win32 ：系统字体目录下的 SimSun.ttc
• Android ：/system/fonts/DroidSansFallback.ttf
• Linux ：./SimSun.ttc

　　自动生成的配置中字体目录的默认路径如下：

• DS ：/Font 目录
• Android ：/system/fonts 目录
• 其它平台：同数据目录

特定平台运行环境

DS

　　以下说明中，$NDSEmulator 为模拟器 DeSmuME 可执行文件的绝对路径，$TargetPath 为 ROM 映像文件（ .nds 文件）的路径，$FAT_Path为 FAT 目录路径（见以下说明）。

　　之前经测试的最小版本为 0.9.6 。建议使用最新版本。

　　运行时，需在运行模拟器的宿主机中准备一个目录作为映射到设备中的虚拟 FAT 目录。宿主的目录在运行中不会被 DeSmuME 修改；宿主目录的文件系统不要求为 FAT 。运行时会加载虚拟目录的内容。

注意 官方版的 DeSmuME 不支持包含非 ASCII 字符的宿主路径而忽略这些文件。部分修改版可能没有这个限制。

注意 因为 DS 模拟器和烧录卡需要加载 ROM 映像到 RAM 后才能运行，映像大小会影响可用运行内存，使用 debug 配置构建的 YSTest 示例版本不一定在 DS 上支持所有功能。相关支持限制及变更详见 YSLib 项目文档 doc/Test.txt 。

　　可通过以下方式之一指定 FAT 目录。

Slot 1 映射

　　Slot 1 （即 NDS ROM 卡槽，硬件介质可以是 NDS 卡带，或烧录卡和存储卡的组合）的模拟从 DeSmuME 0.9.8 版本起支持。

　　运行命令行示例：

"$NDSEmulator" "$TargetPath" --preload-rom --slot1-fat-dir="$FAT_Path"

　　其中 --preload-rom 对 0.9.10 和 0.9.11 版本是必须的（以支持自动 DLDI(en-US) 补丁），否则加载失败。这个选项可以在模拟器（Windows 版本）的 GUI 菜单中 Config → ROM Loading 中选择。最新版本的源码会对自制 ROM 自动启用 ROM 预先加载的选项而不用另行配置，可以省略这个选项。

Slot 2 映射

　　Slot 1 （即 GBA ROM 卡槽，硬件介质可以是 GBA 卡带或其它扩展）的模拟需要配置为使用 GBA Movie Player (Compact Flash) 。

　　运行命令行示例：

"$NDSEmulator" "$TargetPath" --cflash-path="$FAT_Path"

　　对 0.9.10 和 0.9.11 版本，需同 Slot 1 映射添加 --preload-rom 或使用菜单设置加载选项，否则同样无法加载（尽管源码中表示 --preload-rom 是适用 Slot 1 而不是 Slot 2 的选项）。

　　这个选项也可以通过 GUI 配置。在 0.9.9 版本前，使用菜单 Emulation → GBA Slot 。自 0.9.9 版本起，使用菜单 Config → Slot 2 (GBA Slot) 。

注意 DeSmuME svn4030 及之后的一些版本（至少包括 0.9.8 ）会在载入 MPCF 映像时错误地忽略 --cflash-path 选项，以 仿真(Emulation) → GBA 插槽(GBA Slot) 菜单中的设置或对应配置文件 desmume.ini 中指定正确的路径。

　　在 desmume.ini 中有效的最小配置：

[GBAslot]
type=1
[GBAslot.CFlash]
fileMode=0
path=H:\NDS\efsroot\

　　这里 H:\NDS\efsroot 是 $FAT_Path 的一个示例。

注意 自 Slot1 0.9.10 起，当 Slot 1 设置为 R4 时会覆盖 Slot 2 设置加载 R4 路径（ Dev+ 版本显示自动 DLDI 补丁在 Slot 1 设置为 R4 从 GBA Movie Player (Compact Flash) 改为 R4(DS) - Revolution for DS ），因此需确保Slot 1 设置不为 R4 ，或正确设置了 Slot 1 R4 的路径（而改用 Slot 1 映射）。

MinGW32

　　自 build 431 起，YFramework 使用的 FreeImage 修改版集成 libjepg-turbo ，需要 CPU 支持 SSE2 指令集扩展。

　　除 2005 年前生产的硬件外绝大多数环境已经满足这个条件。当前几乎所有兼容 IA-32 的市售 CPU 都包含 SSE2 支持。特别地，支持 x86_64 指令集的 CPU 要求支持 SSE2 ，在使用 x86_64 的 64 位 Windows 上运行 32 位 Win32 程序（通过 WoW64 ）也支持 SSE2 。

Android

　　可使用 adb 命令安装 APK 包，如：

"$ANDROID_SDK/platform-tools/adb" -e install -r "$1"

　　此处 -e 指定 TCP/IP 设备（通常是模拟器），若使用 USB 设备（通常是物理机器）应移除或使用较新的 adb 的 -d 选项代替；"$1" 指定 APK 文件路径。

　　之后，在 Android 的 GUI 环境下直接运行安装的程序。

　　若因签名变更等原因无法覆盖安装或更新，需要先卸载后再安装。

注意 Android 安装 .apk 包时需要占用额外存储资源。为避免内置存储空间不足导致不直接表现安装失败（需要 logcat 查看）但直至运行时找不到二进制库而导致启动失败，应保留足够的空间，特别是对占用较大的 debug 配置构建的映像。保留空间的大小一般大于 .apk 作为 .zip 解压缩占用的空间。另见此处报告的未确认的类似问题。

框架初始化

　　框架初始化服务于整个框架。

　　初始化的重要策略之一是在程序启动时减少不必要的初始化，以允许实现以下目的：

• 减少可能的外部依赖（如不需要使用文字的程序就不初始化字体缓存，也不需要依赖外部字体文件和字体配置等）。
• 减少可能的运行时程序资源占用。
• 保留静态链接时优化去除没有调用的代码以减少二进制可执行文件大小的可能性。

　　按当前框架的设计，框架初始化在 DS 平台在程序运行初始阶段完成。其它平台可延迟初始化，按需调用。

　　并非所有 YFramework 中的 API 都要求框架初始化。以下功能隐含自动进行的框架初始化：

• 使用默认字体缓存。
• 使用 MIME 数据时。

　　框架初始化加载配置文件，其中配置文件路径的确定方式参见以下节的说明。成功公共加载配置文件后，框架初始化检查配置文件的内容，并访问框架公共配置。若检查失败，抛出异常。

　　修改 YFramework 模块 Helper::Initialization 重新编译后，可修改默认设置改变初始化行为。以下行为可能会在未来改变。

根路径

　　根路径(root path) 是框架初始化时参考的基本路径，由如下方式确定：

• Win32 和 Linux（除 Android ）：程序映像所在的目录。
• Android ：SD 卡目录（自动按顺序检测 /sdcard 、/mnt/sdcard 或 /storage/sdcard0 之一）。
• 其它平台：第一次初始化时的当前工作目录。

　　确定根路径在框架初始化或要求确定根路径时进行。若定位程序映像，同时会解析符号链接。若定位根路径失败，抛出异常。

　　抛出的异常默认不被框架处理，可使程序退出。用户代码捕获特定异常可改变默认退出行为。

配置路径

　　公共配置文件 yconf.txt 所在目录的路径前缀（结尾带有路径分隔符）称为框架的配置路径(configuration path) ，决定和平台相关的配置加载起始位置。配置路径和配置文件相对路径（对 yconf.txt ，即配置文件名）组合得到配置文件路径。

　　配置路径的确定方式和平台相关。

　　任意平台总能确定一个首选的配置路径。

　　除首选的配置路径外，一些平台还支持一个或多个不同的后备(fallback) 配置路径。在读写特定的配置文件时，若根路径访问失败，但存在后备配置路径，依序使用这些路径重试直至成功或全部访问失败。这样的配置文件当前包括 yconf.txt 。具体应用可使用初始化 API 以类似的方式加载其它配置文件。

　　以下是具有后备配置路径的平台中确定配置路径的顺序：

• Linux（除 Android ）：
  • 首先使用首选的配置路径。
  • 若环境变量 HOME 的值非空，则路径 $HOME/.YSLib/ 是后备配置路径。
• Win32 ：
  • 同 Linux 平台的顺序（对应使用 Win32 的环境变量和路径语法，即后备配置路径 %HOME%\.YSLib\ ）。
  • 若环境变量 USERPROFILE 的值非空，则路径 %USERPROFILE%\.YSLib\ 是后备配置路径。

　　后备配置路径中若子目录 .YSLib 不存在则被创建。若创建失败，配置路径访问失败。

　　对不具有后备路径的平台，首选的配置路径总是根路径。否则，首选的配置路径由以下方式确定：

• 程序映像所在的位置可推断出符合类似 FHS 的文件系统布局（称为局部 FHS 目录布局），则首选的配置路径为程序映像所在的目录的上一级目录的 var 子目录下的 YSLib 子目录。
  • 推断文件系统布局为以 POSIX 环境变量语法表示为 $PREFIX/、$PREFIX/$BIN/、$PREFIX/lib/ 和 $PREFIX/share/ 这些路径前缀都存在且可作为目录访问，其中 $PREFIX 是程序映像所在的目录的上级目录，而 $BIN 是程序映像所在的目录的名称（按 FHS 通常为 bin ，此处不检查）。
  • 这保证创建映像的可执行程序映像的目录中内容不被修改，以符合 FHS 。
• 否则，首选的配置路径为根路径。
  • 确定配置路径要求确定根路径。

　　对不具有后备路径的平台不检查文件系统布局，也不要求实现确保程序映像路径的操作，以简化实现。

注意 若后备配置路径的配置文件可访问，直接使用此配置文件保存配置，不再创建配置文件。若需要恢复在首选配置路径创建配置文件的行为，需确保后备配置路径的配置文件不可访问（例如，移除所有后备配置路径的这些配置文件）。

配置文件加载

　　加载配置文件 yconf.txt 时，首先按上述的顺序确定各个配置路径，每确定一个路径时访问其中的配置文件。若全部失败（如找不到可读的文件），则尝试自动生成配置并创建配置文件。创建配置文件的位置和顺序同上述确定配置路径的顺序。若创建配置文件全部失败，则放弃创建配置文件，直接使用生成的配置。

　　不存在配置文件时，配置不能通过 Helper::Initialization 的 API 持久化保存，尝试保存配置会失败。

其它初始化

　　成功后，框架进一步处理公共配置文件以外的其它初始化；详见以上具体配置文件的相关章节。