﻿/*
	© 2009-2014 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file Designation.txt
\ingroup Documentation
\brief 设计规则指定和说明。
\version r9202
\author FrankHB <frankhb1989@gmail.com>
\since 早于 build 132
\par 创建时间:
	2009-12-02 05:14:30 +0800
\par 修改时间:
	2014-05-24 06:09 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::Designation
*/


/*

@0 体例和适用范围：
引用标记参见 [Documentation::CommonRules @@0.1] 。
 YSLib 项目(the YSLib project) 包括 YFramework 和 YBase([Documentation::YBase]) 。
本文档适用于 YFramework 的开发。除非有特别说明，编码细节和其它规范也适用于 YBase 。

@1 设计：

@1.1 设计的基本原理和表达形式：
设计的出发点：构建一个可复用的组件组成的库框架。
代码不保证语义角度（例如实现需求）内容的连贯性。
原始目的：在以标准 C++ 环境（宿主实现或独立实现）为基础的嵌入式设备等平台上，建立常规应用程序框架。
扩展目的：渐进地向独立的计算机软件系统演进，探究具有高度互操作性的系统的一般实现方法。

@1.1.1 设计原则：

@1.1.1.1 规约视角：
仅向内廪语义耦合：使用列举外延定义概念前必须提取清晰的内涵，同时避免和其它概念的耦合。
避免重复冗余：语义允许忽略差异的应保持同一性(identity) 的概念和实体不应存在别名以外的副本。

@1.1.1.2 组件视角：
层次封装：组件可分为若干层次，在任意层次上都需要保持对满足一定接口约束的同类组件的可替换性（如果可能，也适用于库的外部依赖项）。
任务关联：允许对完成一种任务提供多种接口，但应尽量能在足够明确的限制条件下找到单一最佳实践。

@1.1.1.3 用户视角：
给用户提供选择的自由。
信任用户，给用户提供服务而不是检查用户的行为。（类似 C 和 C++ 的设计哲学。注意这点同时也允许未定义行为。）

@1.2 理论背景、工具和依据：
基本内容参见 [Documentation::CommonRules @@2.1] 。
表现以下设计意义：
环境隔离：对特定领域相关的上层源代码提供一致的接口。
抽象和封装：提供控制流实体语义的抽象；提供用于封装上层平台相关的模块的支持。

@1.2.1 组织概念模型：

@1.2.1.1 平台无关的组织分类：
框架核心称为 Core ；
其它必须直接基于 Core 之上一些外围功能实现程序是 Shell ；
和框架核心之间没有整体依赖性（依赖在逻辑上可被其它组件替代）的部分称为 Service 。
 Shell 和 Core 应保持相对独立，以方便移植。

@1.2.1.1.1 相对性：
Shell 和 Core 的关系是相对的，例如：
操作系统上层（最终）用户界面和服务相对于操作系统内核(kernel) ；
基于操作系统 Shell 的应用程序相对于操作系统 Shell 。
这样， Shell 和 Core 之间的相对关系可以级联。对组织虚拟化程序架构等有一定意义。

@1.2.1.2 环境(environment) ：
程序中的某一部分的外界称为环境。
根据限定程序的范围，可以有更确切的概念定义，如实现环境（对于一类语言实现而言）、运行时环境（对于共享实现环境的一类程序而言）。
一般地，实现环境可以分为独立环境(freestanding environment) 和宿主环境(hosted environment) ，区分依据为是否依赖于宿主（对于部署在单一计算机上的实现，一般指操作系统）的支持。
因此，环境有时指操作系统及其提供的外部服务的集合。
一些语言，如 ISO C 和 ISO C++ ，可以同时支持宿主环境和独立环境的实现，对应地独立实现(freestanding impementation) 和宿主实现(hosted impementation) 。

@1.3 构建原则：
基本内容参见 [Documentation::CommonRules @@2.2] 。

@1.3.1 可移植性相关：
基本内容参见 [Documentation::CommonRules @@2.2.2] 。
语言使用规则参见 [Documentation::CommonRules @@5] 。
依赖的语言实现参见 @5.2 。

@1.3.2 环境依赖性：
关于环境，参见 @1.2.1.2 。
关于库配置，参见 @5 。
本节适用于 YSLib 项目的各个库，用户程序不受此限制。
不使用和 ISO C++11 不相容的特性，包括 export 关键字([Documentation::CommonRules @@5.7.6]) 和已经在 ISO C++03 中标记为 deprected 而在 C++11 去除的特性（如 const char 数组类型左值到 char* 右值的转换）。
 YSLib 程序默认基于 ISO C++11 （包括 Defect Report 修正；扩展 ISO C++03 部分受 @1.3.2.1 限制）环境和基本的底层系统接口（由 YFramework/YCLib(@5.2.2) 支持）。
依赖 ISO C++ 独立实现或宿主实现，附加以下例外：
需要 @1.3.2.1 列出的扩展支持；
库要求等同于 ISO C++11 定义的宿主实现；
需要定宽整数 std::intN_t 和 std::uintN_t （其中 N 为 8 、 16 、 32 或 64 ）支持（ ISO C++11 中为可选支持）。

@1.3.2.1 需要使用的非 ISO C++03 扩展：
定义于 ISO C99（ISO/IEC 9899:1999）和 ISO C++11（ISO/IEC 14882:2011）中，且有一个以上完整的语言实现。
 Default template arguments for function templates(DR226) ；
 C99 preprocessor(N1653) ；
 Static assertions(N1720) ；
 Right angle brackets(N1757) ；
 long long(N1811) ；
 Built-in type traits(N1836) ；
 auto-typed variables(N1984) ；
 Delegating constructors(N1986) ；
 Extern templates(N1987) ；
 Generalized constant expressions(N2235) ；
 Variadic templates v0.9(N2242) ；
 New character types(N2249) ；
 Template aliases(N2258) ；
 Declared type of an expression v1.0(N2343) ；
 Defaulted and deleted functions(N2346) ；
 Strongly-typed enums(N2347) ；
 Null pointer constant(N2431) ；
 Explicit conversion operators(N2437) ；
 Unicode string literals(N2442) ；
 Raw string literals(N2442) ；
 Inline namespaces(N2535) ；
 New function declaration syntax for deduced return types(N2541) ；
 Initializer lists (N2672) ；
 Non-static data member initializers (N2756) ；
 Rvalue references v3.0(N3053) ；
 Lambda expressions and closures v1.1(N2927) ；
 Range-based for(N2930) ；
 Converting Lambdas to Function Pointers(N3052) ；
 Explicit virtual overrides v1.0(N3272) 。
接口和实现仅使用 ISO C++11 中新增头文件 <array> 、 <atomic> 、 <chrono> 、 <condition_variable> 、 <forward_list> 、 <mutex> 、 <system_error> 、 <thread> 、 <type_traits> 、 <tuple> 、 <unordered_map> 、<unordered_set> 和 <utility> 的特性。

@1.3.2.2
 YSLib 的源代码的本体([Documentation::YFramework @@2.1]) 是平台中立([Documentation::CommonRules @@2.2.2.1]) 的。其中的一部分在冯·诺依曼体系结构的现代数字式电子计算机的范畴内是平台无关的。

@1.3.2.3
格式化输出及结构对齐时注意平台字长差异。

@1.3.3 可维护性和架构设计：
基本内容参见 [Documentation::CommonRules @@2.2.3] 。
语义相关的架构参见 [Documentation::CommonRules @@2.3.2] 。

@1.3.4 实现功能特征概述：
便于扩展。
尽可能地平台无关，且注重效率。
能够保持必要的运行时安全性。
实现一部分的通用较高级功能，例如消息机制(@1.4.1.3) 。

@1.3.5 参考标准和规格说明：
基本内容参见 [Documentation::CommonRules @@1.1] 。
语言使用另见 @1.3.2.1 。
遵从的其它标准和规格说明：
暂略。

@2 框架概览：
参见 [Documentation::YFramework @@2] 。

@3 API 设计和风格概述：
基本规则参见 [Documentation::CommonRules @@3] 。

@3.1 类 C 标准库接口：

@3.1.1 内存管理行为：
接口不符合无隐式 malloc 规则 [Documentation::CommonRules @@5.25.3.1] 时必须向用户明确存储所有权。

@3.2 C++ 函数和函数模板：

@3.2.1 成员最小接口：
为了利用以类为单位的封装性（包括访问权限控制），一般类内的成员函数以最小接口为主，而人本接口在类外紧接类定义声明为第一个参数为类的引用类型的非成员函数。
可以适当使用友元简化接口和实现。

@3.2.2 函数参数和返回类型：
尽量使用返回值而不是输出参数传递结果，特别是在最小接口中。
合理使用默认函数参数减少需要的函数重载版本。
参数和返回类型选取规则参见 [Documentation::ProjectRules @@5.12.2] 。

@3.2.3 模板参数：
合理使用 ISO C++11 支持的函数模板的模板默认参数简化实现，减少需要的函数重载版本。

@3.3 错误处理：
基本内容参见 [Documentation::CommonRules @@3] 。

@3.3.1 异常消息：
使用仅使用基本字符集的字符串表示用户可读的消息。
除非必要，消息中不出现表示代码位置（例如所在函数）的信息，以免冗余。

@3.2.4 SFINAE(substition failure is not an error) 技巧：
使用 SFINAE 进行类型检查，实现复杂的重载匹配。避免暴露过于复杂的接口。
在模板参数或函数参数中使用 ISO C++11 的 std::enable_if 实现 SFINAE 。需要考虑函数签名时，只能使用前者；需要考虑模板和非模板的匹配顺序时，一般使用后者。

@4 标识符命名规约(naming convention) ：
以下是 YSLib 风格标识符的命名规则和约定。

@4.1
参见 [Documentation::CommonRules @@4.1] 。

@4.1.1 保留标识符：
基本内容参见 [Documentation::CommonRules @@4.1.6] 。

@4.1.1.1
以 "_y" 起始的标识符保留给 YSLib 库内部实现使用。

@4.1.1.2
以 "INCLUDED_" 起始的标识符专用于头文件包含标识。

@4.1.1.3 模板形式参数前缀：
以下前缀保留给的标识符保留作为模板形式参数的名称：
 "_b" ：布尔类型参数，包括内建 bool 类型的值或用于表示布尔值的 std::integral_constant 的实例（注意 value 成员不保证是 bool 类型）；
 "_f" ：函数/可调用对象(callable object) 或作为元函数的类型参数；
 "_i" ：接口（纯虚类）类型参数；
 "_p" ：内建指针类型参数；
 "_r" ：引用类型参数；
 "_t" ：不保证以上类型的其它类型参数；
 "_g" ：泛型类型（模板）参数，可能是元函数；
 "_gi" ：泛型接口（纯虚类模板）参数；
 "_gf" ：泛型函数/仿函数模板参数；
 "_v" ：其它非类型参数（值参数）。

@4.1.2 惯用函数命名：
基本内容参见 [Documentation::CommonRules @@4.1.7] 。
若在同一个作用域中出现多个不同的以下约定相同类别内的名称，可以后缀正整数以示区分。

@4.1.2.1 YBase 和 YFramework 约定：
使用以下固定含义的模板形式参数名称（前缀参见 @4.1.1.3 ）：
 _type ：一般类型参数；
 _type2 ：第二类型参数；
 _types ：一般类型多参数；
 _bCond ：表示选择结果的条件的 bool 参数。
 _tSeq ：表示序列的类型参数（一般需要是类类型；注意可以是元类型的实例，而不一定是容器类型）。
 _tScalar ：标量类型（和向量类型相对；注意不一定是 ISO C++ 定义的标量类型，即不需要保证满足 std::is_scalar 类型特征）；
 _fPred ：谓词函数类型；
 _tIter ：迭代器类型；
 _tIn ：输入迭代器类型；
 _tOut ：输出迭代器类型；
 _tFwd ：前向迭代器类型；
 _tBi ：双向迭代器类型；
 _tRandom ：随机访问迭代器类型；
 _tRange ：一般范围类型；
 _tCon ：容器类型（符合 ISO C++11 约定的容器要求的类型，或类似的在特定上下文中通过文档约定的类型如 std::string ，下同）；
 _tSeqCon ：序列容器类型。
使用以下非 ISO C++11 的要求中出现的其它成员名称：
 clone ：动态复制函数，返回类型为被复制的对象的指针。
 begin 和 end 以 ADL 为使用形式，一般使用命名空间作用域包装，不作为 YFramework 类的成员名称。

@4.1.2.2 YFramework 约定：

@4.1.2.2.1 模式 Fetch* ：
除了 YSLib 中非本体部分，命名空间作用域函数名 Fetch* ：语义近似于 Get*Of ，但遵循以下附加规则：
函数名符合模式 Fetch*Ref 的，返回类型为目标类型的引用或 const 引用类型；
函数名符合模式 Fetch*Ptr 的，返回类型为目标类型的指针、 const 指针或对应的智能指针类型；
目标类型为 POD 类型的，返回类型为目标类型；
其它情况返回类型为目标类型的引用或 const 引用类型。

@4.1.2.2.2 模式 Make* ：
类似 ISO C++ 标准库中的 make_* 。

@4.2 宏名：
基本内容参见 [Documentation::CommonRules @@4.2] 。

代码生成器：用宏展开为一段声明或定义的代码。

@4.2.3 全局保留宏名：
使用 YSLib 前需要保证未定义，且之后无法使用，除非使用 #undef 取消定义。
 YSLib 保留宏名以 "YSL" 起始，其基础库使用保留宏名以 "YCL" 起始。

@4.2.3.1 局部保留宏名：
使用 YSLib 前需要保证未定义，但库实现使用 #undef 限制作用域，因此之后可以使用。
 "This" 和 "CThis" 。

@4.3 类型名：
参见 [Documentation::CommonRules @@4.3] 。

@4.4 标号：
参见 [Documentation::CommonRules @@4.4] 。

@4.5 函数名：
参见 [Documentation::CommonRules @@4.5] 。

@4.6 具名对象：
参见 [Documentation::CommonRules @@4.6] 。

@5 程序部署和用户配置：
依赖项相关定义参见 [Documentation::ProjectRules @@1] 。
项目管理相关定义参见 [Documentation::ProjectRules @@2] 。
本章描述 YSLib 项目中除了 YFramework/YSLib 以外的依赖项。
 YSLib 项目的依赖项都是库，其中一部分是不由 YSLib 项目维护的第三方的外部依赖项。
外部依赖项中，系统库（ system library ，符合 GNU GPL v2 和 v3 条例定义）在平台配置中描述，可被所有非外部依赖项。
其它外部依赖项都被 YFramework 引用，如 FreeType2(@5.4.1) 。
以下如无特别说明，非外部依赖项的根路径取 YFramework 包含目录或源代码目录。

@5.1 平台配置：
关于平台的详细含义参见 [Documentation::ProjectRules @@1.2] 。
和本机语言实现相关的平台环境可使用经典系统类型名称(canonical system type name) 描述： architecture/vendor/OS/C library 四元组或 architecture/vendor/OS 三元组，除第一项外可能省略。
使用的实现（参见 @5.2 ）不和平台环境一一对应。一个平台环境可能有多个实现。
目标平台配置和 YCLib 平台定义文件(@5.2.2.4.1) 中定义的公共平台对应。

@5.1.1 配置管理：
基本配置管理参见 [Documentation::ProjectRules @@2.1]。
 MinGW32 为 DLL 目标追加对应 debug 和 release 的配置 debug_DLL 和 release_DLL 。

@5.1.2 当前正式支持的目标平台：
非宿主实现目标平台 DS （ Nintendo/iQue DS/DS Lite/DSi/DSi LL 以及 PC 端模拟器 DeSmuMe 等，对应系统名 arm-eabi 或 arm-none-eabi ）。
宿主实现目标平台 MinGW32 （对应系统名 i686-pc-mingw32 及其向前兼容的 i686-w64-mingw32 等）。
保证 MinGW-W64 的运行时可以正常构建。
使用 MinGW.org 的运行时自 b465 起支持。

@5.1.3 当前试验支持或不完全支持的目标平台：
当前试验支持宿主实现目标平台 Android （至少需 API Level 9 ）。

@5.1.4 平台限制：
当前 DS 仅使用静态链接库链接至目标。
当前 Android 不支持使用 Java 语言构建（ Makefile 缺少命令）；且仅支持单一动态库（ NativeActivity 限制）。

@5.2 环境实现：
除了 ISO C++ 标准库外的非外部依赖项：
基于标准库的基础库 YBase ，包含基于标准库的平台中立的扩展 YStandardEx 等，独立于 YFramework 。
基于 YBase 的平台隔离用库 YCLib(@5.2.2) ，包含于 YFramework 中。
 ISO C++ 实现定义行为要求：
至少支持 std::placeholder::_6 。
当前仅经过实际验证支持的实现包括 G++ 4.8.2 或以上版本。 YBase （包括若干 workaround ） 支持 Microsoft Visual C++ 2013 。
除以上列出外的其它实现不保证支持。
未来可能会提升实现的最低支持版本要求，并移除针对特定版本的 workaround 代码。
本节内列出的构建环境经过测试并用于发布。可能有其它可用兼容环境，不在此列出。

@5.2.1 YBase ：
参见 [Documentation::YBase] 。

@5.2.2 YCLib ：
 YCLib 包含平台相关的 API 包装和若干接口平台中立的独立子库（按头文件路径划分，参见 @5.4.1 ）。
 YCLib 允许平台中立的接口具有实现定义的行为差异。平台中立的接口的对应实体一般位于 namespace platform 。
除非另有说明， YCLib 仅保证非成员或静态成员函数的线程安全性。
平台定义文件 Platform.h 不包含其它文件。

@5.2.2.1 环境资源占用：

@5.2.2.1.1 DS 计时器：
 build 291 前占用计时器 0 和计时器 1 。
 build 291 起占用计时器 2 。
占用计时器用于实现计时接口。若用户占用计时器或修改计数，则计时相关接口结果未定义。

@5.2.2.2 实现定义行为：

@5.2.2.2.1 对于未说明字符串参数编码的文件操作接口：
必要时的编码转换使用 CHRLib([Documentation::YFramework @@2.7]) 。
注意 CHRLib 和 YCLib 相关接口中 UCS-2 在 Win32 下即为 UCS-2LE 。
 DS 直接使用 UTF-8 路径，或 UCS-2LE 转换得到的 UTF-8 路径，使用标准库函数或 POSIX 文件操作。
 MinGW32 直接使用 UCS-2LE 作为 UTF-16LE 路径，或 UTF-8 转换得到的 UCL-2LE 路径，使用 _w 起始的 MSVCRT 文件函数。

@5.2.2.3 平台 API 使用策略：

@5.2.2.3.1 Win32 API ：
需要 #undef 消除引起冲突的宏名，尽可能显式使用带后缀的函数（若存在）。
当存在后缀时，一般尽可能使用 W ，因为大部分情况下 W 后缀为原始版本， A 后缀需要转换间接调用 W 后缀版本。
但也存在例外， 如使用 ::OutputDebugStringA 。此时注意应该使相关字符串保持和 ANSI 及相关代码页的编码兼容，一般应仅使用 ASCII 。
不使用被标记为过时的 API 如 IsBadReadPtr 。

@5.2.2.4 平台文件：
引入平台相关特性。

@5.2.2.4.1 <Platform.h> ：
定义了必要的平台支持。另见 @5.1 。
对正式支持的独立平台定义 YF_Platform_ 起始的宏。宏 YF_Platform 指示实际的独立平台。
对正式支持的公共平台定义 YCL_ 起始的宏，保证替换得到的值非零。使用 #if （而不需要 #ifdef ）直接检测这些宏以确定是否支持。

@5.2.2.4.2 <NativeAPI.h> ：
定义了扩展的平台 API 。

@5.2.2.5 公共约束：
命名空间 platform 的成员满足以下约束（具体要求的定义参见 ISO C++11 ）。
 YCLib::Viedo 的 PixelType 满足 EqualityComparable 要求。

@5.2.2.6 命名空间 platform ：
命名空间 platform 中除以下另有说明外的实体和宏保持各个平台中可用且语义一致。

@5.2.2.6.1 命名空间 platform::KeyCodes
命名空间 platform::KeyCodes 用于公开输入设备的按键设置。其中的成员的一部分满足平台中立接口。
具体的按键由可以转换为 platform::KeyIndex 类型的实体标识。
按键值的数值不大于 platform::KeyBitsetWidth ，用于按键类别（由 platform::KeyCategory 的成员定义）判断，但不作为接口。
平台支持的按键值使用枚举类型 NativeSet 表示，按键值的数值由具体平台定义，一般不变。
不由平台直接支持的按键值使用枚举类型 ExtendedSet 表示，按键值的数值由 YCLib 定义，作为 ABI 的一部分，但不保证长期稳定。
此外，为了兼容提供 constexpr 对象作为按键别名。
 NativeSet 外的按键名都可以兼容以实现平台中立。当前 NativeSet 以 Win32 平台为基准的按键名称都保证兼容，因此平台中立按键名即当前 Win32 实现的按键集合。

@5.2.3 DS 平台工具链和标准库实现：
目标平台 DS ，实现环境参见 @5.1 。
系统库：使用 devkitPro（参见 http://devkitpro.org ） 中的 devkitARM 工具链及库文件的非 debug 版本。
依赖 devkitARM / libnds / default arm7 / libfat 版本：
 build 131 前：
未指定。可使用 devkitARM release 26 - 29 。
 2009-09-20 起：
 libnds 1.3.7 / default arm7 0.5.6 。
 2009-09-22 起：
 devkitARM release 26 / libnds 1.3.8 / libfat 1.0.4 。
 2009-12-12 起：
 devkitARM release 27 / libnds 1.4.0 / default arm7 0.5.8 / libfat 1.0.6 。
 2010-03-25 起：
 devkitARM release 29 / libnds 1.4.3 / default arm7 0.5.12 / libfat 1.0.7 。
 2010-04-06(build 131) 起：
 devkitARM release 30 。
 2010-08-08(build 139) 起：
 devkitARM release 31 / libnds 1.4.5 / default arm7 0.5.14 。
 2010-09-19(build 244) 起：
 default arm7 0.5.15 。
 2010-11-18(build 171) 起：
 devkitARM release 32 / libnds 1.4.8 / default arm7 0.5.17 。
 2011-01-06(build 180) 起：
 libnds 1.4.9 / default arm7 0.5.18 。
 2011-02-16(build 192) 起：
 libnds 1.5.0 / default arm7 0.5.20 / libfat 1.0.9 。
 2011-06-24(build 221) 起：
 devkitARM release 33 / libnds 1.5.0 。
注：文件系统目录访问接口变化，需要使用 devkitARM release 33 或自行配置所需的 POSIX API 。
 2011-07-03(build 223) 起：
 libnds 1.5.1 / default arm7 0.5.21 。
 2011-07-05(build 223) 起：
 devkitARM release 34 。
 2011-08-27(build 236) 起：
 libnds 1.5.4 / default arm7 0.5.23 。
 2011-10-13(build 252) 起：
 devkitARM release 35 / libfat 1.0.10 。
 2012-03-06(build 291) 起：
 devkitARM release 37 。
 2012-04-12(build 300) 起：
 devkitARM release 38 / libnds 1.5.5 / default arm7 0.5.24 。
 2012-05-03(build 306) 起：
 devkitARM release 39 / libnds 1.5.7 。
 2012-05-14(build 308) 起：
 devkitARM release 40 / libfat 1.0.11 。
 2012-06-29(build 321) 起：
 devkitARM release 41 。
 2014-04-06(build 492) 起：
 devkitARM release 42 / libnds 1.5.8 / libfat 1.0.12 / default arm7 0.5.25 。
 2014-04-13(build 493) 起：
在 Windows 上使用 MSys2 环境的包 make 代替 devkitPro/msys 。参见 @5.2.5 。

@5.2.3.1 DS 平台构建说明：
需要使用宏 DEVKITARM 指定 devkitARM 的路径。

@5.2.4 MinGW32 平台工具链和标准库实现：
目标三元组(target triplet) i686-w64-mingw32 ，操作系统 Windows XP/Windows Server 2003 （对应 Windows SDK 版本宏 WINVER 值 0x0501 ）及以上。
系统库：使用 MinGW 间接依赖的 Win32 API 相关库（如 user32 和 gdi32 ）以及 MSVCRT(Microsoft Visual C++ Runtime Library) 的特定版本。
 build 299 前：
无（不支持的平台）。
 2012-04-09(build 299) 起：
使用 http://code.google.com/p/mingw-builds 的 i686-mingw32-gcc-4.7.0-release-c,c++,fortran-sjlj 。
 2012-06-21(build 319) 起：
使用 http://sourceforge.net/projects/mingwbuilds/files/windows-host/4.7.1/release/i686-mingw-w64-gcc-4.7.1-release-c,c++,fortran-sjlj.7z 。
此版本于 2012-10-06 确认已被移除。
此版本于 2013-01-20 确认已被重命名为 x32-4.7.1-release-posix-sjlj-rev0.7z 。
 2012-10-06(build 346) 起：
使用 http://sourceforge.net/projects/mingwbuilds/files/host-windows/releases/4.7.2/32-bit/threads-posix/sjlj/x32-4.7.2-release-posix-sjlj-rev0.7z 。
 2013-03-23(build 392) 起：
使用 http://sourceforge.net/projects/mingwbuilds/files/host-windows/releases/4.8.0/32-bit/threads-posix/sjlj/x32-4.8.0-release-posix-sjlj-rev0.7z 。
 2013-06-03(build 411) 起：
使用 http://sourceforge.net/projects/mingwbuilds/files/host-windows/releases/4.8.1/32-bit/threads-posix/sjlj/x32-4.8.1-release-posix-sjlj-rev0.7z 。
 2013-07-20(build 431) 起：
增加依赖项 NASM 2.07 ： http://sourceforge.net/projects/nasm/files/Win32%20binaries/2.07/nasm-2.07-installer.exe/download 。
当前不直接用于构建 YSLib ，仅用于构建依赖项。
 2013-10-20(build 453) 起：
使用 http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/4.8.2/threads-posix/dwarf/i686-4.8.2-release-posix-dwarf-rt_v3-rev0.7z 。
 mingw-builds 已被合并至 mingw-w64 官方仓库。改变异常模型以兼容 i686 的 LLVM/Clang++ 工具链，这导致二进制兼容性不被保持。
注意之前由于 mingw-w64 的 bug （参见 http://sourceforge.net/mailarchive/message.php?msg_id=31045447 ），即使不改变异常模型也不能保持二进制兼容性。
 2014-01-04(build 465) 起同时支持 MinGW.org 工具链，但由于实现质量等原因，不用于默认发布。
 2014-04-15(build 493) 起：
基础环境更改参见 @5.2.5 。
使用包 mingw32/mingw-w64-i686-gcc 和 mingw32/mingw-w64-i686-gcc-libs 版本 4.8.2-7 。
使用的工具链版本、线程模型和异常模型及外部库的依赖和之前保持一致，因此二进制兼容。

@5.2.4.1 MinGW32 库部署：
 YSLib 内部使用固定的相对路径，不依赖库的部署。
用户程序依赖 YSLib 库（注意静态库可包括第三方库）时，可以复制库文件或建立直接的符号链接，使用以下方法：
 静态库文件（文件名形如 'lib$(LIB).a' ，其中 $(LIB) 是可能带有 d 后缀表示调试版本的库名，下同）置于链接器的搜索路径指定的目录内；
 动态库文件（文件名形如 '$(LIB).dll' ）置于链接器的搜索路径指定的目录内，但重命名为 $(LIB).dll.a ；
 动态库文件（文件名形如 '$(LIB).dll' ）在 PATH 环境变量内或直接依赖的文件所在的目录以便被搜索。
在链接器命令行中引用 $LIB 指定库。静态库链接时同时需要在之前使用 -Wl,-dn 选项以避免链接至动态库（默认链接器优先链接 $(LIB).dll.a 而不是 lib$(LIB).a ）。
以上部署方式中链接器搜索路径中的静态库和动态库的调试版本和非调试版本可以在一个目录内，不产生冲突。

@5.2.5 Windows 构建宿主公共环境：
 Msys 用于 Windows 上版本的构建环境。
 build 458 前：
使用 devkitPro 附带的实现。
 2013-11-22(build 458) 起：
对于 MinGW32 ，使用 http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/msys%2B7za%2Bwget%2Bsvn%2Bgit%2Bmercurial%2Bcvs-rev13.7z 。
 2014-04-12(build 493) 起：
使用 http://sourceforge.net/projects/msys2/files/Base/i686/msys2-base-i686-20140216.tar.xz 作为基础环境。
同时使用 "Tools/msys2-update-pacman.sh" 更新包。
每次主分支版本前同步 MSys 环境（ @5.2.4 中明确提到的除外）至最新版本，但保证只依赖对于基础环境向后兼容的特性，因此应可直接升级到更新版本使用。

@5.2.6 Android 平台工具链和标准库实现：
 build 492 前：
无（不支持的平台）。
 2012-04-07(build 492) 起：
使用 JDK 8u5 x64 、 Android SDK 和 Android NDK r9d 。
使用 API level 9 ， SDK Tools 版本 19.0.3 。
独立工具链目标三元组 arm-linux-androideabi ，构建脚本参见 Tools/make-clang-android.sh 。

@5.2.6.1 Android 平台构建说明：
需要使用宏 ANDROID_SDK 指定 Android SDK 的路径。
构建 YSTest 主目标时不依赖 NDK ，仅需 JDK 、 Android SDK 和独立工具链。
构建脚本会对生成的包签名，因此需要需要准备私钥。用 Tools/create-android-debug-keystore.sh 可生成默认私钥。
构建脚本接受 APK_KEYSTORE 宏指定私钥路径，默认值为 ~/.android/debug.keystore 。可在环境中覆盖。

@5.3 通用库：

@5.3.1
 build 207 前使用 Loki 库的智能指针实现句柄。

@5.4 专用库：
包含于 YFramework 中的子库。
关于 CHRLib ，参见 [Documentation::YFramework @@2.7] 。
关于 Helper ，参见 [Documentation::YFramework @@2.8] 。
关于 NPL ，参见 [Documentation::YFramework @@2.9] 和 [Documentation::NPL]。
本节余下内容描述第三方专用库。

@5.4.1
字体输出使用 FreeType2（参见 http://www.freetype.org ） 实现向量字体光栅化支持。
历史记录、版本信息和构建方法详见 "3rdparty/freetype/Readme.en-US.txt" 。

@5.4.1.1 使用版本：
以下库配置若之前版本已存在，除非另行说明，保持不变。
除非另行说明，使用当时 devkitPro(@5.2.3) 自行编译 DS 库文件，使用当时 MinGW32(@5.2.4) 自行编译 MinGW32 库文件。

@5.4.1.2 DS 库配置：
 build 185 前：
头文件版本： 2.3.12 。
库文件版本：在 VNDSx-1.5.3 源代码中提取的 2.3.6 。
 build 185 起：
头文件版本： 2.4.4 。
库文件版本：使用 makefile 宏 CFLAGS ?= -c -g -O3 -Wall 编译库文件。
库配置： modules.cfg 配置包含以下有效行：
FONT_MODULES += truetype
FONT_MODULES += sfnt
HINTING_MODULES += autofit
HINTING_MODULES += pshinter
RASTER_MODULES += smooth
AUX_MODULES += cache
AUX_MODULES += gzip
AUX_MODULES += psnames
BASE_EXTENSIONS += ftbitmap.c
BASE_EXTENSIONS += ftglyph.c
使用 makefile 宏 CFLAGS ?= -c -g -O3 -Wall 。
 2011-07-03(build 223 rev 31) 起：
头文件版本： 2.4.5 。
库配置： modules.cfg 配置追加以下有效行：
BASE_EXTENSIONS += ftbbox.c
BASE_EXTENSIONS += ftstroke.c
BASE_EXTENSIONS += ftsynth.c
 build 224 rev 34 起：
使用 FreeType 2.4.5 ，但源文件目录 "cache" 使用 2.4.4 版本替换，以修正不明原因的 FontCache::GetAscender 的结果错误。
重新编译库文件。
 2011-12-01(build 266) 起：
使用 FreeType 2.4.8 ，但源文件目录 "cache" 使用 2.4.4 版本替换，原因同上。
库配置： modules.cfg 配置移除以下有效行：
AUX_MODULES += psnames
重新编译库文件。
 2012-03-11(build 292) 起：
使用 FreeType 2.4.9 。证实已修复 cache 错误。
重新编译库文件。

@5.4.1.3 DS 和 MinGW32 库配置：
 2012-03-29(build 296) ：
准备增加 MinGW32 库文件版本，预备 modules.cfg 配置不变。
 2012-04-06(build 299) 起：
增加 MinGW32 库文件版本，使用 mingw32-make 直接构建默认提供的 makefile 。
 modules.cfg 配置不变。
 2012-06-17(build 318) 起：
使用 FreeType 2.4.10 。
 2012-12-21(build 366) 起：
使用 FreeType 2.4.11 。
 2013-05-18(build 405) ：
测试发现 2.4.12 库在 DS 上的性能显著降低，因此决定暂不升级；仅重新编译减小二进制文件大小。
 2013-05-19(build 406) 起：
 modules.cfg 配置移除以下有效行：
HINTING_MODULES += pshinter
AUX_MODULES += gzip
BASE_EXTENSIONS += ftbbox.c
库配置和 DS 库构建文件已添加至版本库，参见 "3rdparty/freetype/builds/ds/modules.cfg" 。
 DS 库文件： 2.4.11 去除 -g 选项（以减小文件体积）重新编译。
 MinGW32 库文件： 重新编译。
 2013-07-01(build 420) 起：
使用 FreeType 2.5.0.1 ，但部分文件使用 2.4.11 版本替换，参见 [Documentation::Meta @@ $workaround_b420] 。
对原始版本的修改：
 "include/freetype/config/ftoption.h" ：保持 2.4.11 版本。
 "src/sfnt/ttmtx.c" ：使用 2.4.11 版本。
 modules.cfg 配置移除以下有效行：
HINTING_MODULES += autofit
AUX_MODULES += cache
BASE_EXTENSIONS += ftfstype.c
BASE_EXTENSIONS += ftstroke.c
BASE_EXTENSIONS += ftsynth.c
重新编译 DS 库文件。
实际用于 MinGW32 的 modules.cfg 配置并未移除以上有效行。
重新编译 MinGW32 库文件。
 2013-11-30(build 459) 起：
使用 FreeType 2.5.1 ，替换文件同上，除路径 "include/freetype/config/ftoption.h" 变更为 "include/config/ftoption.h" 。
库配置： modules.cfg 配置追加以下有效行（否则 WOFF 支持会因为调用的 GZip 函数未定义而导致 YFramework 链接失败）：
AUX_MODULES += gzip
 MinGW32 改为使用同 DS 一致的 modules.cfg 。
重新编译 DS 和 MinGW32 库文件。
 2013-12-24(build 462) 起：
使用 FreeType 2.5.2 ，替换文件同上。
 2014-04-13(build 493) 起：
使用 FreeType 2.5.3 ，替换文件同上。
 MinGW32 库文件： 使用命令行显式设置 CFLAGS="-c -O3 -Wall -fomit-frame-pointer -DNDEBUG" 重新编译。

@5.4.2
图形库：修正的 Anti-Grain Geometry 库 V2.4 。
 2011-01-19(build 187) 起移除。

@5.4.3
图像库使用 FreeImage 。
历史记录、版本信息和构建方法详见 "3rdparty/FreeImage/Readme.en-US.txt" 。

@5.4.3.1 使用版本：
以下库配置若之前版本已存在，除非另行说明，保持不变。
除非另行说明，使用当时 devkitPro(@5.2.3) 自行编译 DS 库文件，使用当时 MinGW32(@5.2.4) 自行编译 MinGW32 库文件。
 2013-06-26(build 417) 起：
使用裁剪的 FreeImage 3.15.4 。对原始版本的修改参见 "3rdparty/include/FreeImage.h" 和 "3rdparty/FreeImage/" 。
 2013-07-21(build 431) 起：
使用裁剪的 FreeImage 3.15.4 ，并使用 libjpeg-turbo-1.3.0 替换 libjpeg-8d ，更新了 zlib 和 libpng 。对原始版本的修改参见 "3rdparty/include/FreeImage.h" 和 "3rdparty/FreeImage/" 。
注意增加的 libjpeg SIMD 代码在 MinGW32 依赖于 NASM(@5.2.4) 构建。
 2013-10-21(build 453) 起：
在上一版本的基础上更新 libpng ，并重新编译 MinGW32 库文件。

@5.5 库基础结构：
平台设置在 <YCLib/Platform.h>(@5.2.2.4.1) 中。
除了 MinGW32 的平台运行时外，所有外部链接库为静态库。除了 YCLib 外，对外部库未经过封装的使用仅在 Adaptor 中。这样有利于以子库为单位的移植。

@5.6 全局命名空间：
基本规则参见 [Documentation::ProjectRules @@3.5] 。
除了使用标准库命名空间 std 外如下所列。

@5.6.1 标准库实现提供的附加命名空间：
 __gnu_cxx ： libstdc++ 扩展，可被 YBase::LibDefect 和 YFramework::YSLib::Adaptor 使用。

@5.6.2 YBase 引入的命名空间：
 YBase 引入的主要命名空间唯一且和次级子项目的模块名称一致（但 YDefinition 此处同 YStandardEx ）。
 ystdex ：从 std 扩充的平台无关的实用程序 YStandard 。 YSLib 本体直接依赖于此命名空间。
 ytest ：测试框架设施 YTest 。

@5.6.3 YFramework 引入的命名空间：
参见 [Documentation::YFramework @@2.3.2] 。

@6 编码风格导引：
仅叙述之前章节未涉及的内容。
基本内容参见 [Documentation::CommonRules @@6] 。

@6.1 源代码嵌入文档：
使用 Doxygen 。
编码适应大多数源文件，默认为 UTF-8 。
默认语言为简体中文（在接口文档中使用；实现中的注释默认使用美式英文）。

@6.1.1 注释风格：
使用简化的（去除可以省略的星号后的） Qt 风格的注释。
分行例外（默认参见 [Documentation::CommonRules @@6.4.1] ）： URL 链接等超出默认行宽时可在同一行（无法生成正确的代码）。

@6.1.2 指令同义词：
当多种指令等价时使用 Doxygen 手册中直接说明（而非指示同义词即 "Equivalent to" ）的一项。
例外：
对外部参考使用 \see 而不是 \sa ；
 \throw 指显式抛出异常， \exception 指内部调用间接抛出的异常。

@6.1.3 指令行风格：
组(group) 相关指令（ \defgroup 、 \ingroup 、 \name 等）、实体标识指令（ \def 、 \fn 等）以及 \author 、\par 、 \sa 、 \since 、 \version 不使用句为单位（不使用全角标点）；其它指令后的内容以句为单位（对于中文注释以全角标点结束；不成句的不视为完整的注释）。
 \defgroup 指令在所有文件中应保持无歧义地出现一次以避免错误。
 \par 指令以半角“:”结尾。
实体注释中详细注释放在最后，和之前的指令相隔一个空行。

@6.1.4 指令格式和顺序：
组相关指令在最前（且对于 \defgroup ，跟随注释首行“*”后使用一个水平制表符分隔），然后依次为实体标识指令（除了 \def ，一般省略）和其它指令。
指定顺序的段落指令： \brief 、 \tparam 、 \param 、 \pre 、 \post 、 \invariant 、 \return 、 \throw 、 \exception 、 \note 、 \warning 、 \bug 、 \deprecated 、 \relates 、 \sa 、 \see 、 \since  、 \todo 、 \par 。
从属的非段落指令如 \code 、 \endcode 、\tt 、 \verbatim 等不限制顺序。
其它顺序参见 http://drupal.org/node/1354#links 。

@6.2 YFramework 规则：
参见 [Documentation::YFramework @@4] 。

@6.3 其它实现规则：
在建议 [Documentation::CommonRules @@5.3.3.1] 的基础上强制要求全局名称保留前缀 :: 规则。
全局 operator new/delete 使用前缀 :: 以强调确定使用全局版本（对应非名称的 new/delete 表达式也同样使用）。
其它一般全局名称的使用总是保留前缀 :: 以便移植。
同理，除非另有约定，所有外部平台基础库不使用 using namespace 省略前缀命名空间的调用，同时保持和全局名称不省略 :: 的形式一致。
依次以部件、事件和调用形式的顺序集中添加或移除事件处理器，其中调用形式约定为操作符调用、成员函数调用和非成员函数调用；使用宽松分行([Documentation::CommonRules @@6.4.3.1]) 分隔处理器列表项。

@7 一般实现导引：
自定义应用程序 Shell 类，继承默认 Shells::Shell 类或其派生类并产生实例。
完成自定义 Shell 类的消息处理过程。一般把多个处理过程的响应封装为单一函数。
对于支持实现对应 Shell 的窗口封装为窗体（Form）类（一般继承自 Window 类），在此自定义类中添加所需的 GUI 部件的定义，并实现界面效果。
在响应输入等事件消息的处理过程中添加对应的代码。

@7.1 初始化：
需要保证主 Shell 句柄在应用程序实例初始化之后初始化，基类 Shell 的构造函数调用了 Application 的非静态成员函数。

*/
////

