Skip to content
Browse files

README update. Added build file templates to use as starting point fo…

…r new components
  • Loading branch information...
1 parent bfc4bab commit 3b587c60255b209c700fa28dbc38e086b825d9cf @sdesai sdesai committed Feb 25, 2009
View
220 componentbuild/README
@@ -0,0 +1,220 @@
+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.:
+
+ cd yui2/src/autocomplete
+ 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.
+
+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 it's 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 at the paths 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 README.properties 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 over-ride 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 README.targets
View
125 componentbuild/docs/README
@@ -1,125 +0,0 @@
-YUI uses ANT to create component build files from individual
-source files.
-
-Each component has it's own ANT build script residing in the component's
-"src" folder, with an associated properties file used to configure the
-default build properties e.g:
-
- yui2/src/autocomplete/build.xml
- yui2/src/autocomplete/build.properties
-
-The component build scripts 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). Running yuicompressor
- d). Running jslint all 3 built files
- e). Adding boiler plate module/version registration code
- f). Building skin files from <component>-core.css and <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 scripts currently do not 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 commiting changes.
-
-Below is a step-by-step guide installing the build system, allowing
-you to build the "src" component code.
-
-SHORT VERSION
-
-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.:
-
- cd yui2/src/autocomplete
- ant all
-
-DETAILED VERSION
-
-To use the build system, you'll need to install ANT and obtain
-the YUI build infrastructure scripts from github.
-
-These are one-time install tasks.
-
-INSTALLING ANT
-
-1). Download and install ANT 1.7 (or above)
-
- http://ant.apache.org/bindownload.cgi
-
-2). Set ANT_HOME to point to your ANT install root and add
- $ANT_HOME/bin/ant to your PATH
-
-INSTALLING YUI SCRIPTS
-
-1). Clone the YUI "builder" project from github:
-
- http://github.com/yui/builder/
-
-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.
-
-BUILDING AN EXISTING COMPONENT
-
-You should now be able run the build.xml file in any component's
-src folder, to build the component by typing in "ant all", e.g:
-
- At the command prompt:
-
- cd yui2/src/autocomplete
- ant all
-
-The "all" build target will build the autocomplete component from it's
-source files and deploy the built files to the yui2/build/autocomplete
-folder.
-
-If you just type in "ant", without a target specified, it will
-execute the default target, "local", which will build files to the
-temporary src/<component>/build_tmp directory, without deploying
-them to the top level build directory.
-
- At the command prompt:
-
- cd yui2/src/autocomplete
- ant
-
-ANT will output build information to 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
-
-TODO
View
20 componentbuild/templates/yui2/build.properties
@@ -0,0 +1,20 @@
+# MyComponent Build Properties
+
+# As long as the 'builder' project is cloned to the default folder
+# next to the 'yui2' project folder, the 'builddir' property does not
+# need to be changed
+#
+# If the 'builder' project is checked out to an alternate location, this
+# property should be updated to point to the checkout location.
+builddir=../../../builder/componentbuild
+
+# The name of the component. E.g. dom, autocomplete, container
+component=mycomponent
+
+# The main class for the component. This is the class which get registered for YUI 2
+# NOTE: For a css component (e.g. fonts, grids, reset etc.), this property is not used/required
+component.mainclass=YAHOO.widget.MyComponentClass
+
+# The list of files which should be concatenated to create the component.
+# NOTE: For a css component use component.cssfiles instead.
+component.jsfiles=MyComponentClass.js, MyComponentHelperClass.js, MySubComponentClass.js
View
9 componentbuild/templates/yui2/build.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- YUI 2 Component Build File -->
+
+<project name="MyComponent" default="local">
+ <description>MyComponent Build File</description>
+ <property file="build.properties" />
+ <import file="${builddir}/2.x/bootstrap.xml" description="Default Build Properties and Targets" />
+</project>
View
22 componentbuild/templates/yui3/build.properties
@@ -0,0 +1,22 @@
+# MyComponent Build Properties
+
+# As long as the 'builder' project is cloned to the default folder
+# next to the 'yui3' project folder, the 'builddir' property does not
+# need to be changed
+#
+# If the 'builder' project is checked out to an alternate location, this
+# property should be updated to point to the checkout location.
+builddir=../../../builder/componentbuild
+
+# The name of the component. E.g. event, attribute, widget
+component=mycomponent
+
+# 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=MyComponentClass.js, MyComponentHelperClass.js, MySubComponentClass.js
+
+# The list of modules this component requires. Used to setup the Y.add module call for YUI 3.
+# NOTE: For a css component, this property is not used/required.
+
+# component.use, component.supersedes, component.optional and component.skinnable are other properties which can be defined
+component.requires=node, attribute, queue
View
9 componentbuild/templates/yui3/build.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- YUI 3 Component Build File -->
+
+<project name="MyComponent" default="local">
+ <description>MyComponent Build File</description>
+ <property file="build.properties" />
+ <import file="${builddir}/3.x/bootstrap.xml" description="Default Build Properties and Targets" />
+</project>
View
21 componentbuild/templates/yui3/rollup/build.properties
@@ -0,0 +1,21 @@
+# MyRollupComponent Build Properties
+
+# As long as the 'builder' project is cloned to the default folder
+# next to the 'yui3' project folder, the 'builddir' property does not
+# need to be changed
+#
+# If the 'builder' project is checked out to an alternate location, this
+# property should be updated to point to the checkout location.
+builddir=../../../builder/componentbuild
+
+# The name of the rollup module
+component=myrollupcomponent
+
+# Flag, indicating this module is a rollup module
+component.rollup=true
+
+# Path to sub-module build files, in the order they are to be rolled up
+component.rollup.modules.buildfiles=subcomponentone.xml, subcomponenttwo.xml
+
+# Rollup registration options
+component.use=subcomponentone, subcomponenttwo
View
13 componentbuild/templates/yui3/rollup/build.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ YUI 3 Rollup Component Build File. Running this build.xml file, will kick-off the
+ subcomponent builds, to create subcomponentone and subcomponenttwo, and will also
+ roll both of these subcomponent back up into the rollup file.
+-->
+
+<project name="YUI" default="local">
+ <description>MyRollupComponent build file</description>
+ <property file="build.properties" />
+ <import file="${builddir}/3.x/bootstrap.xml" description="Default Build Properties and Targets" />
+</project>
View
13 componentbuild/templates/yui3/rollup/subcomponentone.properties
@@ -0,0 +1,13 @@
+# SubComponentOne Build Properties
+
+# This file is just the same as a regular (non-rollup) component file,
+# the only difference being the need to specify the top level build directory
+# as shown below
+
+# Normally, subcomponents are deployed to the same location as the parent rollup, hence
+# we over-ride the default top level build directory (the default would be ${srcdir}/build/subcomponentone)
+global.build.component=${srcdir}/build/myrollupcomponent
+
+builddir=../../../builder/componentbuild
+component=subcomponentone
+component.jsfiles=SubComponentOne.js, SubComponentOneHelper.js
View
5 componentbuild/templates/yui3/rollup/subcomponentone.xml
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="SubComponentOne" default="local">
+ <property file="subcomponentone.properties" />
+ <import file="${builddir}/3.x/bootstrap.xml" description="Default Build Properties and Targets" />
+</project>
View
13 componentbuild/templates/yui3/rollup/subcomponenttwo.properties
@@ -0,0 +1,13 @@
+# SubComponentTwo Build Properties
+
+# This file is just the same as a regular (non-rollup) component file,
+# the only difference being the need to specify the top level build directory
+# as shown below
+
+# Normally, subcomponents are deployed to the same location as the parent rollup, hence
+# we over-ride the default top level build directory (the default would be ${srcdir}/build/subcomponenttwo)
+global.build.component=${srcdir}/build/myrollupcomponent
+
+builddir=../../../builder/componentbuild
+component=subcomponenttwo
+component.jsfiles=SubComponentTwo.js, SubComponentTwoHelper.js
View
5 componentbuild/templates/yui3/rollup/subcomponenttwo.xml
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="SubComponentTwo" default="local">
+ <property file="subcomponenttwo.properties" />
+ <import file="${builddir}/3.x/bootstrap.xml" description="Default Build Properties and Targets" />
+</project>

0 comments on commit 3b587c6

Please sign in to comment.
Something went wrong with that request. Please try again.