Build your Dojo-based Javascript Application and deployed via CDN

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',monospace; direction:ltr; border-top-style:none; color:black; font-size:8pt; border-left-style:none; overflow:visible; padding-top:0px">    layers : [

        {

        },monospace; direction:ltr; border-top-style:none; color:black; font-size:8pt; border-left-style:none; overflow:visible; padding-top:0px">    ],monospace; direction:ltr; border-top-style:none; color:black; font-size:8pt; border-left-style:none; overflow:visible; padding-top:0px">    prefixes : [

    ["dijit","../dijit"],monospace; direction:ltr; border-top-style:none; color:black; font-size:8pt; border-left-style:none; overflow:visible; padding-top:0px">    ]

}

例子中，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文件。