导航

　　YSLib 是什么？

　　返回目录查看其它内容。

目标读者

　　本文预期的读者是对了解如何使用 YSLib 创建项目感兴趣的开发者。

基础知识

　　本文假定读者已经掌握或了解以下知识，不详细展开讨论：

  • 计算机体系结构常识
  • 了解规范 C++ 语言的标准（ISO/IEC 14882）
  • 了解什么是语言的实现（如编译器和链接器等）并掌握常见实现的使用方法（如 G++ 命令行）
  • 有必要时，能避免依赖只在特定实现支持的方言特性

概要

　　本文档说明开发 YSLib 程序的简易操作。以下仅提供操作步骤和主要意义的解释。

注意 若需自行定制构建，参照以下引用的文档的全文，而非某个特定章节；再按照构建中的步骤执行。

　　当前只有关于 Windows 下使用 MinGW32 的内容，基于 MSYS2 环境。

环境配置

　　使用 YSLib 开发需要配置 YSLib 环境，以确保 YSLib 的库和相关环境可用。

　　当前建议直接在本机环境中从源代码构建安装 YSLib ，参照以下步骤和要点：

  • 参照先决条件的 PC(MinGW32) 一节给出的链接下载 MSYS2 并配置环境，执行脚本安装所需的工具。
    • 注释 若不需要构建 GUI 应用程序，也可以参照先决条件的 PC/Linux 一节，在 Linux 环境下本机构建。
  • 获取源代码。
    • 若直接从版本库获取，直接构建可能找不到库而在链接时失败。可以自行参照文档构建缺少的外部依赖项，或从归档仓库下载二进制文件放置到指定的库文件路径中，详见开发说明。
    • 文件不包含 POSIX 权限。若需在依赖文件权限的环境（包括典型的 Linux 环境）中直接运行 shell 脚本，需确保（可能被间接调用的）脚本文件可执行，如运行 find Tools -type f -name "*.sh" -exec chmod +x {} \; 。
  • 参照 Sysroot ，运行 Tools/install-sysroot.sh 脚本以构建 YSLib 并安装头所需的文件，得到 Sysroot 环境。然后，把 sysroot/usr/bin 目录的完整路径加入 PATH 环境变量（一般应添加在最前端）。
    • 注意 除非了解确切的作用，不要添加 YSLib 中的其它目录到 PATH ；添加不合适的目录可能会导致脚本运行失败。

注释 以上是对新手的建议步骤。为了避免在之后的步骤中出现需要回溯解决的问题，这些步骤务求详尽。若已了解构建环境配置或为自动化部署，通常总是可以使用一行脚本在受支持的环境中直接构建 Sysroot 。

开发基础

　　以下介绍使用 YSLib 开发须知的基础要点，并说明如何开发示例程序。

控制台程序和图形用户界面(GUI) 程序

　　需要注意，在 Windows 中控制台程序仍然可以包含 GUI 。

　　YSLib 支持各种用户应用程序。为了简便起见，以下只介绍 GUI 程序的使用。更具体的说明参见 Windows 子系统。

编写 Hello World 程序

　　新建 C++ 源文件（名称任意，但需要以 .cpp 等作为扩展名以保证 SHBuild 作为 C++ 源文件处理），内容如下：

#include <YSBuild.h>
#include YFM_Helper_GUIApplication
#include YFM_YSLib_UI_Label
#include YFM_Helper_HostedUI

int
main()
{
	using namespace YSLib;
	GUIApplication app;
	UI::Label wgt({480, 360, 160, 24});

	wgt.Text = u"Hello world!";
	Host::ShowTopLevel(wgt, WS_CAPTION | WS_SYSMENU | WS_MINIMIZEBOX, 0);
	Execute(app);
}

关于头文件

　　可以安全地重复包含头文件。

　　注意到 #include 后可以是一个宏。这里表示路径的宏 YFM_* 由 <YSBuild.h> 保证定义，因此这个头文件需要在使用这些宏之前被包含。

　　使用宏表示 YFramework 的大多数头文件名是兼容性的需要。用户程序不需要使用这种策略，尤其是集成开发环境可能会对这样引入的头文件的修改不敏感而导致的构建遗漏。

　　MinGW32 平台的 Helper::HostedUI 的头文件已经保证包含了 <Windows.h> 中宿主窗口的声明，不需要显式包含。

使用 SHBuild-BuildApp 脚本构建程序

　　把上面的文件保存到一个空的目录下，以下以 $SRC 指定这个目录名。

　　执行以下命令：

bash -c "cd $SRC; SHBuild-BuildPkg.sh release ."

　　在目录 $SRC/.release 下找到构建好的可执行文件（具体文件名取决于源文件名），执行观察结果。

说明

　　bash -c 启动新的 shell 执行命令。

　　cd $SRC 切换 shell 的当前工作目录到源代码目录。

　　SHBuild-BuildPkg.sh 调用构建脚本。脚本的参数分别是：

  • release 是一个配置名称。配置名称决定保存生成的文件的输出目录相对当前工作目录的位置，这里输出目录是当前工作目录下的 .release 子目录。可以更换配置名称以指定不同的输出目录。 　　* 若配置名称以 debug 起始，启用调试配置，自动使用调试库和构建选项。
  • . 表示构建的目录源代码的根目录为当前工作目录。
  • 之后的可选参数在此省略。

　　构建脚本以特定的选项调用 SHBuild 工具作为脚本解释器执行 NPLA1 脚本 SHBuild-BuildApp.txt ，详见 Sysroot 。

　　SHBuild-BuildApp.txt 内部再次调用 SHBuild 工具进行构建。默认会递归扫描整个目录（除了名称以 . 起始的子目录外）。若存在多个源文件，这些文件都会被一起编译并链接。为了避免预期以外的结果，之前要求源文件在空目录中。

其它方法

　　也可以直接调用 SHBuild 或者编译器命令行，但需要手动指定调用编译器的参数以及链接的库等，较为复杂，在此从略。

清理

　　无论是 SHBuild 还是 SHBuild-BuildPkg.sh 当前都不提供清理功能。因为包括中间文件的输出文件都在同一个输出目录中，直接删除输出的目录即可。

进一步阅读

　　参见开发说明的相应章节和进阶的教程。