• R/O
  • SSH

YSLib-wiki: Commit

The wiki source of YSLib documentation.


Commit MetaInfo

Revision51234500f85c0830906f3f59df0db651c074f05a (tree)
Time2020-10-10 14:43:16
AuthorFrankHB <frankhb1989@gmai...>
CommiterFrankHB

Log Message

Run.zh-CN.md: 从开发文档迁移并更新部分框架初始化的内容;添加 MinGW32 平台依赖 CPU 指令集扩展的说明;添加外部依赖项名称的说明。

Change Summary

Incremental Difference

diff -r a1a41c885807 -r 51234500f85c Run.zh-CN.md
--- a/Run.zh-CN.md Tue Sep 29 17:04:09 2020 +0800
+++ b/Run.zh-CN.md Sat Oct 10 13:43:16 2020 +0800
@@ -24,14 +24,16 @@
2424
2525 # 文件系统
2626
27-  为最大化可移植性,原则上 YSLib 的程序逻辑**不依赖自身组件具有显式编码的具体文件路径**,因此默认不要求在具体系统约定的周知(well-known) 目录部署。但具体平台配置可以自行限定目录布局作为默认运行时环境,如 [Sysroot](Sysroot.zh-CN.md) 。其中外部文件可有默认路径,参见以下相关章节。
27+  为最大化可移植性,原则上 YSLib 的程序逻辑**不依赖自身组件具有显式编码的具体文件路径**,因此默认不要求在具体系统约定的周知(well-known) 的文件系统位置(如 [Windows DLL 搜索路径](https://docs.microsoft.com/zh-cn/windows/win32/dlls/dynamic-link-library-search-order)中的目录和 [FHS](https://zh.wikipedia.org/zh-cn/%E6%96%87%E4%BB%B
28+6%E7%B3%BB%E7%BB%9F%E5%B1%82%E6%AC%A1%E7%BB%93%E6%9E%84%E6%A0%87%E5%87%86) 定义的目录)部署。但具体平台配置可以自行限定目录布局作为默认运行时环境,如 [Sysroot](Sysroot.zh-CN.md) 。其中外部文件可有默认路径,参见以下相关章节。
2829
2930   YSLib 中的库使用的文件系统路径具有以下约束:
3031
31-* 不依赖兼容 POSIX 的文件系统和路径表示
32- * 特别地,不依赖文件系统是否具有文件名的大小写敏感性
33- * **推论** 为保证可移植性,中的路径需显式明确大小写;可兼容 FAT 等文件系统
34-* 要求支持符合 YSLib 项目规范的开发(参见项目的 `doc/ProjectRules.txt` )
32+* 不依赖兼容 POSIX 的文件系统和路径表示。
33+ * 特别地,不依赖文件系统是否具有文件名的大小写敏感性。
34+ * **推论** 为保证可移植性,文件系统路径大小写敏感,需要显式区分而加以明确。
35+ * 这样仍可兼容 FAT 等大小写不敏感的文件系统。
36+* 要求支持符合 YSLib 项目规范的开发(参见项目的 `doc/ProjectRules.txt` )。
3537
3638   一般地, YBase 不要求文件系统访问;使用 YFramework 框架的程序,由 YFramework 中的框架初始化等逻辑引入文件系统访问。
3739
@@ -45,10 +47,13 @@
4547 * 对于静态链接 YFramework 和 YBase 程序,不需要其它二进制程序文件的部署。
4648 * 使用 DLL 的程序可能依赖 YFramework.dll 和 YBase.dll ,或者 debug 配置的 YFrameworkd.dll 和 YBased.dll 。这些库已经在 sysroot 的 `bin` 目录下安装,因此可以直接把 `bin` 目录加入 `PATH` 环境变量,而不必复制或移动库文件。
4749
50+**说明** 在任意被支持的平台上,YSLib 避免使用导致在特定平台上被特殊处理且无法可靠避免这种行为而确保兼容性一致的外部依赖项名称(若因为外部环境更新导致此类问题,则需在 YSLib 的新版本适当修改后支持)。例如,支持 [API Set Schema](http://www.geoffchappell.com/studies/windows/win32/apisetschema/index.htm) 的 Windows 版本加载 DLL 时,[`LdrLoadDll` 解析以 `api-` 或 `EXT-` 起始的文件名进行重定位](https://stackoverflow.com/a/47530043/2307646) ,因此设计时确保外部依赖项对应的文件名不以这些前缀起始。
51+
4852 # 外部文件
4953
5054   外部文件包括:
5155
56+* 在文件系统中部署的外部二进制依赖项。
5257 * 配置文件:可被修改以改变程序的运行时行为。
5358 * 其它数据文件。
5459
@@ -243,6 +248,12 @@
243248
244249 **注意** 自 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 映射)。
245250
251+## MinGW32
252+
253+  自 build 431 起,YFramework 使用的 [FreeImage](https://freeimage.sourceforge.io/) 修改版集成 [libjepg-turbo](https://zh.wikipedia.org/zh-cn/Libjpeg#libjpeg-turbo) ,需要 CPU 支持 [SSE2](https://zh.wikipedia.org/zh-cn/SSE2) 指令集扩展。
254+
255+  除 2005 年前生产的硬件外绝大多数环境已经满足这个条件。当前几乎所有兼容 IA-32 的市售 CPU 都包含 SSE2 支持。特别地,支持 x86_64 指令集的 CPU 要求支持 SSE2 ,在使用 x86_64 的 64 位 Windows 上运行 32 位 Win32 程序(通过 [WoW64](https://zh.wikipedia.org/zh-cn/WoW64) )也支持 SSE2 。
256+
246257 ## Android
247258
248259   可使用 `adb` 命令安装 APK 包,如:
@@ -261,21 +272,75 @@
261272
262273 # 框架初始化
263274
264-  需要修改 YFramework 的模块 Helper::Initialization 重新编译后修改默认设置改变初始化行为。以下行为**可能会在未来改变**。
265-
266-  自动生成 `yconf.txt` 所在目录的默认路径称为框架的**根路径**,和平台相关,如下:
275+  框架初始化服务于整个框架。
267276
268-* Win32 和 Linux :程序映像所在的目录
269-* Android : SD 卡目录(自动检测 `/sdcard` 、 `/mnt/sdcard` 或 `/storage/sdcard0` 之一)
270-* 其它平台:当前工作目录
277+  初始化的重要策略之一是在程序启动时减少不必要的初始化,以允许实现以下目的:
271278
272-## 根路径定位
279+* 减少可能的外部依赖(如不需要使用文字的程序就不初始化字体缓存,也不需要依赖外部字体文件和字体配置等)。
280+* 减少可能的运行时程序资源占用。
281+* 保留静态链接时优化去除没有调用的代码以减少二进制可执行文件大小的可能性。
273282
274-  定位根路径在框架初始化时进行。若定位程序映像,同时会解析符号链接。若定位根路径失败,默认异常退出。
283+  按当前框架的设计,框架初始化在 DS 平台在程序运行初始阶段完成。其它平台可延迟初始化,按需调用。
275284
276-  成功加载配置文件后,框架初始化检查配置文件的内容,并访问框架公共配置。若检查失败,默认异常退出。
285+  并非所有 YFramework 中的 API 都要求框架初始化。以下功能隐含自动进行的框架初始化:
277286
278-  用户代码捕获特定异常可改变上述的默认退出行为。
287+* 使用默认字体缓存。
288+* 使用 MIME 数据时。
289+
290+  框架初始化加载配置文件,其中配置文件路径的确定方式参见以下节的说明。成功公共加载配置文件后,框架初始化检查配置文件的内容,并访问框架公共配置。若检查失败,抛出异常。
291+
292+  修改 YFramework 模块 Helper::Initialization 重新编译后,可修改默认设置改变初始化行为。以下行为**可能会在未来改变**。
293+
294+## 根路径
295+
296+  **根路径(root path)**是框架初始化时参考的基本路径,由如下方式确定:
297+
298+* Win32 和 Linux(除 Android ):程序映像所在的目录。
299+* Android :SD 卡目录(自动按顺序检测 `/sdcard` 、 `/mnt/sdcard` 或 `/storage/sdcard0` 之一)。
300+* 其它平台:第一次初始化时的当前工作目录。
301+
302+  确定根路径在框架初始化或要求确定根路径时进行。若定位程序映像,同时会解析符号链接。若定位根路径失败,抛出异常。
303+
304+  抛出的异常默认不被框架处理,可使程序退出。用户代码捕获特定异常可改变默认退出行为。
305+
306+## 配置路径
307+
308+  公共配置文件 `yconf.txt` 所在目录的路径前缀(结尾带有路径分隔符)称为框架的**配置路径(configuration path)**,决定和平台相关的配置加载起始位置。配置路径和配置文件相对路径(对 `yconf.txt` ,即配置文件名)组合得到配置文件路径。
309+
310+  配置路径的确定方式和平台相关。
311+
312+  任意平台总能确定一个首选的配置路径。
313+
314+  除首选的配置路径外,一些平台还支持一个或多个不同的**后备(fallback) 配置路径**。在读写特定的配置文件时,若根路径访问失败,但存在后备配置路径,依序使用这些路径重试直至成功或全部访问失败。这样的配置文件当前包括 `yconf.txt` 。具体应用可使用初始化 API 以类似的方式加载其它配置文件。
315+
316+  以下是具有后备配置路径的平台中确定配置路径的顺序:
317+
318+* Linux(除 Android ):
319+ * 首先使用首选的配置路径。
320+ * 若环境变量 `HOME` 非空,则路径 `$HOME/.YSLib/` 是后备配置路径。
321+* Win32 :在 Linux 的基础上:若 `$HOME` 非空,则路径 `$HOME/.YSLib/` 是后备配置路径。
322+ * 同 Linux 平台的使用顺序(对应使用 Win32 的环境变量和路径语法,即备份路径 `%HOME%\.YSLib\` )。
323+ * 若环境变量 `USERPROFILE` 非空,则路径 `%USERPROFILE%\.YSLib\` 是后备配置路径。
324+
325+  后备配置路径中若子目录 `.YSLib` 不存在则被创建。若创建失败,配置路径访问失败。
326+
327+  对不具有后备路径的平台,首选的配置路径总是根路径。否则,首选的配置路径由以下方式确定:
328+
329+* 程序映像所在的位置可推断出符合类似 FHS 的文件系统布局(称为局部 FHS 目录布局),则首选的配置路径为程序映像所在的目录的上一级目录的 `var` 子目录下的 `YSLib` 子目录。
330+ * 推断文件系统布局为以 POSIX 环境变量语法表示为 `$PREFIX/`、`$PREFIX/$BIN/`、`$PREFIX/lib/` 和 `$PREFIX/share/` 这些路径前缀都存在且可作为目录访问,其中 `$PREFIX` 是程序映像所在的目录的上级目录,而 `$BIN` 是程序映像所在的目录的名称(按 FHS 通常为 `bin` ,此处不检查)。
331+ * 这保证创建映像的可执行程序映像的目录中内容不被修改,以符合 FHS 。
332+* 否则,首选的配置路径为根路径。
333+ * 确定配置路径要求确定根路径。
334+
335+  对不具有后备路径的平台不检查文件系统布局,也不要求实现确保程序映像路径的操作,以简化实现。
336+
337+**注意** 若后备配置路径的配置文件可访问,直接使用此配置文件保存配置,不再创建配置文件。若需要恢复在首选配置路径创建配置文件的行为,需确保后备配置路径的配置文件不可访问(例如,移除所有后备配置路径的这些配置文件)。
338+
339+## 配置文件加载
340+
341+  加载配置文件 `yconf.txt` 时,首先按上述的顺序确定各个配置路径,每确定一个路径时访问其中的配置文件。若全部失败(如找不到可读的文件),则尝试自动生成配置并创建配置文件。创建配置文件的位置和顺序同上述确定配置路径的顺序。若创建配置文件全部失败,则放弃创建配置文件,直接使用生成的配置。
342+
343+  不存在配置文件时,配置不能通过 Helper::Initialization 的 API 持久化保存,尝试保存配置会失败。
279344
280345 ## 其它初始化
281346
Show on old repository browser