Dojo Toolkit Slim Build

Hi everyone 🙂

Well if you ended up here I guess you have been, like me, looking all over the dojo docs, and even the whole internet, to find how to build a small custom dojo build.
I needed that myself for my current project

First of all, my own background is from traditional IT,  down to the machine,  with compiled languages. So when I hear “build” I understand to get a bunch of files and put them in one unique, nice, compressed, easy to transfer, fast to run, almost magic file.

But that’s not what it means with dojo 😦 I guess that coming from the web, where you have files and requests online all the time, the standard is more to have all your mess on a server somewhere and not worry about it. There fore a “build” is only an optimisation, a way to reduce the mess… that ultimately still remains around. And that’s what happens when you do a standard build with dojo, all files are copied anyway, just in case something would be missing…

However, when I am building a web-app, I am also thinking of what if :
• my external network goes down, and I still need to access all my resources.
• I want to port it to another platform
• I want to be able to have everything offline on a USB disk and I need it to work even if I am not connected
• etc.

And for all these reasons, what I want is only one “mydojobuild.js” file. But sadly very few docs on the web try to achieve that goal.

After a few days of trying a bit everything, here is what I ended up with :
1. a built “dojo.js”
2. a few “nls/nls_<locale>.js”

🙂

First a few things that are quite usefu to know, but it took me some time to understand :
• The command line options for the build can also be included in the profile file. Pretty useful if you want to script the whole process like I do.
• Even though your profile specifies only one layer to be built, the dojo build system will always build at least a dojo/dojo.js (and usually also a dijit/dijit.js and a dojox/dojox.js I think – even if you don’t care about it) anyway. So if you want all your dependencies in ~*one file*~, you have to put them in dojo/dojo.js.

And here is how my build profile looks like :

//http://docs.dojocampus.org/build/buildScript
dependencies = {
    stripConsole: "normal",
    action: "release",
    mini: true,
    optimize: "shrinksafe",
    layerOptimize: "shrinksafe",
    releaseName: "my_dojo_build",
    // list of locales we want to expose
    localeList: "en-gb,en-us,fr-fr",
    layers: [
    //Custom build of the mandatory dojo.js layer
    {
        name: "dojo.js",
        customBase: true,
        dependencies: [
            "dojo.i18n",
            "dijit.Dialog",
            "dijit.form.Form",
            "dijit.form.Button",
            "dijit.form.ValidationTextBox",
        ]
    }],
    prefixes: [
        [ "dijit", "../dijit" ],
        ["dojox", "../dojox"]
    ]
}

Pretty small and maintainable 🙂

I build it with :

cd dojo/util/buildscripts && \
    sh build.sh profileFile="path_to_my_profile" log=WARN version=1.6.1 

Then I only need to get the dojo/dojo.js file, as well as the dojo/nls/dojo_* for localization.
And because, believe it or not, I test my application before deploying it ;), so if I miss a dependency from dojo, I will see it and fix the build profile. I don’t need all the files that the dojo build put around (but I didn’t find any option to disable this step in the build yet). Ah and just in case you are wondering, yes localization files are separated and will remain out of the dojo.js because if I am speaking french I don’t want to load all languages at runtime…

I am now pretty happy with my solution, as I can run the build and extract what I need with a simple waf script, in the configure method, such as:

#finding dojo mandatory layer
dojobaselayer = dojobuildnode.find_node("dojo/dojo.js")
if dojorelnode is None :
    conf.fatal("dojo/dojo.js mandatory base layer was not found " + \
               "in build directory. Cannot continue.")
dojobaselayer_uc = dojobuildnode.find_node("dojo/dojo.js.uncompressed.js")
if dojobaselayer_uc is None : 
    conf.fatal("dojo/dojo.js.uncompressed.js base layer was not found " + \
               "in build directory. Cannot continue.")

# Finding the scripts folder where to put build results
scriptsnode = conf.path.find_dir('htdocs/scripts')
if scriptsnode is None : 
    conf.fatal("htdocs/scripts/ subfolder was not found. Cannot continue.")

#copying mandatory dojo layer
conf.start_msg("Extracting Dojo built layer" )
shutil.copy(dojobaselayer.abspath(),scriptsnode.abspath())
conf.end_msg( scriptsnode.find_node(
    os.path.basename(dojobaselayer.abspath())
).relpath())
conf.start_msg("Extracting Dojo built layer - uncompressed" )
shutil.copy(dojobaselayer_uc.abspath(),scriptsnode.abspath())
conf.end_msg( scriptsnode.find_node(
    os.path.basename(dojobaselayer_uc.abspath())
).relpath())

#extracting localization resources
dojonls = dojobuildnode.find_node("dojo/nls")
if dojonls is None : 
    conf.fatal("dojo/nls for mandatory base layer was not found " + \
               "in build directory. Cannot continue.")
conf.start_msg( "Extracting Localization resources ")
scriptsdnlsnode = scriptsnode.make_node("nls")
scriptsdnlsnode.mkdir()

#copying localization resources from the build
#excluding default copied file by dojo build process
for fname in dojonls.ant_glob("dojo_*") :
    shutil.copy( fname.abspath(), scriptsdnlsnode.abspath())
conf.end_msg( scriptsdnlsnode.relpath() )

DISCLAIMER : I cannot guarantee that the script up there will work. It’s python, and I had to re-indent it to fit in here… So you might have some quick easy syntax fix to do if you copy it.

Well that’s it for now. Dojo is pretty slim and I am happy as it s not so heavy to move around any more.

Two things I still need to investigate:
1. How to embed dijit themes in a build. That should be possible, as I saw some reference one the web, but no example so far… So if you have a clue, or any question, just let me know 😉
2. How to rename the dojo.js file and the matching pathname in js code. That should be possible with the scopeMap option, that can map dojo.* to mycustomname.* However I ll need a lot more tests to make that work properly I believe

And now you can go explain to your dojo build how to go on diet 😉