Merge branch 'master' of github.com:openlayers/ol3

bin/README.md

@@ -0,0 +1,51 @@
+# Build Utilities
+
+This directory contains utilities used for building OpenLayers applications, 
+generating the API docs, and building hosted versions of the library.
+
+## Dependencies
+
+OpenLayers is built using [Closure Compiler][closure].  The [plovr][plovr] build
+tool simplifies building with Closure Compiler and comes with a built-in version
+of the Closure Library and Compiler.  Both the Compiler and plovr require Java
+version 1.6 or above.  This directory includes a bash/batch script for driving
+plovr.  For pulling down plovr and accessing it in a cross-platform way,
+[Ant][ant] is used.
+
+The instructions below assume that you have added the `ol` bash/batch script to
+your path (type `ol` and see usage docs to confirm this is set up).
+
+[closure]: https://developers.google.com/closure/compiler/
+[plovr]: http://plovr.com/
+[ant]: http://ant.apache.org/
+
+## Building an Application
+
+To compile an application together with OpenLayers, you will provide a build
+configuration file for the compiler.  See the `demo` folder for example 
+configuration files (e.g. `map.json`).
+
+Compile your application with the `build` command:
+
+    ol build path/to/config.json
+
+Substitute the path to your build configuration file above.
+
+## Building the API Docs
+
+From within the root of the OpenLayers directory, use the `doc` command to build
+the API docs:
+
+    ol doc
+
+This will generate documentation in the `jsdoc` directory.
+
+## Building the Hosted Library
+
+To compile the full OpenLayers api, use the `build` command from the root of the
+OpenLayers directory:
+
+    ol build
+
+This will generate an `api.js` script in the same directory.  (This is equivalent to `ol build path/to/ol/api.json`.)
+

bin/build.xml

@@ -8,15 +8,15 @@
     <property name="ol.home" location=".."/>
     <property name="plovr.jar" location="${ol.home}/bin/plovr.jar"/>
     <property name="main.json" location="${ol.home}/main.json"/>
-    <property name="api.json" location="${ol.home}/api.json"/>
+    <property name="build.json" location="${ol.home}/api.json"/>
 
     <target name="usage">
         <echo>
         Available commands:
         
         serve - Run the library server
-        api   - Builds the optimized file with public api
+        build - Builds a minified version of the library or an application
-        doc   - Build the reference docs
+        doc   - Generate the reference docs
         </echo>
     </target>
 
@@ -36,10 +36,22 @@
         </java>
     </target>
 
-    <target name="api" depends="deps">
+    <target name="checkpath">
+        <condition property="build.json.set">
+            <isset property="build.json"/>
+        </condition>
+        <fail message="Missing build config." unless="build.json.set"/>
+        <property name="build.json.fullpath" location="${build.json}"/>
+        <condition property="build.json.exists">
+            <available file="${build.json.fullpath}" type="file"/>
+        </condition>
+    </target>
+
+    <target name="build" depends="deps, checkpath">
+        <fail message="Build config '${build.json.fullpath}' doesn't exist." unless="build.json.exists"/>
         <java jar="${plovr.jar}" fork="true">
             <arg value="build"/>
-            <arg value="${api.json}"/>
+            <arg value="${build.json}"/>
         </java>
     </target>
     

bin/ol

@@ -36,4 +36,9 @@ else
 
 fi
 
-ant -e -f "$OL_HOME/bin/build.xml" -Dol.home="$OL_HOME" $1
+ANT_ARGS=""
+if [ $# -gt 1 ]; then
+    ANT_ARGS=-Dbuild.json="$2"
+fi
+
+ant -e -f "$OL_HOME/bin/build.xml" -Dbasedir=. -Dol.home="$OL_HOME" $1 $ANT_ARGS

bin/ol.cmd

@@ -15,4 +15,7 @@ popd
 set COMMAND="%~1"
 if "%~1" == "" set COMMAND="usage"
 
-ant -e -f %OL_HOME%\bin\build.xml -Dol.home=%OL_HOME% -Dbasedir=. %COMMAND%
+set ANT_ARGS=
+if "%~2" == "" set ANT_ARGS="-Dbuild.json=%~2"
+
+ant -e -f %OL_HOME%\bin\build.xml -Dol.home=%OL_HOME% -Dbasedir=. %COMMAND% %ANT_ARGS%