From Learn About the Ext JavaScript Library

Introduction

There are several options available for building your own versions of Ext into minified output files. Why is this important?

• You can include only the files you need, making for a smaller output file for deployment.
• You can minify the source, also an important deployment step.
• If you are a support subscriber and have SVN access, you can create your own intermediate development builds for testing purposes, or work with the latest Ext features and bug fixes between official releases.
• You can optionally automate the build process, and even integrate it into your overall automated application build process if you have one (e.g., via Ant).

The three main build methods that will be covered are:

• The online Build Your Own utility. This is most useful for one-off builds or for easily creating a custom build with no installation or setup required.
• The Java-based, command line Ext SVN Builder. This is recommended for Mac and Unix users for easy, automated batch building from SVN.
• Our JS Builder application. Recommended for Windows users, as it offers the most flexibility and many advantages over the other methods.

Build Your Own Online

Anyone can create a custom Ext build themselves via our simple, hosted build tool. This is a great option for quickly and easily building your own custom Ext file. However, it does not include the resources or examples, and can only build from the current release version of Ext. This tool is primarily intended for producing output files optimized for deployment into a production application. For more flexible options, or to build from development branches of Ext, see the other sections following this one.

Build Steps

1. Navigate to http://extjs.com/products/extjs/build/
2. Choose your preferred library and click Next.
   If you aren't sure what to choose and/or do not use the other libraries listed, just leave the default (Ext Stand-alone). For more information about why you might choose a different base library, see this FAQ section.
3. Select all of the component packages that you need and click Build It!.
   Note that required dependencies will be included automatically (no need to select them yourself), but optional dependencies must be selected manually if you want to include them. The builder will automatically ensure that each source file is only packaged once into the output build file, even if included as a dependency multiple times.

Online Builder Pros & Cons

Pros	Cons
Simple to use Fast! Built-in dependency checking Nothing to install or maintain yourself	Manual build process, cannot be automated Web access required to run it Limited flexibility in what can be built No option for an uncompressed debug build No ability to include non-Ext files Current release version of Ext only — no ability to build from development branches
Bottom Line
For one-off builds, it's a quick and easy option with no setup required. For long-term, repeatable builds, or for greater flexibility, you will probably be better off using JS Builder (if on Windows) or the Ext SVN Builder (on Mac/Unix).

Ext SVN Builder

This is a handy little Java-based utility that lets you build the entire Ext file tree (including source, resources and examples) with a single command. However, it does not provide the flexibility to pick and choose what files to build. Because of this, its primary purpose is for SVN users to be able to pull down the latest Ext code and easily build a working test version of Ext. If you do not have SVN access, this will probably not be very useful to you, and you should check out JS Builder instead for custom building from any existing source.

Build Steps

1. Make sure you have a current version of Java installed
2. Download the Ext SVN Builder application if necessary
3. Open a console or command line window to the install folder and run:
   Unix: java -jar builder.jar -s "/your/path/to/svn/dir" -o "/your/output/dir"
   Windows: java -jar builder.jar -s "c:\your\path\to\svn\dir" -o "c:\your\output\dir"

The supported command line options are:

• -s: Path to SVN checkout directory (required)
  This should be the path to the top-level folder that contains the source, resources and examples folders.
• -o: Output path for Ext (required)
  This can be any path you want. Note that existing files will be overwritten, but files that have been removed from SVN will not be deleted. It is a good idea to build to a fresh path for final deployment.
• -d: Build a debug, non compressed version (optional)
  The output files will still have comments stripped, but the code will not be minified. This is preferred during development so that debugging is easier.

Customizing the Build Process

As mentioned in the introduction, the Ext SVN Builder is primarily intended for building the latest version of everything in SVN at any given time. However, it works by reading the .jsb files included with the Ext source. These are JS Builder project files, and include all dependencies for each project being built. While these are intended for use with JS Builder, they can technically be edited by hand if necessary to produce your own custom builds. In general, if you need this level of control over the process, using JS Builder directly, as explained in the next section, will probably better suit your needs.

Script Automation

One nice feature of using the Ext SVN Builder utility is that you can easily automate it via shell scripts (or batch files in the Windows world). That way there's no need to remember and retype your paths each time you want to build. Here's a simple example of how this could be done, but of course the scripts can be customized via the full scripting capabilities of your environment.

