Welcome to YUI Builder
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:
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
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.
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
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.
1) Download and install ANT 1.7 (or above)
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:
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.
To perform a full build for a component, run ant with the "all" target:
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:
So, for autocomplete, the built files would be copied to:
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.
To perform a local build for a component, run ant without a target:
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:
So, for autocomplete, the built files can be found in the directory below:
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:
A YUI 3 Component (either a JS or CSS component), use:
A YUI 3 Rollup Component, use:
For the rollup component: build.xml build.properties
For the sub components: subcomponentone.xml subcomponentone.properties subcomponenttwo.xml subcomponenttwo.properties
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.
ant allwill give you the default log output, may be a little noisy
ant all -vwill give you full log output (really noisy)
ant all -qwill give you only the jslint output from your build
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
npm -g i jshint), we will use that by default.
To skip using this you can pass
`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`