如何使用Qomo的Builder系统

aimingoo Javascript, Qomo, OpenSource Project

1. Qomo的Builder系统

Qomo在Beta2之后，主要解决的一个问题就是Builder系统。在设计上，Qomo对Builder系统提出了非常严格(甚至是苛刻)的要求，其中包括：

  • 使用Qomo自身的框架来实现
  • 使用JavaScript来实现，而不要第三方的应用(例如.exe的压缩程序)
  • 对既有的和将来的Qomo项目透明，无影响
  • 深入到Qomo内核的、分层的、可分解的模块定制
  • 编译的结果代码，与使用中的调试版本无差异

这些要求所主要表现的，就是Qomo的Builder可以定制，而且对使用者来说公开、透明。

由于JavaScript是解释执行的脚本，而并没有真正的“编译”能力，所以在Qomo中所谓的“编译(Build)”其实是指两个过程：

  • Link: 连接。将各个代码块有序地组合成单一的.js文件
  • Compress: 压缩。清除代码中的空格等，使代码尽可能地变得短小以缩短载入时间

使用Qomo的Builer所产生的结果，是生成一个单独的.js文件。——由于网页中的JavaScript没有写文件的能力，所以事实上是生成了结果的代码块，用户可以手工复制到一个.js文件中去。

这个生成的单独的.js文件是可以任意命名的，为了方便，下面都称其为“Qomo.js”。——不过，在mozilla里只能命名为Qomo.js(或自行修改代码中的一个正则表达式)。

2. Builder的体系结构

Qomo的Builder系统被放在Qomo的根目录之下，位于Qomo/Build目录中，下面是这个目录的说明。

Build目录包括的子目录有：

   packer/      : 一个可由用户使用的压缩器程序，但目前Qomo并没有使用到它。
   jsmin/       : 一个开源的、JavaScript实现的压缩器。Qomo使用了它的js版本，而其中的jsmin.exe只是为了用来压缩jsminfull.js。 :)
   TestCase/    : 测试代码，包括一个示范性的Builder工具。
   sample_final/: 编译结果的测试示例，包括编译时使用的参数配置

Build目录包括的代码有：

   Default.Config.js     : 编译的缺省配置
   Builder.html          : 编译器(对话框)
   Building.js           : 提供给Qomo的用于编译(连接)的模块
     FinalBuilder.js     : 在Building.js中使用的一个inline代码块
   ProtectCodeContext.js : 压缩算法中用于快速清除注释的类
   Compressor.js         : 算法器类
     Compressor(1).js    : 一种压缩算法的inline代码块
     jsmin.js            : jsmin压缩的js版本

Build/TestCase子目录包括的代码有：

   T_RemoveImport.html   : 测试程序 - 移除Qomo.js中特定代码块的
   T_TestFinal.html      : 测试程序 - 检查编译后的Qomo.js是否能有效装载
   T_Builder.html        : 浏览器兼容的通用示例和工具 - 用于“连接(link)”代码
   T_Compress.html       : 浏览器兼容的通用示例和工具 - 用于“压缩(compress)”代码
   T_CustomBuilder.html  : 能在IE上使用的示例和工具 - 完整的编译工具

基本上来说，整个体系中的关键代码在于Build/Building.js。它使用了Qomo的特性以侵入Qomo代码的装载(import)过程，并收集过程中的信息。而Build/FinalBuiler.js则用于拼装这些收集来的信息，以及对代码做一些(可预测的)修改：

  • Building.js的侵入不修改Qomo的流程，也不影响这个流程；
  • finalBuilder.js的拼装和修改以不影响Qomo中的代码块为基本前提。

3. Qomo中如何Builder代码 - for IE

在IE中，你可以直接打开T_CustomBuilder.html来编译代码。编译过程是可视的，你只需要将结果代码复制到一个.js文件中即可。——你应该使用utf-8编码的、文本格式的.js文件。

使用T_CustomBuilder.html编译时，界面上的各个配置项都可以任意组合。——当然，“任意”并不一定有价值，在另一篇文档中，我会专门讲述Qomo的层次结构，你便于你更合理地编译一个最终交付(或发布)的Qomo版本，以使用在你的项目中。

界面上的一些配置项是被禁用的，但当另一些配置项被选中／取消时，它们会被开启。这种关联关系，被配置在两个地方。其一是Default.Config.js中，用 js代码的方式来控制了模块的依赖性，以使编译出的代码可用。还有是在T_CustomBuilder.html中载入的uicontrol.js文件里，它仅用于控制T_CustomBuilder.html里的界面表现。

有两个选项在T_CustomBuilder.html中总是无效的。即“图形组件库”和“数据库组件库”。

这是因为在Qomo V1.0 Final中，这两个组件库并没有被正式发布。如果要把它们编译进去，你需要将T_CustomBuilder.html中的DebugComponents变量置为true。事实上“扩展界面控件”也没有被发布。但其中一些代码仍是可用的，所以被选项被置为开启了。

要在最终代码中包含“图形组件库”、“数据库组件库”和“扩展界面控件”之任一，你都需要自己解压v1.0 final发布包中的(Trial)Components.zip，使得Components目录的位置与Framework目录的位置在同一级上。