Unix Shell Script

This is as easy as it gets — simply save the same exact console command as shown above in the Build Steps section to a text file, then execute it as a script in the console by calling it with your scripting shell of choice. For example, if you create a text file named "build-ext-2.0" that contains this script:

java -jar builder.jar -s "/your/path/to/svn/dir" -o "/your/output/dir"

...you could execute it in the console using the Bourne Shell like so: sh build-ext-2.0

Windows Batch File

Save the following script as a batch file (e.g., "build-ext-2.0.bat") and set the path variables as needed. The path variables are necessary for proper handling of paths with spaces. The script assumes that it's being run in the same folder as builder.jar, although you could add an absolute path to that file as well to run the script from anywhere. Note that the Java path must be set explicitly because the batch file will not pick it up from the system path. Once the file is created, you can double-click it in Explorer or run it from the command line like so: build-ext-2.0

echo off
set JAVA_PATH="C:\Program Files\Java\jre1.6.0_02\bin"
set EXT_PATH="C:\SVN\Ext\branches\ext2.0"
set OUTPUT="C:\Inetpub\wwwroot\deploy\ext-2.0"
 
%JAVA_PATH%\java -jar builder.jar -s %EXT_PATH% -o %OUTPUT%

Ext SVN Builder Pros & Cons

Pros	Cons
Platform-independent Convenient for building everything from SVN Automatically generates compressed and debug builds Supports building from the SVN trunk or from development branches Can be automated via shell scripting	Requires that Java be installed Very little flexibility in what files can be built No ability to include non-Ext files in builds Slow (because it always builds all 3 complete Ext projects)
Bottom Line
On Mac/Unix, this utility is your best option. Set up your shell scripts and you'll be ready to build anytime with a single command. Windows users should consider JS Builder for ultimate power and flexibility.

JS Builder

JS Builder (or JSB) is a full-fledged application for managing the building of source files, and it's the tool that the Ext team uses internally for managing our interim development builds. It is a Windows-only .NET application, which is its main drawback for some people, but it has many advantages to the other build methods discussed above. The .jsb files included with the source code in Ext distributions and in SVN are JS Builder project files and can be opened and edited in the JSB GUI application.

JSB GUI

A complete overview on using JSB is beyond the scope of this tutorial. It can actually be used as a general-purpose build/compression tool for your own projects, and custom JS and CSS files can be included to create project-specific builds. Simply create a new project and add the files you need. There are also many options available in the Options window, as well as project-specific settings in the Project Settings and Build Settings tabs.

For now, we will just discuss what you need to know in order to effectively build Ext from source. If you haven't done so already, first download and install JSB from the JSB project site. Once that's done, you're ready to build.

Build Steps

1. The Ext source files can be installed anywhere, but the original folder structure should be unmodified.
2. Find the \src folder under the Ext \trunk (or \branches\ext2.0) and double-click on ext.jsb to launch the JSB GUI.
3. By default, everything should be set up to build just as it is for the Ext team. You may want to change the default Output Directory value under the Build Settings tab — this is the root folder under which the output files will be created.
4. Click the Build Project button (last menu button on the right) or select Build > Build Project from the menu. It should start building and you should see the output files created in the output directory.
5. Repeat the same steps for each of the three .jsb files as needed (the others are under \resources and \examples).

One additional comment about the JSB GUI — on the Build Settings tab there is a list of output files at the bottom. These are "output targets," or combined output files that contain multiple source files. These are used to create build packages specific to different functional areas within an application. You will also notice the entry for "Everything" in ext.jsb — this is the build definition for the file ext-all.js that many people use by default to include all of Ext. You can edit these output targets or add your own. This is also a great way to manage your own projects — you could combine your own JavaScript files into a single output target containing your own application code.

To use JSB to keep abreast of the latest SVN changes for testing purposes, a typical workflow might be:

• Update your local Ext source folder from SVN.
  If you have edited any files (including the .jsb files) you will have to delete or move them — SVN will not overwrite them. Note: As currently implemented, if you want to build to a custom output directory, you will have to edit that setting again each time you do this as all settings are saved in the .jsb file which gets updated from SVN. This will most likely be changed in a future version so that project settings are saved separately from the file list that defines the build.
