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

…r new components
yui · Feb 26, 2009 · 3b587c6 · 3b587c6
1 parent bfc4bab
commit 3b587c6
Show file tree

Hide file tree

Showing 12 changed files with 350 additions and 125 deletions.
diff --git a/componentbuild/README b/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
diff --git a/componentbuild/docs/README b/componentbuild/docs/README
diff --git a/componentbuild/templates/yui2/build.properties b/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
diff --git a/componentbuild/templates/yui2/build.xml b/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>