如何使用Qomo的Builder系统

================================================================================
Qomolangma OpenProject v1.0

类别    ：Rich Web Client
关键词  ：JS OOP，JS Framwork, Rich Web Client，RIA，Web Component，
          DOM，DTHML，CSS，JavaScript，JScript

项目发起：aimingoo ([email protected])
项目团队：../../Qomo_team.txt
================================================================================

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/: 编译结果的测试示例，包括编译时使用的参数配置(PNG图片)

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，使得Comonents目录的位置与
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
使用了非常有效的“清除清释”的算法，使得清除后的代码可读性仍然很高。因此，大多数
情况下，你不需要取消这个选项。