build系统是dojo异于其它Javascript框架的显著特征之一。通过build你的Dojo-based Javascript应用程序,可以立即获得以下好处:
- Java使用一个类一个文件的组织方式,这种方式方便了开发期管理;发行时可以将class打包成package,又减少了发行时的对象个数(如果采用压缩话,还缩小了文件尺寸)。通过dojo的build系统,就可以将指定目录下的全部或者部分Javascript自动打包成一个javascript文件,称作layer。因此,在开发中也可以做到一个’类’一个文件,而不用担心布署问题。
- 在build过程中可以指定是否做极简化(minification)。通过极简化,不但缩小了javascript文件的尺寸,以加快传输速度,减小带宽费用,也加快了浏览器的解析速度。这是因为一方面小的文件尺寸解析起来更快,另一方面变量名的极简化也使得解析速度加快。
事实上,dojo的build系统不仅用来build基于dojo的应用程序,也可以用来build/deploy基于其它Javascript框架的应用。
Dojo build系统概览
Dojo的build系统的主要工作是,从指定的build profile文件读取配置,特别是要build的target,自动分析文件之间的依赖,将逻辑上属于同一个layer,但物理上分散的文件整合到一个javascript文件中(根据profile的指示),再对这些layer文件做极简化。最后,它还将未处理的源文件拷贝到指定的输出文件夹,以防止万一出现功能模块无法在layer中找到的情况。此外还可以通过build系统指定加载器(普通加载和cross-domain加载),指定css的选择器实现等功能。
构建系统本身需要:
- dojo SDK包
- Java运行时环境
- build profile,一个javascript文件
- 待build的应用程序代码
构建系统本身位于dojo/util/buildscripts文件夹下。在windows下可以通过运行build.bat来试运行一下。它会立即输出:
因为没有指定任何选项,特别是没有指定build profile,所以build系统无法工作,打印出命令提示出来。
关于build的选项,可以通过文件\util\buildscripts\jslib\buildUtil.js里进一步研究。
指定profile后再次运行build,这次会有:
release: Optimizing (shrinksafe) file: ../../release/edward/dojo/../../../../edward/front/release/e
dward.js
release: Files baked into this build:
dojo.js:
./jslib/dojoGuardStart.jsfrag
./../../dojo/_base/_loader/bootstrap.js
./../../dojo/_base/_loader/loader.js
./../../dojo/_base/_loader/hostenv_browser.js
./../../release/edward/dojo/_base/lang.js
./../../release/edward/dojo/_base/array.js
./../../release/edward/dojo/_base/declare.js
./../../release/edward/dojo/_base/connect.js
输出的最后告诉我们生成了哪些layer文件,这些layer文件中又包含了哪些内容。最后,它告诉你此次构建花了多少时间,输出文件的位置在哪。
现在来看看build profile
build profile
build profile是驱动构建系统运行的脚本文件。这个文件定义了一个中dependencies的字面量对象。这里要注意它与其它语言的构建系统文档不一样的地方是,它是一个可以运行的Javascript文件,因此遵守Javascript语法。也即,在定义对象时,出现在’:'右边的要么是字符串常量,要么是已经定义且赋值的Javascript变量(当然没必要这样做)。如果你的本意是要使用一个字符串常量,但却忘记加上引号,那么这个字符串会被当成一个变量被求值!!
build profile的语法元素主要有三类:
构建指示
通常我们在最开始的地方放置构建指示。凡是在文件buildUtils.js中列出的那些选项,都可以写在这一段。你也可以不在这个文件中指定,而在调用build.bat时,通过命令行指定。尚不清楚如果在命令行和profile中都指定了同一个选项,何者优先级高。下面是一个例子:
dependencies = {
//stripConsole : 'all',
loader : 'xdomain',
copyTests : false,
localeList : 'en-us',
layers : [
{
},
],
prefixes : [
["dijit", "../dijit"],
]
}
例子中,layers和prefixes为空,接下来研究这两项。
layers
layers用来告诉构建系统要将哪些文件打包进哪些layer文件。由于可能有多个layer,因此layers实际上是一个由多个对象构成的数组。它的每个对象具有这样一些属性:
name,该layer的名字,它有两层意思。其一,它是要生的layer文件的文件路径和文件名。其二,在profile中用来引用这一layer对象的标识符。注意dojo的官方文档中长期一来存在着一个错误,即文档中它通过resourceName(后面将要讲到)来引用一个layer,而实际上这种说法是错误的。这一点,可以从dojo自己提供的example profile中得到验证(参见standard.profile.js中layerDependencies的引用)。基于第一层意思,因此我们可以将其指定到任何可以访问到的位置。
resourceName,这个名字是我们在dojo.provide和dojo.require中要使用的名字。
discard,取值为true或者false(不带引号)。它的作用是当与layerDependencies结合时,可以从build输出中排除掉某些javascript及其生成文件。比如如果mylayer.js使用到了dijit中的很多文件,但由于我们将要采用CDN方式来布署dojo工具包(后面再讲CDN方式布署dojo),所以并不需要自己构建的dijit,更不需要将这些dijit包含到mylayer.js中来。这时就要先定义dijit layer,再将dijit layer的discard属性定义为true。
dependencies:要将哪些javascript文件整合进本layer。下面我们来看一个例子:
1: layers : [
2: {
3: name : "../dijit.js",
4: resourceName : "dijit.dijit",
5: discard : true,
6: dependencies : ["dijit.dijit"]
7: },
8: {
9: name : ../release/myApp.js",
10: resourceName : "myApp",
11: layerDependencies : ["../dijit.js"],
12: dependencies : [
13: "myApp.base"
14: ]
15: }
16: ],
注意第4行的resource name和第6行的dependencies。如果稍微有一点confuse的话,要记住在dijit文件夹下,实际上是存在一个叫做dijit.js的文件,它包含了大部分常用的dijit部件。这里也给出了一个提示,即如果你要将很多很多Javascript文件整合进一个layer文件,并不需要将其全部加入到profile中,也可以采用在另一个javascript文件中包含这些文件,再在profile中只引入这个总的包含文件即可,这样做的好处是减小了profile的大小。dojo的构建系统会根据dojo.require的提示来解析所有的依赖和传递依赖。注意,在dojo 1.6及未来的版本中,这个依赖除了由dojo.require定义之外,还可能由define函数来定义(define函数是dojo 1.6引进的关于AMD loader的实现的一部分)。这一点目前并未体现在其文档中。
再看第11行,这一行提示构建系统,如果本layer有依赖到dijit.dijit里定义的resource,这些resource本身已通过layer “../dijit.js”加载,所以无需包含在本layer中。这一声明对减小myApp.js这一layer的大小是很重要的。
最后,请注意在resourceName和dependencies中定义的那些字符串,都是点分隔的。其中在点前面的部分被称作前缀。构建系统通过前缀(prefix)来寻找构建的源文件位置。
prefix
prefixes : [
// the system knows where to find the "dojo/" directory, but we
// need to tell it about everything else. Directories listed here
// are, at a minimum, copied to the build directory.
["myApp", ../myApp/src"],
["dijit", "../dijit"],
]
第5行定义了myApp的源文件位置。因此前面layer定义中,myApp.base所指向的文件base.js将从/myApp/src文件夹下寻找。
注意构建系统只知道dojo的位置,并不知道dojox和dijit的位置,因此这里也必须为它们指定路径。
构建系统的优化
在我的机器上,一个空白的dojo工程(即基本上没有自定义的模块源文件)构建最长可以花到4~5分钟。这要归功于dojo有很多很多小文件,以及构建时先要删除前面构建的文件,然后再将整个dojo文件夹的内容拷贝一次。如果你只是借用dojo的构建系统来构建自己的工程,而并不使用任何dojo的功能,应该可以在保留dojo的文件夹结构的前提下,清除掉dojo,dijit,和dojox文件夹下的内容,以加快构建速度。此外,即使使用了dojo,但如果没有用到dojox的功能,也可以将这个文件夹删除掉。单是删除这个文件夹就会加快不少速度。
第二,dojo允许指定构建的layer。在开发过程中可以将这个参数写在profile中。即使是指定了只构建custom layer,构建系统还是会拷贝dojo的文件—似乎省略的只是整合成layer及minify的过程。
部署的优化
dojo有一个激动人心的特性,就是它的加载器允许xDomain加载。简单地说,dojo的普通加载器使用了xhrGet来加载javascript脚本,再通过eval之类的方式激活javascript中的对象,或者调用document.write,将其写入文档,由浏览器来解析生成对象。普通加载器是默认的加载器,但它有一些问题。其一是,它无法利用浏览器多线程下载文件的能力;其二是不允许(xhrGet不允许)跨域加载脚本;其三是,在文档加载完成以后,它无法加载新的脚本,因为此时document.write不可用。尽管从安全角度看,浏览器禁止xhrGet跨域访问数据有其理由,但跨域加载脚本却有着绝对合理的理由。脚本文件都是静态文件,为了性能优化的考虑,大型网站常常使用专门的服务器和域名来host这些文件。比如一个网站可能使用myapp.example.com来host应用程序,而使用images.static.example.com和js.static.example.com来host这些静态文件。进一步地,为了在全球都能得到同样快速的服务响应,大型网站可能使用CDN来host这些文件,这样也使得javascript文件可能不跟应用程序文件在同一服务器上。
xDomain的加载方式解决了上述问题,更重要地是,它使用利用CDN加载成为可能。xDomain的加载方式是在文档的DOM模型构建完成之后,向DOM的文件头(head和body此时可以)插入<script>标签,这样触发浏览器自己去加载该资源。xDomain加载器需要自己照管的,就是文件依赖的解决,以及在所有资源可用之后,再调用用户指定的回调函数,从而启动用户的应用。
如果要构建一个支持xdomain加载的应用,需要在命令行或者profile中指定’loader:xdomain’属性。这样构建出来的layer文件,以及未被包入layer的文件,会多一个.xd的后缀。比如myApp.js支持xdomain加载时,构建的输出就是myApp.xd.js。当然,这两个文件的内容也是不同的。后者多了对xdomain加载的支持。
在部署的应用程序中使用xdomain加载有两种方式,一种是直接引用带.xd的dojo.xd.js;另一种是通过dojoConfig来指定。这样会导致dojo加载器自动寻找文件的xd版本。比如在使用xdomain加载的情况下,dojo.require(“myApp.base “)会导致加载文件myApp/base.xd.js。
加载器只知道在dojo.xd.js所在的目录,以及这一目录同级的目录中支寻找javascript模块。在使用CDN的情况下,显然此时加载器无法寻找到用户自定义的、部署在自己domain内的机器上的模块。此时需要通过dojoConfig的modulePaths或者registerModulePath来指定模块搜索路径。
1: dojo.registerModulePath("myApp", "http://www.example.com/myApp");
dojo文档里没有提到在CDN情况下如何指定这个路径,它的示例都采用相对路径。不过实验证明可以使用上例所示的绝路径。注意,dojo文档里提到,这个路径绝对不能以’/'结尾,因为dojo会自己(不加判断地)附加一个上去。
最后要注意,当使用CDN部署和xdomain加载时,你的自定义模块也应该是xd的。而如果你使用非xd的dojo来加载部署在其它机器上的模块是,你多半会得到浏览器抛出的不能跨域访问的错误—因为dojo在底层使用了xhrGet(不知道dojo 1.7全面采用AMD加载后,这一实现是否被改写)。
另一个常见,但却是false alarm的case是,在使用xdomain加载的情况下,如果使用dojo来声明一个类,但是关于其路径,provide和declare等不对应,此时会出现文件加载成功(已经写入到HTML文件中的头部),但抛出cann’t load xdomain resource错误。这个与xdomain关系不大了,应该仔细看看javascript的写法。
FAQ
Q: 在profile中将log级别设置为log : ‘logger.TRACE’,但却没有任何输出?
A:默认地build系统的日志级别就是最详细一级。注意profile是Javascript,所以问题中的赋值实际上是给log设定了一个字符串变量,而util/buildScripts/jslib/logger.js期待一个整数值,logger.TRACE是它的一个常量。其它取值是logger.INFO, logger.WARN, logger.ERROR。
Q:在一次构建中,假设target是layer.js。已指定是xdomain构建,但仅生成layer.js,没有生成layer.xd.js?
A:如果在profile中指定了layerDependencise,就会出现这样的情况。但遗憾地是,屏幕输出仍会令人困惑地打印出已生成layer.xd.js文件。