KISSY Module Compiler

author: 承玉

简介

  • 是一个自动模块依赖合并工具.
  • 是一个自动模块依赖抽取工具.
  • 是一个模块代码规范辅助工具, 可以辅助规范模块编写, 不仅仅只适用动态加载场景, 也可以用来提高开发阶段效率.
  • 是一个模块代码部署工具. 结合 KISSY Loader , 用于模块代码部署阶段, 多个模块根据其依赖合并为一个文件, 减少 HTTP 链接数.

下载

推荐使用 Ant 整合调用: Ant

使用说明

该工具为一个 jar 包, 推荐嵌入到 ant 中, 作为项目构建的一个阶段.

Note

ant 以及相关压缩工具可直接使用 kissy-tools 中的文件, 建议直接下载整个 kissy-tools 作为项目工具一部分.

举例

下载 kissy module compiler demo

源文件结构:

src/
    biz/
         x.js
         y.js
         page/
              run.js

其中 x.js 内容为:

KISSY.add(function() {
  return"x + overlay + switchable"
}, {requires:["overlay", "switchable",'./x.css']});

其中 y.js 内容为:

KISSY.add(function(S, x) {
  return"y + " + x
}, {requires:["./x","./y.css"]});

其中 run.js 内容为:

KISSY.add(function(S, y) {
  return"run + " + y
}, {requires:["../y"]});

下面介绍 KISSY Module Compiler 的两个用法:模块依赖自动合并与模块依赖自动抽取

1. 模块依赖自动合并

配置一下 build.xml

<!--
build example for kissy loader
@author yiminghe@gmail.com
-->
<project name="compressor.build" default="build" basedir="." xmlns:ac="antlib:net.sf.antcontrib">

    <!--入口文件模块所在目录-->
    <dirname property="current.dir" file="${ant.file.compressor.build}"/>
    <property name="assets.dir" location="${current.dir}/src/"/>
    <property name="page.dir" location="${assets.dir}/biz/page/"/>
    <property name="page.dir.tmp" location="${current.dir}/tmp/"/>
    <property name="build.dir" location="${current.dir}/build/"/>
    <property name="page.build.dir" location="${build.dir}/biz/page/"/>
    
    <!--项目文件编码-->
    <property name="charset" value="utf-8"/>

    <!-- kissy tools 项目源码目录 -->
    <!-- 注意:请用 kissy tools 中的 ant 运行此 xml -->
    <property name="ks.tools" value="d:\code\kissy_git\kissy-tools\"/>
   
    <property name="module.compiler" value="${ks.tools}\module-compiler\module-compiler.jar"/>    

    <!-- js 构建-->
    <target name='jsrun' depends="combo">
    </target>
    
    <target name='prepare'>
        <mkdir dir="${build.dir}"></mkdir>
        <mkdir dir="${page.build.dir}"></mkdir>     
        <copy encoding="${charset}" todir="${build.dir}">
            <fileset dir="${assets.dir}" includes="**/*.css"/>
        </copy>
    </target>
    
    <!--js  combo 地址获取-->
    <target name='combo' depends="prepare">
        <ac:for param="page">
            <!--入口模块文件所在目录的所有模块循环处理-->
            <path>
                <fileset dir="${page.dir}" includes="*.js" excludes="*.combo.js,*-min.js,*.dep.js"/>
            </path>
            <sequential>
                <ac:var name="var.modname" unset="true"/>
                <basename property="var.modname" file="@{page}" suffix=".js"/>
                <echo>
                    build ${var.modname} in @{page}
                </echo>
                <java classname="com.taobao.f2e.Main">
                    <arg value="-require"/>
                    <!-- 入口模块 -->
                    <arg value="biz/page/${var.modname}"/>

                    <arg value="-baseUrls"/>
                    <arg value="${assets.dir}"/>

                    <arg value="-encodings"/>
                    <arg value="${charset}"/>

                    <arg value="-outputEncoding"/>
                    <arg value="${charset}"/>

                    <arg value="-output"/>
                    <arg value="${page.build.dir}/${var.modname}.js"/>

                    <arg value="-outputDependency"/>
                    <arg value="${page.build.dir}/${var.modname}.dep.js"/>

                    <classpath>
                        <pathelement path="${module.compiler}"/>
                        <pathelement path="${java.class.path}"/>
                    </classpath>
                </java>
            </sequential>
        </ac:for>
    </target>

    <!--项目(js,css)构建-->
    <target name="build" depends="jsrun"/>

</project>
1.1 参数说明
require

需要打包的入口模块 .

baseUrls

模块文件查找目录集合, 一般是业务模块的源码目录, 多个目录间以 , 分隔. 如 x:/code/ .

encodings

指明模块目录中文件的编码, 顺序对应于 baseUrls , 多个编码以 , 分隔. 如以上示例: gbk , 表示业务模块为 gbk 编码.

outputEncoding

指明最后合并打包文件的编码格式. 如以上示例 utf-8 .

output

指明最终合并打包后的文件路径以及名称. 如示例: x:/code/package/y.combine.js , 表示该工具产生的合并后文件为 x:/code/package/y.combine.js . 一般建议压缩后的文件名要和 “入口模块文件名” + “-min” 一致.

