Creating a Custom Distribution

Prerequisites

You need the following installed on your computer to run Dojo's build system:

Creating a Custom Profile

Creating your own Dojo distribution allows you to take advantage of the build system. In the src/buildscripts/profiles directory, you will create a profile build file called foo.profile.js like this:

var dependencies = [ 

	"dojo.io.*",

	"dojo.event.*",

	"dojo.xml.*",

	"dojo.graphics.*",

	"dojo.io.BrowserIO",

	"dojo.widgets.*",

	"dojo.widgets.Button",

];



load("getDependencyList.js");

This should list all the resources you are directly using.

Including Non-Dojo Resources

If you want to include your own code into a build you need to make

custom resource for your code, ie,

dojo.provide("mycompany.widget.SomethingCool"), then define the profile file like this:

var dependencies = [

         "dojo.widget.*",

         "dojo.io.*",

         "dojo.event.*"

         "mycompany.widget.SomethingCool"

];



dependencies.prefixes = [

   ["mycompany", "../mycompany"]

];



load("getDependencyList.js");

The "../mycompany" path in the dependencies.prefixes is relative to dojo.js. It operates the same as what you use for dojo.registerModulePath() (or dojo.setModulePrefix() in 0.3.1 or earlier versions).

Exclude Interning Resources from the Build

(available since Dojo 0.4.1)

If you subclass a Dojo widget in your code and don't make use of the original widget standalone (directly), then you may not want to include the original template file for that particular widget at all. Or you have a custom css file for a Dojo widget, and you don't want to include the original one, then you can specify internSkipList in your profile.

Let's assume you want to have a built Dojo with Editor2 in it, but you do not want to include the default EditorToolbar.html as you already have a customized one, then you can use this profile:

var dependencies = [

	"dojo.widget.Editor2"

];



dependencies.internSkipList = [

	"dojo.widget:templates/EditorToolbar.html"

];



load("getDependencyList.js");

Notice the "dojo.widget:" prefix to the actual path for EditorToolbar.html: it is used to avoid confliction of template file paths among different namespaces.

Running The Build

After specifying a profile file as shown above that statically specifies the resources you want to include, and saving it as /buildscripts/profiles/foo.profile.js, run Ant and specify the profile name as a parameter. For example, from the buildscripts directory:

ant -Dprofile=foo clean release

Some additional build options:

-DprofileFile=/path/to/myProfile.profile.js

You can use this instead of -Dprofile to specify a profile file that is not in the dojo/buildscripts/profiles folder.

intern-strings

If widgets that are built into dojo.js specify templatePath and/or templateCssPath, the intern-strings ant target will intern the HTML/CSS into dojo.js so that additional XMLHttpRequests are not needed to load the HTML and CSS later.

Another build example:

ant -DprofileFile=/path/to/myProfile.profile.js clean release intern-strings
strip-resource-comments

Available in Dojo 0.4.2+. This task will remove the comments from the files in src/. This helps the download size of modules that are not part of dojo.js and are loaded via dojo.require().

Example (for Dojo 0.4.2+):

ant -Dprofile=ajax clean release intern-strings strip-resource-comments

For Dojo 0.4.3+, it is possible to run all the files through the Dojo compressor instead of just stripping comments. To do that, specify -Dstrip_and_compress=true in the ant command:

ant -Dprofile=ajax -Dstrip_and_compress=true clean release intern-strings strip-resource-comments

After the build

Running the build generates a release directory and all that is needed to use Dojo with your application. You will distribute the contents of the release directory with your application.

Including Dojo from HTML source files

Once your resources are specified, to include Dojo from the source tree, you simply include the following tag in your html source:

Additionally, you will need to specify the resources to load as you need them loaded. I do this in a separate script file to initialize Dojo. For example, if you have code that required the Dojo event system, you would add the command:

dojo.require("dojo.event.Event");

Note however, that you should still distribute the release/dojo/src directory in your distribution. Although the JavaScript?, css, and html files have been merged into dojo.js, there are still image files that are being accessed from the src/ directory.

Supporting dojo.require("foo.baz.*")

If you want to say something like dojo.require("foo.baz.*"), to include all the resources in the acme/foo directory, then you will need to create file called 

__package__.js

in the foo/baz directory, with the following format:

dojo.kwCompoundRequire({

	common: ["foo.baz.resource1", 

		"foo.baz.resource2"] // a generic dependency

});



dojo.provide("foo.baz.*");

Definitions

kwCompoundRequire
passes an object of modules, grouped by host environment
provide
Conclude with the name of the module that is now considered loaded.

NOTE: For Dojo 0.3+, dojo.hostenv.conditionalLoadModule() has been replaced with dojo.kwCompoundRequire() and dojo.hostenv.moduleLoaded() has been replaced with dojo.provide(). To use the old methods with Dojo 0.3+, please use a compatibility package.

A Longer Example

Here's the contents of dojo/src/foo/__package__.js:

dojo.kwCompoundRequire({

    common: ["dojo.foo.Foo", "dojo.foo.Bar"],

    browser: ["dojo.foo.Baz"]

});



dojo.provide("dojo.foo.*");

This set of definitions says that when someone writes dojo.require("dojo.foo.*"); from within a browser, Foo.js, Bar.js, and Baz.js will get included from this directory. When run from the command line, only Foo.js and Bar.js will get included.