使用T_CustomBuilder.html编译和发布代码的一些配置与生成代码的示例，放在sample_final目录中。请参考配置即可。

4. Qomo中如何Builder代码 - for FF

在FireFox等mozilla兼容浏览器用使用Qomo的builder相对要麻烦一点。但这也使得过程更加清晰。

  • 首先用编辑器打开T_Builder.html，确定你需要装载哪些模块，并修改该网页中被注释掉的一段脚本代码。——将false改成true。
  • 然后在浏览器中打开这个网页，你会看到一个文本框中已经链接(link)好了全部的代码。
  • 接下来，在浏览器中打开T_Compress.html，将前面链接好的代码复制到T_Compress.html的文本框中。然后按下"compress it.."按钮。
  • 文本框中会出现压缩后的代码。

ＯＫ，复制它并存入你的Qomo.js即可。

5. Builder.html的使用

Builder.html是浏览器兼容的，因此你也可以在fireFox里打开它。但事实上它不并不显示编译后的结果。——它是一个对话框，并向打开它的主窗口返回结果代码。

Builder.html包括了压缩与链接两个部分。你需要做的，只是写一个主页面，并写下类似如下的代码：

  data_compiled = showModalDialog('Builder.html', $QomoConfig, "...");

如果$QomoConfig参数为null，则Builder.html将使用默认配置(装入所有的代码)，否则将根据$QomoConfig的设置来完成编译。

你可以在代码中加入如下的HTML，以载入一个$QomoConfig变量的副本：

<script src='/Qomo/Qomo.Config.js'></script>

Qomo.Config.js中是一个最小化声明的配置信息。因此，载入该脚本之后，你也可以在打开Builder.html之前修改$QomoConfig的值。示例如下：

$QomoConfig.set('Building', true);  $QomoConfig.set('Profiling', false);

此后，将变量$QomoConfig作为参数传给打开Builder.html的对话框即可。而该对话框在关闭时会返回一个编译完成的字符串。

关于该过程的细节，请参考T_CustomBuilder.html。与后者不同的是，Builder.html是浏览器兼容的。——因此如果需要，你可以写自己的Custom Builder for Other Browser. :)

6. 生成编译后代码(Qomo.js)的部署

在不使用命名空间时，生成的Qomo.js是一个与路径无关的单独文件，你可以在服务器的任意位置上部署该文件。也可以编写代码，使用Qomo.js中的任何类和函数。

在使用命名空间时，Qomo.js能够自动地找到当前路径并为你设定命名空间。按照约定，Qomo总是依照目录结构来注册类的命名空间。在编译的 Qomo.js 中，保存了一套虚拟的路径映射，以使得你可以在Qomo.js所在目录中创建如下两个子目录：

  Framework/
  Components/

并将代码放在这两个目录中。在使用Class()注册后，会自动地注册到Qomo的命名空间。你也可以使用$map()和$mapx()建立自己的命名空间与路径映射。关于这些，请参考有关路径与命名空间的文档。

你可以把代码放在任何位置，而不仅限于上述的目录。但在你自己映射路径与命名空间之前，它们都被注册到Qomo.Thirdparty路径下。

7. 关于兼容层代码

Builder只将当前（编译环境）中的浏览器相关的代码编译到Qomo.js中，其它所有的兼容层代码都未被链入。因为并非所有的人都希望为兼容环境做B/S开发。——当然，也还有其它的一些原因，例如未来可能要支持非浏览器环境下的JavaScript Host。

如果你使用Qomo.js，又希望它支持兼容环境。那么你应该将Qomo目录下的Framework/Compat/目录中的文件复制到与Qomo.js相同的目录下。保持如下的路径关系：

  .../Qomo.js  .../*.*

由于在使用兼容层时，$import模块总是被链入的。因此，Qomo在检测到与当前（编译环境）不同的浏览器时，会自动地载入对应的兼容模块。

在将来的版本中，Qomo允许你指定这个兼容层代码所在的目录位置。——如果你需要，也可修改编译后的Qomo.js中的代码。

8. 几个附助的选项

T_CustomBuilder.html中有几个辅助的选项，包括：

  • 添加文件头
  • 清除注释
  • 不压缩
  • 移除配置信息

其中，“添加文件头”是不可选的，它的作用，就是在Qomo.js代码的最前面添加一个版权信息而已。仅从代码上说，你也可以移除它。但建议你保留这些信息。至少，其中的版本号与发布时间是有价值的。

“移除配置信息”用于清除了$QomoConfig这个全局函数。该函数用于查询编译期的配置。——你的确有可能代码要用到它。但如果不需要，你也可以移除。在编译后的Qomo.js中，是不再需要调用这个函数的。

如果你选择“不压缩”，则Builder只是连接代码，而并不压缩它。这样它就可以很方便地调试和修改了。

当选择“不压缩”时，你也可以取消“清除注释”选项。这样的代码将只是简单的拼接。Qomo使用了非常有效的“清除清释”的算法，使得清除后的代码可读性仍然很高。因此，大多数情况下，你不需要取消这个选项。