• Back up your current Ext output folder so that you can easily roll back if needed without rebuilding the previous version.
• Open each .jsb file and build it.
• Test the new version of Ext using your new output files.

JSB Console

JSB also ships with a console version, which is quite handy for command line building. This is useful for automating builds using batch files, Ant scripts, etc. Building using JSB Console is pretty simple:

Build Steps

1. Open a Windows command prompt.
2. Go to the JSB install directory (or add it to your system path).
3. Run JSBuildConsole.exe using the /path option to specify the path to the .jsb file and the /output option to specify the output path (it will use the default output path from the .jsb file if you leave this off). Run JSBuildConsole /? for a detailed explanation of all options available. Example:
   JSBuildConsole /path=c:\svn\ext\branches\ext2.0\src\ext.jsb /output=c:\inetpub\wwwroot\ext\deploy
4. Repeat for each .jsb file that you want to build as needed.

Script Automation

As with the Ext SVN Builder earlier, using the console version of JSB via batch scripts will usually be the way to go so that you don't have to memorize or retype the commands to run it. Simply save the following script as a batch file (e.g., "build-ext-2.0.bat") and set the path variables as needed. The path variables are necessary for proper handling of paths with spaces. Once the file is created, you can double-click it in Explorer or run it from the command line like so: build-ext-2.0. This example batch file will build all three Ext projects with verbose logging and will delete existing output files prior to building.

echo off
set JSB="C:\JS Builder\JSBuildConsole.exe"
set EXT_PATH="C:\SVN\Ext\branches\ext2.0"
set OUTPUT="C:\Inetpub\wwwroot\deploy\ext-2.0"
 
set SRC=%EXT_PATH%\src\ext.jsb
set RESOURCES=%EXT_PATH%\resources\resources.jsb
set EXAMPLES=%EXT_PATH%\examples\examples.jsb
 
%JSB% /path=%SRC% /output=%OUTPUT% /clean /verbose
%JSB% /path=%RESOURCES% /output=%OUTPUT%\resources /clean /verbose
%JSB% /path=%EXAMPLES% /output=%OUTPUT%\examples  /clean /verbose

JS Builder Pros & Cons

Pros	Cons
Graphical UI for managing files Complete flexibility in what can be built Can define custom builds and build targets Optionally output uncompressed debug builds Non-Ext files or projects can be used with JSB Can be automated using the console version	Windows only, requires .NET 2.0 Managing the output paths (in the GUI) is currently non-optimal
Bottom Line
On Windows, the combination of the JSB GUI and console versions is hard to beat. For Mac/Unix users, the Ext SVN Builder is your best alternative.

Deployment

During the development and testing phases of your project, you will want to deploy uncompressed JS files to support debugging. When you encounter errors in minimized JS files, it is nearly impossible to step through, and error messages are not always accurate or helpful. The online builder does not provide any way to output uncompressed build files. The Ext SVN Builder will optionally output the standard ext-all-debug.js, which you should use by default in most cases. If you want to build your own custom output files, and you need uncompressed debug versions, setting up custom build targets in the JSB GUI is pretty much your only option.

Generally speaking, you should stick to ext-all-debug.js during development as the simplest approach, then define your custom, compressed output builds for final deployment purposes.

A Note Regarding JS Compression

There are many tools available for compressing and/or obfuscating JavaScript code. JS Builder uses JSMin (which is a fairly conservative compression scheme with no obfuscation), and for development purposes, this usually does not matter. However, for production deployment, you may decide to further optimize your files by running them through an additional layer of compression and/or obfuscation. Whether or not the benefit would justify the effort depends on several variables, but it might be worth trying different options and comparing the output to see what might work best for you. For example, you could build a single uncompressed build target containing your entire application using JSB, then run it through ShrinkSafe prior to final deployment if you find that to be the best option for your application.

Here are some of the most popular options currently available for JavaScript:

• JSMin
• Dojo ShrinkSafe
• YUI Compressor
• Dean Edwards' Packer

CompressorRater is a site that compares these different applications and gives some basic benchmarks for deciding among them.

For final deployment, you should also make sure that gzip is installed and configured on your web server. Gzip compresses JavaScript files on the server and sends them over HTTP to the browser in compressed form, allowing the browser to decompress them at the last second. Most JavaScript files (even minimized ones) receive a significant reduction in file size through Gzip, which can increase the perceived speed of your application on initial load.