You really do have to do your own custom packaging of dojo in order to get the snappy performance we all want. Generally, what we have done is this:

1.) Added a dojo-build directory to our project, which holds a src version of dojo untarred.
2.) Have two header files, one for dojo-dev, and one for dojo-prod. This allows us to have the standard dojo-release for our development purposes (this file holds the link lines, djconfig, etc) and one for production, which just links to our custom dojo base file, and our custom dijit file. Our build process scrapes out the dojo.require's from our tpl templates. This way, you only have two requests for all of dojo, and your own widgetry. We also scrape out the addModule line, as that is not needed in production.
3.) The profile file as shown above lists all of the dijits , and our own widgets, that are called DIRECTLY. This is important to manage, and should be thought about whenever you add / remove a dijit or custom widget from your app. The prefixes are just dijit, and our own module. Try to embed all of your requires for each custom widget within it's Widget.js file.

For php folk, the concept of a build is pretty foreign. But eventually, as your app gets bigger, you need something like ant or phing in order to build, and deploy, your app. The dojo build process just hooks right into whatever build script you use. We fire the command line build.sh with parameters telling it where our profile file, and deployment dir (right in our js dir) should be.

Like most people, I took the tundra theme, and used it as a base for our own theme. I wanted the theme to be completely seperate from the dojo directory, in our css dir. At the top of tundra.css, you will see a relative link to the base dijit.css file. This bit us hard after our custom build. If you move your theme dir outside the dojo area, a relative link will break in a custom build (since the dojo-1.0.1 dir is not present in the production dist), but firebug cant catch that the dijit.css core file was 404. All dijits were messed up until we changed this. Our production dojo_head.tpl file links to the production custom build's dijit.css, and then our own theme css. e.g.:

@import url("js/dojo-release/dojo/dijit/themes/dijit.css");
@import url("css/themes/gq/gqdojo.css");

I've seen a lot of discussion on the boards about how one should use the custom build after you've created a layer file with additional classes compiled in. For a local Dojo build (not XDomain) as listed above, I think the correct HTML code to reference the layers is:

Is this correct? The important thing to note is that you have to reference both the dojo.js and mydojo.js files, I think.

In order to try and fully understand the dojo build profile parameters, I have attempted to describe them in the following table. If there are errors or omissions in what I have posted, please let me know and I will be happy to correct them.

For source code at version 1.0.2, this table assumes a minimal build command of the form:

./build.sh profile="yourProfileFilenameHere" action="release" version="1.0.2"

where you run the command from the path:

/dojo-release-1.0.2-src/util/buildscripts

Note that the entire built distribution directory tree needs to be included in your webapp, not just the built dojo.js and file described in the name build parameter below.

Note that it was not possible to fit the table within the fixed width of the light colored posting area. Simply select the table text to see it clearly.

Build Parameter		Function		Optional			If not provided, then:

dependencies		Container for layers	N if layers are provided.	Generates dojo.js base library.

layers			list of dojo libraries	N if dependencies are provided.	N/A
			to be built, where 
			each library is 
			stored in a separate 
			file			

name			path where layer is	N if dependencies are provided.	N/A
			to be stored. This
			path is relative to 
			the release/dojo/dojo 
			directory. Both a
			compressed (<name>.js) 
			and an uncompressed 
			(<name>.js.uncompressed.js) 
			module file will be 
			built. Name may only 
			contain a single dot and it
			must be just before the js
			file extension.

resourceName		string defining a	Y				No dojo.provide is included
			library; causes a 					in generated build file.
			dojo.provide to be 
			placed in the generated 
			build file where 
			resourceName is the 
			name you choose to 
			define your custom 
			built library. This
			name defines the
			namespace for the
			module to be 
			generated in the 
			given layer. (broken
			in versions 0.9 to 
			1.0.2 - see bug 5688)
							
layerDependencies	list of prebuilt dojo	Y				Assumes a dependency on dojo.js. 
			or custom libraries 					Generates dojo.js base library
			that libraries to be 					by default and copies it into the 
			generated depend upon					release directory.
						
dependencies		list of dojo widgets 	Y				No library beyond base libraries 
			to be built (baked) 					will be generated.
			into the generated 
			layer file defined by 
			the “name” parameter; 
			the dependencies are 
			those widgets that you 
			will request in your 
			web page(s) through 
			dojo.require statements

prefixes		list of dojo or custom 	Y				Modules are not copied to 
			directory paths where 					release directory.
			individual dojo modules 
			(for example individual 
			widget source files) 
			are stored. A module
			may reference other
			namespaces through
			dojo.require() 
			statements. The contents 
			of these directories are 
			copied to the release 
			directory during the 
			build sans any modules 
			included in the generated 
			base libraries or 
			libraries defined by the 
			“name” parameter

Hi.
Under the header "Creating a Custom Profile", the path name src/buildscripts/profiles should read utils/buildscripts/profiles.

--EDIT---
I found it, (i downloaded the src file) thanks anyway

I don't have buildscipts directory and build.sh. where I can find it?
Thanks

You might want to have your own modules outside dojo-hierarchy, so that they're not parallel to dojo, dijit and dojox, but instead one level up. To do this properly there are few things to remember. First, you probably want keep your modules totally separate from Dojo's, so let's set it to build your layer files into your module directory. When you change your layer-name to point to your module directory, layer-files (also uncompressed.js) and localization resources (nls-directory) will be copied there. See the following sample profile:

