Permalink
Browse files

Comments/README for component build system

  • Loading branch information...
1 parent b2ae49b commit bfc4babcee93b0438d941fddffe968f43230fc36 @sdesai sdesai committed Feb 25, 2009
Showing with 185 additions and 86 deletions.
  1. +93 −79 componentbuild/docs/README
  2. +57 −6 componentbuild/shared/properties.xml
  3. +35 −1 componentbuild/shared/targets.xml
@@ -1,111 +1,125 @@
-The YUI Team uses ANT to create component build files from individual
-source files.
+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
-base folder, with an associated properties file used to configure the
-default build properties.
+"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 source files
- b). Stripping logger statements
- c). Running yuicompressor
- d). Running jslint all 3 built files
- e). Attaching the appropriate suffix (e.g. beta, experimental etc.)
- f). Adding version registration code
- g). Deploying local built files to <2.x>/build
- h). Deploying assets to <2.x>/build
- i). Deploying src files to <2.x>/src, for Documentation parsing
+ 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.
-NOTE: The scripts currently do not checkin any code to CVS
+These are one-time install tasks.
-Below is a step-by-step guide to getting things setup for a new
-component.
+INSTALLING ANT
-GETTING STARTED
+1). Download and install ANT 1.7 (or above)
-0). If you have any work in progress, especially in your build
- directories, back it up before trying this.
+ http://ant.apache.org/bindownload.cgi
-1). Download and install ANT 1.7 (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
-2). Run cvs update -D under yahoo/presentation/tools/builder. You'll
- pickup the componentbuild directory, if it's not there already.
+INSTALLING YUI SCRIPTS
-3). Set ANT_HOME to point to your ANT install root and add
- $ANT_HOME/bin/ant to your PATH
+1). Clone the YUI "builder" project from github:
-4). Set the following two environment variables, to point to your local
- working directory
+ http://github.com/yui/builder/
- YUI_SRC_DIR = <CVSROOT>/yahoo/presentation/2.x
- YUI_BUILD_DIR = <CVSROOT>/yahoo/presentation/tools/builder/componentbuild
+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:
- If you don't work directly in your CVS tree, wherever it is that you
- copy the yahoo/presentation code to.
+ <gitroot>/yui2 [ cloned yui2 project ]
+ <gitroot>/yui3 [ cloned yui2 project ]
+ <gitroot>/builder [ cloned builder project ]
-5). To start with, copy $YUI_BUILD_DIR/build.common.xml and
- $YUI_BUILD_DIR/build.common.properties to your own component's
- base directory (the folder containing your src/asset files)
+ Cloning it to the default location will allow you to
+ build any of the components without having to modify any
+ component build scripts.
- NOTE: You can also look at $YUI_BUILD_DIR/build.example.xml,
- build.example.properties. They're essentially READMEs and have
- detailed information about the full set of variables available.
+BUILDING AN EXISTING COMPONENT
-6). Modify your version of build.properties to reflect your component
- requirements
+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:
- IMPORTANT NOTES:
+ At the command prompt:
- a). By default the local build location is set to the "build"
- directory under the component's base directory:
+ cd yui2/src/autocomplete
+ ant all
- component.basedir=${srcdir}/widget/${component}
- component.builddir=${component.basedir}/build
+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.
- This directory gets created/over-ridden everytime you build.
-
- If your component has a persistant local "build" directory, you can
- specify another transient directory for ANT to use, using the
- above property.
+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.
- b). The logger.regex properties are designed to strip lines
- containing "logger"|"YAHOO.log", including multiline calls.
-
- If using the default regex, you need to make sure your logger
- statements are on their own lines and end in semi-colons otherwise
- and code on the same line as the logger statement will be stipped.
+ At the command prompt:
- Also, the default regex may not be appropriate for certain
- components. For example the Logger component or YAHOO may need
- to modify this regex to suit their needs.
-
- Individual component owners can define their own regex, based on
- their coding styles.
+ cd yui2/src/autocomplete
+ ant
-7). cd to your component's base directory and type "ant" at the command
- line.
-
- With no arguments, ANT will run look for a "build.xml" in the current
- folder, and invoke it's default target
+ANT will output build information to screen, as it runs through the
+build, which can be redirected to a file if required:
-8). If all is good, this should run the "local" target (which is the default
- target). This creates <component>.js and <component>-min.js in the local
- build directory specified by ${component.builddir}.
+ prompt>ant all
-9). If you run "ant all", the script will run the "local" target, building
- to your local build directory and then deploy files to the top level
- 2.x/build, 2.x/src directories.
+ Buildfile: build.xml
+ [echo] Starting Build For autocomplete
+ ...
+ [echo] builddir : ../../../builder/componentbuild
+ ...
+ ...
+ BUILD SUCCESSFUL
+ Total time: 7 seconds
-You can run other targets also by specifying them on the command line
-using "ant <target>".
+ prompt>
-If interested, you can also look at
+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.
- $YUI_BUILD_DIR/targetlib.xml : Target definitions
- $YUI_BUILD_DIR/buildproperties.xml : Default property values
- $YUI_BUILD_DIR/macrolib.xml : Macro tasks
+CREATING BUILD FILES FOR A NEW COMPONENT
-You can contact sdesai@yahoo-inc.com or yui-team@yahoo-inc.com for help,
-information or to report issues with this infrastructure
+TODO
@@ -2,6 +2,7 @@
<project name="YuiSharedProperties">
+ <!-- ANT contrib library for loops, if/else support, with property fix for FOR task -->
<taskdef resource="antcontrib.properties">
<classpath>
<pathelement location="${builddir}/lib/ant-contrib/ant-contrib-1.0b3-modified.jar" />
@@ -10,10 +11,14 @@
<dirname property="buildfile.dir" file="${ant.file}" />
+ <!--
+ builddir : The path to the builder/componentbuild directory from the component build file
+ srcdir : The path to top of the project source directory (e.g. yui2) from the component build file
+ -->
<property name="builddir" location="../../../builder/componentbuild" />
<property name="srcdir" location="../.." />
- <!-- Default Library Version Build -->
+ <!-- buildfiles.eol : End of line char to use for built files -->
<property name="buildfiles.eol" value="lf"/>
<!-- Supporting Tools -->
@@ -22,9 +27,11 @@
<property name="jslintsrc.js" location="${builddir}/lib/jslint/fulljslint.js" />
<property name="yuicompressor.jar" location="${builddir}/lib/yuicompressor/yuicompressor-2.4.jar" />
+ <!-- YUI Compressor arguments for JS and CSS files -->
<property name="yuicompressor.css.args" value="--type css --line-break 6000" />
<property name="yuicompressor.js.args" value="--disable-optimizations --preserve-semi --line-break 6000" />
+ <!-- Enable/Disable YUI Compressor verbosity. NOTE: Checked in build files should not disable this flag -->
<property name="yuicompressor.js.verbose" value="true" />
<property name="yuicompressor.css.verbose" value="true" />
@@ -36,12 +43,50 @@
<istrue value="${yuicompressor.css.verbose}" />
</condition>
- <!-- Top Level Directories (e.g. <project>/build, <project>/src) -->
+ <!-- Top Level Build Directories (e.g. yui2/build, yui3/build)-->
<property name="global.build.base" location="${srcdir}/build" />
<property name="global.build.component" location="${global.build.base}/${component}" />
<property name="global.build.component.assets" location="${global.build.component}/assets" />
- <!-- Component Defaults -->
+ <!-- Component Level Properties
+
+ component Component name, lower-case. Used for build filenames(e.g. component.js, component-min.js)
+ component.module Module name, mostly always the same as component
+ component.mainclass Main JS class representing the module. Version code will be added to this class [ YUI2 Only ]
+
+ component.basedir Absolute path to the component's base directory (e.g. yui2/src/autocomplete)
+ component.srcdir Absolute path to the component's base directory (e.g. yui2/src/autocomplete)
+ component.builddir Absolute path to the component's local build directory (e.g. yui2/src/autocomplete/build_tmp)
+
+ component.jsfiles.base Base dir for component's js files (e.g. yui2/src/autocomplete/js)
+ component.jsfiles Comma seperated ordered list of source files to be concatenated, relative to component.jsfiles.base
+
+ component.assets.skins.base Base directory for the component's skinning assets (e.g. yui2/src/autocomplete/assets/skins)
+
+ If this value is set, the build expects the following directory structure:
+
+ <component.assets.skins.base>
+ - <component>-core.css
+ - skins/sam/<component>-skin.css
+ - skins/sam/[component specific skin images]
+
+ component.assets.skins.files Set of skinning assets to deploy (defaults to **/*)
+
+ component.assets.base Base directory for the component's non-skinning related assets. E.g. swfs, non-skinned images
+ component.assets.files Set of assets files to deploy (defaults to **/*)
+ component.assets.flatten Whether or not to flatten the asset directory structure when deploying to build
+
+ component.logger.regex Regex used to strip logger statements
+ component.logger.regex.byline If component.logger.regex.byline is false, regex will match against the
+ entire file as opposed to line by line - required for multiline search.
+ component.logger.regex.flags The set of standard Perl5 regex flags which apply. Defaults to mg if not provided
+ component.logger.regex.replace The replacement string to use. Defaults to empty string
+
+ LOGGER REGEX NOTE:
+ - Log statements need to end in semi-colons, otherwise the default regex will strip out code until the next semi-colon is hit.
+ - Any code on the same line as the start or end of a Log statement will be stripped. Hence Log statments should be on their own lines.
+ -->
+
<property name="component.module" value="${component}" />
<property name="component.basedir" location="${buildfile.dir}" />
<property name="component.srcdir" value="${component.basedir}" />
@@ -61,17 +106,21 @@
<available file="${component.assets.base}/skins" type="dir" property="component.skins.exist"/>
<available file="${component.assets.base}" type="dir" property="component.assets.exist"/>
- <condition property="component.basefilename" value="${component}-${component.releasetype}" else="${component}">
+ <!--
+ component.basefilename, component.releasetype: Deprecated
+ We used to mark filenames with suffixes (-beta, -experimental), which we no longer do
+ -->
+ <condition property="component.basefilename" value="${component}" else="${component}">
<isset property="component.releasetype"/>
</condition>
- <!-- Default Logger Regex values if not provided -->
+ <!-- Default logger regex values if not provided -->
<property name="component.logger.regex" value="^.*?(?:logger|YAHOO.log).*?(?:;|\).*;|(?:\r?\n.*?)*?\).*;).*;?.*?\r?\n" />
<property name="component.logger.regex.replace" value="" />
<property name="component.logger.regex.flags" value="mg" />
<property name="component.logger.regex.byline" value="false" />
- <!-- Rollup Support -->
+ <!-- Rollup support, currently only used for YUI 3 -->
<property name="component.rollup" value="false"/>
<property name="component.rollup.target" value="all"/>
@@ -86,8 +135,10 @@
</and>
</condition>
+ <!-- The temporary working directory used by the build process -->
<property name="workingdir" location="${component.builddir}/ant" />
+ <!-- The file which defines the default targets for the particular type of component (module, rollup, css) -->
<condition property="targetbase" value="rollup" else="module">
<istrue value="${component.rollup}"/>
</condition>
@@ -2,6 +2,38 @@
<project name="YuiSharedTargets">
+ <!--
+
+ TARGET DEFINITIONS
+
+ This file defines the core set of targets which make up the build process,
+ and which can be invoked via the ant command line, using ant <target>.
+
+ all Invokes "local" and then "deploy". This is what you would normally call
+ when you're ready to check in your code.
+
+ local Invokes "clean, init, build, minify, lint". This is what you would
+ normally call, when going through a local build/test/build/test cycle.
+
+ clean Deletes the local build dir
+ init Creates the component's local build dir (e.g. yui2/src/autocomplete/build_tmp)
+
+ build [abstract] Builds the component files in the local build dir. The work
+ actually performed in the build step varies for the type of component and is
+ defined by the type of build file pulled in (e.g. componentbuild/2.x/module.xml,
+ componentbuild/3.x/rollup.xml, componentbuild/shard/cssmodule.xml etc)
+
+ minify Compresses the built files
+ lint Runs lint on the built files
+
+ deploy Copies built code, along with any assets, to the top level build directory
+
+ The implementation of "build" is handled by the files in builder/componentbuild/2.x and
+ builder/componentbuild/3.x, which define the build steps for yui2 and yui3 components and
+ also account for the different types of components - modules, rollups, css modules etc.
+
+ -->
+
<echo level="info">Starting Build For ${component}</echo>
<echo level="info">Ant Properties</echo>
@@ -81,7 +113,9 @@
</copy>
</target>
- <target name="deploydocs" description="Copy doc files to global doc locations"></target>
+ <target name="deploydocs" description="Copy doc files to global doc locations">
+ <!-- TODO -->
+ </target>
<target name="-prepend" if="component.prependfiles">
<concat destfile="${workingdir}/${component.basefilename}.js.tmp" fixlastline="true">

0 comments on commit bfc4bab

Please sign in to comment.