Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Fetching latest commit…

Cannot retrieve the latest commit at this time

README
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 <component>.js, <component>-min.js, <component>-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 <component>-core.css, <component>-skin.css
   g) Deploying built JS, CSS and assets to <project>/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 <project>/src directory, and built code into the 
   <project>/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:

   <gitroot>/yui2       [ cloned yui2 project ]
   <gitroot>/yui3       [ cloned yui2 project ]
   <gitroot>/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. 
Something went wrong with that request. Please try again.