heX 打包生成工具说明

自 v1.1.10 版本开始,heX 支持将 web 前端资源打包(非压缩)。我们借助 Chromium 项目中的 GRIT 工具进行资源打包。因此,打包过程中需要 Python 2.6 或更新版本的支持。

工具位于 Release/tools 文件夹中,make_grd 的入口为 make_grd.pygrit 的入口为 grit/grit.py

打包生成分为两部分,其中第一部分可以通过 heX 提供的自动化工具生成,也可以手动生成。

1. make_grd

make_grd 工具是一段用 Python 写的脚本。它的作用是根据目标文件夹下的文件系统结构生成一个资源列表文件,扩展名为 .grd,本质上为一个 XML 文件。里面包含以下重要信息:

  • /grit/outputs/output[filename=web_resources.json]:生成供 heX 读取的 JSON 版资源文件列表。此文件名必须为 web_resources.json,不可改变。
  • /grit/outputs/output[filename=*.pak]:生成供 heX 读取的打包后的 PAK 格式的资源文件。所有的 web 前端资源都将打包到此文件中。此文件名默认为 web_resources.json,也可以是其他文件名,这取决于清单文件中的 application_shortname 配置项。
  • /grit/release/includes/include:include 元素包含了三个重要属性,
    • file 属性指定了文件名以及其相对路径,此路径是相对于上面的目标文件夹。
    • name 属性为此文件指定一个名称,不可重复。
    • type 属性为此文件类型,一般为扩展名,若没有扩展名则自动转换为 BINDATA。

make_grd 工具的调用方法很简单,默认情况下必须指定 path 参数:

python tools/make_grd.py --path=web

这样,工具就会试图遍历当前工作路径下的 web 文件夹内的所有文件及子文件夹,并在当前工作路径下生成一个 web_resources.grd 文件。

也可以指定生成的 GRD 文件的文件名,以及 GRD 文件中输出的 PAK 文件的文件名。--output 指定输出的 GRD 文件,--pak 指定输出的 GRD 文件中指定的 PAK 文件名,如:python tools/make_grd.py --path=web --output=web.grd --pak=test.pak

最终可能会生成如下 GRD 文件:

<?xml version="1.0" encoding="utf-8"?>
<grit current_release="1" latest_public_release="0">
  <outputs>
    <output filename="web_resources.json" type="rc_header">
      <emit emit_type="prepend"/>
    </output>
    <output filename="test.pak" type="data_package"/>
  </outputs>
  <release seq="1">
    <includes>
      <include file="index.html" name="INDEX_HTML" type="html"/>
  </release>
</grit>

当然我们可以自己手动生成这个文件。

2. grit

grit 工具全称 Google Resource and Internationalization Tool,是 Chromium 项目的一部分。我们对 GRIT 进行了轻度的改装,以使它可以生成出我们需要的 web_resources.json。调用方法:

首先确定要打包的文件夹,如 /Users/admin/dev/test,将上一步的 GRD 文件复制到这个文件夹中。执行 python tools/grit/grit.py -i /Users/admin/dev/test/web_resources.grd build -o web

上面这段命令的意思是,读取 /Users/admin/dev/test/web_resources.grd,并在当前工作路径下的 web 文件夹下生成打包后的资源文件,包括 web_resources.json 以及 GRD 文件中指定的 PAK 文件名。

3. 加载资源

此时我们在输出的文件夹中得到了 web_resources.json 及 PAK 文件。将这两个文件复制到 heX 应用程序所在目录,并修改 manifest.json

manifest.json 中有一项 use_grit_package 必须设置为 true,另一项 application_shortname 值为字符串,允许为空。

当值为空时:PAK 文件的文件名 必须web_resources.pak,此时加载的 URL 形式为 chrome://xxx/yyy,其中 xxx 为当前可执行文件名(默认为 hexclient),yyy 为 web_resources.json 文件中的文件及其路径。如:chrome://hexclient/index.html

当值不为空时:PAK 文件的文件名 必须application_shortname 的值 .pak,如 application_shortname 值为 test,则 PAK 文件名为 test.pak。此时加载的 URL 形式为 chrome://xxx/yyy,其中 xxxapplication_shortname 值,yyy 为 web_resources.json 文件中的文件及其路径。如:chrome://test/main/index.html