<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->
$Id$

        Commons Sandbox - Google Summer of Code 2010 Project

                    -- TITLE --

SCXML Code Generation Framework, JavaScript Edition (SCXML/cgf/js): An
SCXML-to-JavaScript Compiler Optimized for User Interface Development on the
World Wide Web

                  -- ABSTRACT --

This project has two goals. The first is to develop an SCXML-to-JavaScript
compiler optimized for User Interface development on the World Wide Web.
This would allow developers to elegantly describe and implement Web-based
UIs with complex behavioural requirements. The second goal is to generate
graphical depictions of statecharts, which may then be animated in response
to live UI events. This would allow developers to better comprehend the
dynamic behaviour described by their statecharts.

GSoC participant: jbeard
GSoC mentor:      rahul


==Requirements==

Ant and Java


==Installation==

To use SCXMLcgf/js, you must first download the dependencies. Run:

ant -f getDeps.xml


==Running the Compiler==

./run.sh [options] file1 file2 ...

A summary of available options are as follows:

- backend	Statechart implementation technique. Currently one of {switch | table | state}
- noForEach	Assume that the target environment does not have an Array.forEach method
- noIndexOf	Assume that the target environment does not have an Array.indexOf method
- noMap		Assume that the target environment does not have an Array.map method
- ie		The equivalent of -noForEach -noIndexOf -noMap
- beautify	Will run generated code through a beautifier.
- log		Will enable logging in generated code.
- verbose	Will enable verbose logging in the compiler.


For example, you might run the following:

./run.sh --backend state --beautify --ie test/kitchen_sink/KitchenSink.xml > KitchenSinkIE.js


==Running Unit and Performance Tests==

SCXMLcgf/js comes with a script for automating unit and performance tests. 

./build.sh [task]

A summary of available tasks are as follows:

- clean: Deletes the build directory.
- init: Creates the build directory.
- genJavaScript: Generates JavaScript from unit and performance test
	 SCXML.
- genPerformanceTestHtml: Generates an HTML file for each performance
	 test script and each target JavaScript file.
- runPerformanceTestsWithSelenium: Uses Selenium to open generated
	performance test HTML files in browsers that are available on the
	system, and capture benchmark data from them.
- doPerformanceAnalysis: Sends captured benchmark data to the
	performance analysis script.
- genUnitTestHtml: Generates an HTML file for each performance test
	script and each target JavaScript file.
- runUnitTestsWithSelenium: Uses Selenium to open generated unit test
	HTML files in browsers that are available on the system, and capture
	unit test results from them.
- runUnitTestsWithRhino: Runs unit tests with Rhino.


To run unit and performance tests with Selenium, you must have a web server
serving files on port 8080 in the SCXMLcgf/js root directory.