Welcome to YUI Builder

This repo has been deprecated in favor of Shifter.

Introduction

YUI uses ANT to create component build files from individual source files.

Each component has its own ANT build file residing in the component's source folder with an associated properties file used to define build parameters specific to the component e.g:

yui2/src/autocomplete/build.xml yui2/src/autocomplete/build.properties

The component build will automate the conversion from component source to .js, -min.js, -debug.js by:

a) Concatenating individual source files b) Stripping logger statements c) Compressing files, using yuicompressor d) Running jslint on all 3 built files e) Adding boiler plate module/version registration code f) Building skin files from -core.css, -skin.css g) Deploying built JS, CSS and assets to /build

The same component build system is also used for CSS components such as reset, base, fonts and grids.

The component build does not currently:

a) Check in any code

The developer is responsible for checking modified source code into the /src directory, and built code into the /build directory, allowing them to review diffs, before committing changes.

b) Generate API documentation

Installation

Below is a brief summary as well as a detailed step-by-step guide for installing the build system, allowing you to build the "src" component code.

Summary

1. Install ANT 1.7 or above, and add ant to your path

2. Clone the YUI "builder" project from http://github.com/yui/builder/

3. At the command line, cd to the source directory of the component you wish to build, and execute "ant all" to build, e.g.:

   prompt> cd yui2/src/autocomplete prompt> ant all

Detailed Instructions

To use the build system, you'll need to install ANT and obtain the YUI build infrastructure from github.

These are both one-time install tasks.

Installing Ant

1. Download and install ANT 1.7 (or above)

   http://ant.apache.org/bindownload.cgi

2. Be sure to define an ANT_HOME environment variable to point to your ANT install root, and add the ANT executable to your environment's PATH variable.

Installing YUI Build Infrastructure

1. Clone the YUI "builder" project from github:

   http://github.com/yui/builder/

   This project contains the files used by the YUI ant build process.

2. Out of the box, the build system is designed to work when cloned to the default "builder" directory, parallel to the project source directories:

   /yui2 ( cloned yui2 project ) /yui3 ( cloned yui2 project ) /builder ( cloned builder project )

   Cloning it to the default location will allow you to build any of the components without having to modify any component build scripts.

   NOTE: YUI Builder is also available for download as a zip from http://yuilibrary.com/downloads. If downloading from this location to build yui2 or yui3 source, make sure to unzip the contents into the directory structure mentioned above, to have the build work out of the box.

Building An Existing Component

With ANT and the YUI build infrastructure installed, you can now build any of the components from source, using the build.xml file in the component's source directory.

The build system allows you to build locally, within the component's source directory, and also run a full build to update the top level build directory for a component.

Full Build

To perform a full build for a component, run ant with the "all" target:

e.g:

prompt> cd yui2/src/autocomplete
prompt> ant all

The "all" build target will build the component from its source files AND deploy the built files, as well as any assets, to the top level build folder:

<project>/build/<component>

So, for autocomplete, the built files would be copied to:

yui2/build/autocomplete

NOTE: When invoking ant without a file argument, as we do above, it will use build.xml, if present in the current directory - which is what we want.

LOCAL BUILD

To perform a local build for a component, run ant without a target:

e.g:

prompt> cd yui2/src/autocomplete
prompt> ant

This will run the default target, which is "local".

The "local" build target will build the autocomplete component from its source files, but will NOT deploy the built files to the top level build folder.

The locally built files are stored in the temporary directory:

<project>/src/<component>/build_tmp

So, for autocomplete, the built files can be found in the directory below:

yui2/src/autocomplete/build_tmp

Build Output

ANT will output build information to the screen, as it runs through the build, which can be redirected to a file if required:

prompt> ant all

    Buildfile: build.xml
        [echo] Starting Build For autocomplete
        ...
        [echo]     builddir : ../../../builder/componentbuild
        ...
        ...
    BUILD SUCCESSFUL
    Total time: 7 seconds

prompt>

NOTE: Most components will have warnings which are output during the "minify" and "lint" steps, which the component developer has evaluated and determined to have no impact on functionality.

Creating Build Files For A New Component

The builder/componentbuild/templates directory has basic build.xml and build.properties templates for the various component types supported.

For most new components, you should be able to start with the appropriate template files and simply change the values of the basic properties defined to suit your component.

If you're creating:

• A YUI 2 Component (either a JS or CSS component), use:

  builder/componentbuild/templates/yui2

   build.xml
   build.properties
  

• A YUI 3 Component (either a JS or CSS component), use:

  builder/componentbuild/templates/yui3

   build.xml
   build.properties
  

• A YUI 3 Rollup Component, use:

  builder/componentbuild/templates/yui3/rollup

  For the rollup component: build.xml build.properties

  For the sub components: subcomponentone.xml subcomponentone.properties subcomponenttwo.xml subcomponenttwo.properties

Further Customization

If required, you can define custom values for any of the properties defined in builder/componentbuild/docs/properties.html to customize the build for your new component, however as mentioned above, for most components the properties defined in the template files should be sufficient.

You can also override or extend existing targets, to customize the actual build process for a component if required. The list of targets and their role is defined in builder/componentbuild/docs/targets.html.

Log Verbosity

• ant all will give you the default log output, may be a little noisy
• ant all -v will give you full log output (really noisy)
• ant all -q will give you only the jslint output from your build

JSLint/Hint

By default, we look for the node executable. If found we use a Node.js based JSLint server to lint the JS files. If it's not installed, we fall back to Rhino (which can be very slow)

If you install the jshint (npm -g i jshint), we will use that by default.

To skip using this you can pass -Djshint.skip=true:

`ant all -q -Djshint.skip=true`

The default is also to only run jslint/hint on RAW files, skipping min and debug versions.

You can change this by adding -Dlint.all=true to your command:

`ant all -q -Dlint.all=true`