outputDependency

可选。入口模块的依赖配置文件。 使用自动 combo 时需要.

1.2 最终效果

目录结构

build/
     biz/
        page/
            run.js
            run.dep.js

其中 run.combo.js 内容为:

/*
 Combined modules by KISSY Module Compiler: 

 biz/x
 biz/y
 biz/page/run
*/

KISSY.add("biz/x", function() {
  return"x + overlay + switchable"
}, {requires:["overlay", "switchable", "./x.css"]});
KISSY.add("biz/y", function(S, x) {
  return"y + " + x
}, {requires:["./x", "./y.css"]});
KISSY.add("biz/page/run", function(S, y) {
  return"run + " + y
}, {requires:["../y"]});

其中 run.dep.js 内容为:

/*Generated By KISSY Module Compiler*/
KISSY.config('modules',{
'biz/page/run': {requires: ['overlay','switchable','biz/x.css','biz/y.css']}
});
1.3 连接状况
  1. 若服务器不支持自动 combo ,则不用引入 run.deps.js,最终三个链接 run.js 和 overlay.js 以及 switchable.js
  2. 若服务器支持自动 combo ,则可引入 run.deps.js,配置 KISSY.config("combine",true) 后即可将switchable 和 overlay 的请求合为一个连接.最终两个连接 run.js 以及 ??overlay.js,switchable.js

2. 模块依赖自动抽取

配置一下 build.xml

<!--
build example for kissy loader
@author yiminghe@gmail.com
-->
<project name="compressor.build" default="build" basedir="." xmlns:ac="antlib:net.sf.antcontrib">

    <!--入口文件模块所在目录-->
    <dirname property="current.dir" file="${ant.file.compressor.build}"/>
    <property name="assets.dir" location="${current.dir}/src/"/>
    <property name="build.dir" location="${current.dir}/build-combo/"/>
    
    <!--项目文件编码-->
    <property name="charset" value="utf-8"/>

    <!-- kissy tools 项目源码目录 -->
    <!-- 注意:请用 kissy tools 中的 ant 运行此 xml -->
    <property name="ks.tools" value="d:\code\kissy_git\kissy-tools\"/>
   
    <property name="module.compiler" value="${ks.tools}\module-compiler\module-compiler.jar"/>    

    <!-- js 构建-->
    <target name='jsrun' depends="combo">
    </target>
    
    <target name='prepare'>
        <mkdir dir="${build.dir}"></mkdir>
        <copy encoding="${charset}" todir="${build.dir}">
            <fileset dir="${assets.dir}" includes="**/*"/>
        </copy>
    </target>
    
    <!--js  combo 地址获取-->
    <target name='combo' depends="prepare">
        <java classname="com.taobao.f2e.ExtractDependency">
            <arg value="-baseUrls"/>
            <arg value="${build.dir}"/>

            <arg value="-encodings"/>
            <arg value="${charset}"/>

            <arg value="-outputEncoding"/>
            <arg value="utf-8"/>

            <arg value="-output"/>
            <arg value="${build.dir}/deps.js"/>

            <arg value="-fixModuleName"/>
            <!--自动 combo 需要补全文件名-->
            <arg value="true"/>

            <classpath>
                <pathelement path="${module.compiler}"/>
                <pathelement path="${java.class.path}"/>
            </classpath>
        </java>
    </target>

    <!--项目(js,css)构建-->
    <target name="build" depends="jsrun"/>

</project>
2.1 参数说明
baseUrls

模块文件查找目录集合, 一般是业务模块的源码目录, 多个目录间以 , 分隔. 如 x:/code/ .

encodings

指明模块目录中文件的编码, 顺序对应于 baseUrls , 多个编码以 , 分隔. 如以上示例: gbk , 表示业务模块为 gbk 编码.

outputEncoding

指明最后合并打包文件的编码格式. 如以上示例 utf-8 .

output

最终依赖配置文件的路径

fixModuleName

默认 false. 是否自动补全模块名.

2.2 最终效果

目录结构

build-combo/
            deps.js
            biz/
                 x.js
                 y.js
                 page/
                      run.js

其中 deps.js 内容为:

/*Generated by KISSY Module Compiler*/
KISSY.config('modules', {
'biz/page/run': {requires: ['biz/y']},
'biz/y': {requires: ['biz/x','biz/y.css']},
'biz/x': {requires: ['overlay','switchable','biz/x.css']}
});

其中 x.js 内容为:

KISSY.add("biz/x", function() {
  return"x + overlay + switchable"
}, {requires:["overlay", "switchable", "biz/x.css"]});

其中 y.js 内容为:

KISSY.add("biz/y", function(S, x) {
  return"y + " + x
}, {requires:["./x", "biz/y.css"]});

其中 run.js 内容为:

KISSY.add("biz/page/run", function(S, y) {
  return"run + " + y
}, {requires:["../y"]});

Note

注意自动 combo 需要配置 fixModuleName 以补全模块名。

2.3 连接情况

通过引入 deps.js 以及配置 KISSY.config("combine",true) 最终应用会产生两个连接 :

  1. biz/??x.js,y.js,page/run.js
  2. ??overlay.js,switchable.js