Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
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.