Second, to use this from your pages, you need to include and set stuff in the correct order:

1. dojo.js and djconfig - load the basic Dojo functionality
2. registerModulePath - set the custom module namespace correctly
3. my-all.js - load the layer file
4. require - load the classes normally, if the layer wasn't found

See the following snippet:

If you wish to have a custom copyright included in the layer, you must add a copyrightFile to the layer specification. See the file util/layer.profile.js for an example. Note that this is the only copyright included in the layer, so if the layer bunches dojo dependencies with 'explosive' dependencies, then both copyrights would need to be included in the file specified by the copyrightFile property.

how much does it compress
i made a custom build but the compression was not so good.
can you tell what level of compression does it allow .......
my custom build for dojo 1.1.1 has a size of 9.04 mb ......... using optimize=packer
is there any option to further compress the file

Regards,
Prajot

Is there a shorthanded way to include all dependent files into a single JS file without explicitly listing them in the "dependencies" section?

To compress @imported css files into one file, you can also use the following option:

cssOptimize=comments.keepLines

Thanks for this info Pete!

This piece of news was missing from the article: Dojo 1.1 supports the following new build options:

• cssOptimize: cssOptimize=comments will strip comments and whitespace from CSS files and also inline any CSS files that are referenced by @import rules.
• cssImportIgnore: cssImportIgnore takes a comma separated list of file paths. These file names will not be inlined during the cssOptimize step. The file paths used in cssImportIgnore should match the file paths used in the @import calls.
• buildLayers: After you do a full build, if you just want to rebuild a layer or set of layers, you can pass buildLayers=[comma separated list of layer names], and just those layers will be rebuilt. If you have problems with the option, try doing a full build and trying again.
• symbol: symbol=short and symbol=long will inject function names for all anonymous functions, making it easier to do some debugging in environments like IE.
• There are new build options associated with multiversion support. See the Multiversion Book Page for more information.
• Rhino builds: You can now do custom builds that target Rhino as the host environment, instead of the browser. See the example build file to see how to specify the Rhino host environment.

Smaller build system changes also in Dojo 1.2. See Dojo 1.2 Loader and Build System highlights:

The final example in the slides demonstrates how you can create a 5.5 KB (gzipped) dojo.js file and dynamically load it after the page loads, so if your site uses progressive enhancement, your up-front Dojo cost can be zero bytes, and just load as little as possible for the functionality that you use.
...
There is a new build option for stripping out console method calls. stripConsole=normal strips out all console.* calls except console.error and console.warn. stripConsole=all strips all console.* calls.

Let me say that custom builds architecture and implementation are beautiful and absolutely great from the engineering point!

In particular, the use of full-blown parsing (Rhino) for compression (instead of regexes) makes it a really solid solution.

I would like the clarification on how layer dependencies are tracked and aggregated in current implementation. I see that build process tracks at least MOST module dependencies inside dojo tree for their aggregation into layer, so the number of requests are reduced dramatically and performance is high. But does layer reliably track and include ALL dependencies? Is that possible that some required module is not included into layer despite layer depends on that module -- lets call it "layer dependency leak".

In other words, if widgetry uses only, say, 300KB layer, nls bundles, and dofo.js, is it safe to remove the unused rest of ~3MB of dojo library leaving only that layer, nls and dojo.js? (At production site, not development, of course.)

Since layer is supposed to live in (be complemented with) the rest of the dojo library, the dependency leak in a layer is not critical - leaked module is readily available in dojo library. Thus, the rest of the library acts like a safety net against layer dependency leaks. But if layer dependency tracking&aggregation is complete and reliable (as compression is), such safety net is not needed and rest of the library can be removed.

My working assumption is that it is not safe to remove rest of the library.

It would be nice to hear expert opinion on this.

I did a custom dojo build on the 1.3 src and loaded both js in my jsp page

dojo.js
mydojo.js

it works fine, but in IE6 it shows Access is denied javascript error.
Firefox error console doesn't show any errors

anyone know of a fix for this? thanks~

the profile i used...

dependencies ={
layers: [
{
name: "mydojo.js",
dependencies: [
"dojox.grid.DataGrid",
"dojo.data.ItemFileReadStore"
]
}
],
prefixes: [
[ "dijit", "../dijit" ],
[ "dojox", "../dojox" ]
]
};

NOTE:
I tried doing a custom build with 1.2.3 src with the same exact profile and it works fine with NO 'access is denied' javascript error.

Still few more notes about minimizing Dojo builds... There's a video over DojoCampus Dojo Build 301: Compacting your build that demonstrates briefly howto build minimized Dojo package. There have been some changes from 1.2 to 1.3 that are best explained by this snippet from build_mini:

build_mini.sh is available in the official Dojo release 1.2!

If you are using 1.2.x, use build_mini.sh from the official repository:

In Dojo 1.3 and higher, build_mini.sh was removed and replaced with:

• build parameters mini="true" and copyTests="false"
• a post-build script named clean_release.sh (also available in 1.2), which does the same work as build_mini, though requires you run a standard build prior.

A port of the original mini script to work with 1.2.3 is available here and was contributed by Sudheer.