Auto-Building YUI 3 Custom Modules

The details of my development strategy to automatically build YUI 3 Custom Modules that I outlined in my talk at YUICONF 2009.

YUI 3’s modularity and instance sandboxing invites developers to create their own custom modules, breaking apart their specific application logic.

Having developed over 30 Custom YUI 3 Modules in the last year I quickly realized I needed a sane way to go from writing code to running it in the browser. So, I set out to connect the YUI Builder with my IDE.

For the last three or more years I’ve been using Aptana Studio IDE for HTML, CSS, and JavaScript code development. Aptanta, which is built on Eclipse, can be used standalone or as a plugin to Eclipse. The concepts here are not specific to Eclipse; the details of my technique on implementing the concepts are however.

Goals and Reasons

• Synchronize UI building with the rest of the project code.
  Compiling of JavaScript (when needed) should occur along with any server-side code compilation. IDEs such as Eclipse, ‘Build Automatically’ a project’s Java code; I want my YUI 3 Custom Modules to ‘Build Automatically’ as well.
• Faster turn-around.
  I don’t want to switch from my IDE to another program to run builds on my UI code. The IDE should recognize when it needs to re-build my UI code. I want a process where I: hack… hack… save… refresh-browser…
• Easier for non-UI developers.
  Teams of developers are usually working on a shared code-base; a mixture of server-side and client-side code wrapped up into one project. If the UI code is built automatically, like the server-side code, the non-UI developers won’t bitch don’t have to do anything UI-related.
• Cmd + S = JSLint, Compress, & Deploy.
  Anytime the source file(s) to a YUI 3 Custom Module change, the YUI Builder tool runs, giving me: JSLint-ing, YUI Compressor-ing, and YUI 3 Module wrapping.

Auto-Building in Eclipse IDE

Eclipse is an open, extensible, integrated development environment. Eclipse’s External Tools feature a great place to integrate the YUI Builder into the IDE:

“External tools allow you to configure and run programs, batch files, Ant buildfiles, and others using the Workbench. You can save these external tool configurations and run them at a later time.

Output from external tools is displayed in the console view.

You can add external tools as part of the build process for a project. These external tools will run in the specified order every time a project is built.” — Eclipse.org

Eclipse External Tools Builders can run Ant tasks, the YUI Builder and YUI 3 Custom Module build files are Ant tasks, perfect!

The goals listed above are reachable. I’m, not going to lie, this was hard to get working the first time; I feel it’s best to go through the process in steps.

0. Git YUI Builder

You need a copy of the YUI Builder project. If you already have Git clones of other YUI projects, make the Builder project a sibling to them.

$ git clone git://github.com/yui/builder.git

Detailed YUI Builder installation instructions.

1. Set builddir as a Global Ant Property in Eclipse

YUI 3 Module build files need to be configured with a builddir property; Eclipse can be configured with the path to YUI Builder on your system. By creating this property you will not have to hard-code the path to the YUI Builder project; making it easier to share code amongst a team. Everyone in your team will need to set the builddir Ant property in their Eclipse configuration; a trade-off between configuration and development environment convention.

Eclipse > Preferences > Ant > Runtime > Properties
Name: builddir
Value: /path/to/yui/builder/componentbuild
The value will needs to be set for each system specifically.

2. Create YUI 3 Module Directory Structure

For each YUI 3 Custom Module you create, you’ll want to create a directory structure that mimics the default structure for YUI 3 Core Modules (Note: The directory structure can be different, you’ll just have to “tell” the YUI Builder via extra configuration in the build.properties file):

Assume we’re creating a module named test

/../
	test/
		js/
			test.js
		build.xml
		build.properties

3. Create build.xml and build.properties Files

The build.xml file is ran by Ant, it defines some meta-data about the module build and imports the module-specific build.properties file.

Again, assuming a module named test

build.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Test Component Build File -->
<project name="Test" default="local">
    <description>Test Build File</description>
    <property file="build.properties" />
    <import file="${builddir}/3.x/bootstrap.xml" description="Default Build Properties and Targets" />
</project>

build.properties

I left in the comments to provide explanations of the main settings.

# Test Build Properties

# The name of the component. E.g. event, attribute, widget
component=test

# The list of files which should be concatenated to create the component.
# NOTE: For a css component (e.g. cssfonts, cssgrids etc.) use component.cssfiles instead.
# component.jsfiles=test.js, testHelperClass.js, testSubComponentClass.js
component.jsfiles=test.js

# The list of modules this component requires. Used to set up the Y.add module call for YUI 3.
component.requires=widget

# The list of modules this component supersedes. Used to set up the Y.add module call for YUI 3.
component.supersedes=

# The list of modules that are optional for this module. Used to set up the Y.add module call for YUI 3.
component.optional=

4. Connect Eclipse With YUI Builder and Module’s Build File

Creating and configuring a new Project Builder will allow Eclipse to drive the YUI Builder tool for your YUI 3 Custom Module.

Open Project Properties

Project > Properties

Create New Project [Ant] Builder

Builders > New…
Choose Ant Builder

Set Build Name and Select Buildfile Created in Step 3

Give the Builder a unique name and select the Buildfile associated with your Custom Module (which you setup previously) by choosing: Browse Workspace….

Note: One finicky thing I found with Eclipse is it’s in-ability to remember Builder settings when moving between tabs; Always click Apply before switching tabs in the Builder Configuration.

Set Ant Targets

By default, the Builder’s: ‘After a “Clean”’, and ‘Manual Build’ Eclipse “Moments” will be set to the default Ant target as specified in the Ant buildfile. Choose the default target for ‘Auto Build’ as well.

Set Build Options

Important here is to tell the builder which files to monitor for changes, and only re-build the YUI 3 Custom Module when one (or more) of those files has changed. Otherwise the build process will run in an infinite loop.

Check: Specify working set of relevant resources
Click: Specify Resources…

Specify [Relevant] Resources

Notice: I do not have the build_tmp directory selected, just the source files that make up the YUI 3 Custom Module. You’ll want Eclipse to monitor just the module’s source files, and rebuild the module when only those file change.

Build Project Automatically

Set your Eclipse project to ‘Build Automatically’ by selecting:
Project > Build Automatically

Further Configuration

The YUI Builder tool is highly-configurable, there are many configuration properties that can be set and Ant targets to run; both specified in the docs folder of the YUI Builder project. Most likely you’ll have to configure extra properties in your build.properties files to move your deployable YUI 3 Custom Modules to an appropriate place in your project’s layout.

I highly recommend you review the YUI Builder configuration properties and Ant targets documentation.