# uSCXML ReadMe
[](https://travis-ci.org/sradomski/uscxml)
#### Related Documents
- [Building form Source](docs/BUILDING.md)
- [Open Issues](docs/ISSUES.md)
- [Getting Started](docs/GETTING_STARTED.md)
## General
uSCXML is a SCXML interpreter and transformer written in C/C++. It is
[standards compliant](#test-reports) and [easily extended](#extending-uscxml)
even in C# and Java. The *interpreter* itself runs on Linux,
Windows, Raspberry Pi and Mac OSX, each 32- as well as
64Bits as well as iOS. The *generated native code* transformed from an
SCXML document runs on virtually any platform.
### Interpreter
The implementation of the SCXML **runtime interpreter** is available in the
libuscxml library with the uscxml-browser binary as a
frontend. It implements the following features:
* Data Models
* Full [ECMAScript data model](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/ecmascript) using Google's v8 (and JavaScriptCore on MacOSX and iOS)
* Simplified support for [Web Storage](http://www.w3.org/TR/2013/REC-webstorage-20130730/) in document.localStorage
* Support for binary data via [TypedArrays](https://www.khronos.org/registry/typedarray/specs/latest/) (will not throw exceptions yet)
* Full [NULL data model](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/null) with required In predicate
* [Prolog data model](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/prolog/swi) using SWI prolog
* Experimental [Promela data model](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/promela) for use
with the [SPIN](http://spinroot.com/spin/whatispin.html) model-checker
* Early support for a [Lua data model](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/lua)
* Rudimentary support for [XPath data model](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/datamodel/xpath)
* Invokers
* scxml: Invoke a nested scxml interpreter
* dirmon: Watches a directory for changes to files
* scenegraph: Simplified 3D scenegraphs with custom markup
* heartbeat: Periodically sends events
* umundo: Subscribe to channels and publish events
* [Many others](https://github.com/tklab-tud/uscxml/tree/master/src/uscxml/plugins/invoker)
* DOM
* DOM Core Level 2 + XPath extensions available for ecmascript data model
* Namespace aware to embed custom markup for special invokers
* Communication
* Features the standard basichttp I/O processor
* Features the required SCXML I/O processor
* No DOM I/O processor
* Early support for [WebSockets](http://datatracker.ietf.org/doc/rfc6455/)
* Can actually respond to HTTP requests with data via <response>
* Language Bindings
* Java bindings
* C# bindings
* PHP module for apache and cli interpreter (discontinued)
* Interactive Debugger
* Accessible via a [web-frontend](http://htmlpreview.github.io/?https://github.com/tklab-tud/uscxml/blob/master/apps/uscxml-debugger.html)
* Complete with user-defined breakpoints, data model inspection and stepping
### Transformer
The **transformer** is implemented in the libuscxml_transform library and
made available via the uscxml-transform binary. It is a general tool
for SCXML documents and currently implements the following features:
* Transformations onto
* [Flattened SCXML documents](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/transform/ChartToFlatSCXML.cpp) in which only a single state is ever active
* Resulting documents require slight adaptations to a compliant interpreter for donedata, the In predicate and invokers.
* Semantic equivalence is shown via IRP tests.
* [C native code](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/transform/ChartToC.cpp) for easy embedding of SCXML state-charts in C and C++ programs
* No invokers are implemented at the moment and only a single SCXML state-chart can be given in a given document.
* [PROMELA programs](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/transform/ChartToPromela.cpp) for model-checking via linear temporal logic with the SPIN model-checker.
* Only defined for the promela and null datamodel.
* [Minimized SCXML documents](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/transform/ChartToMinimalSCXML.cpp) with dead states and executable content removed
* Minimization is performed dynamically by marking elements as visited and removing unvisited elements.
* Annotations of the transitions exit set entry set, priority, conflicts, domain
### Test Reports
* We continuously run the [W3C IRP tests](http://www.w3.org/Voice/2013/scxml-irp/) for SCXML.
* The manual and XPath specific tests, are [excluded](https://github.com/tklab-tud/uscxml/blob/master/test/ctest/CTestCustom.ctest.in).
To run the tests yourself, you need to generate the build environment and pass -DBUILD_TESTS=ON via CMake:
$ cmake -DBUILD_TESTS=ON && make
Afterwards, you can run the various tests. There are more than 3500 tests in total,
so maybe restrict yourself to some subset.
| Variant | Data Model | Results | Invoke as |
|---------------|------------|---------|------------------------------------------|
| Plain IRP | ECMAScript | 196/196 | $ ctest -L "^ecma/test" |
| | XPath | 107/211 | $ ctest -L "^xpath/test" |
| | PROMELA | 147/165 | $ ctest -L "^promela/test" |
| | Lua | 165/201 | $ ctest -L "^lua/test" |
| Flattened IRP | ECMAScript | 196/196 | $ ctest -L "^fsm/ecma/test" |
| | XPath | 107/211 | $ ctest -L "^fsm/xpath/test" |
| | PROMELA | 147/165 | $ ctest -L "^fsm/promela/test" |
| | Lua | 165/201 | $ ctest -L "^fsm/lua/test" |
| Generated C | ECMAScript | 140/140 | $ ctest -L "^gen/c/ecma/test" |
| Verification | PROMELA | 130/181 | $ ctest -L "^spin/promela/test" |
### License
uSCXML itself is distributed under the Simplified BSD license as in, do not sue us and do
not misrepresent authorship. Please have a look at the licenses of the [libraries we depend
upon](https://github.com/tklab-tud/uscxml/blob/master/docs/BUILDING.md#build-dependencies) as well.
## Performance
We did some performance measurements in the scope of the C transformation. As
you can see in the figure below, for most IRP tests we average to a duration of
5-20us per microstep on an early 2015 MacBook Pro 13" with 3.1Ghz in the case
of [generated/compiled C](https://github.com/tklab-tud/uscxml/blob/master/test/src/test-c-machine.machine.c). For interpretation at runtime, we average at around 70-130us per
microstep. The generated C is rather optimized while the focus of the
interpreter is more on correctness, feature completeness and extensibility.
However, there are some lessons learned that are yet to be applied for the
interpreter.
For the tests, we took the [highest precision timer](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/concurrency/Timer.cpp)
we could attain and measured how long the execution of a given SCXML IRP tests took while
subtracting initialization, tear-down and the time spent in the data-model's routines. Time is
averaged over 1.000 iterations.
# Acknowledgments
This SCXML interpreter is developed at the [Telekooperation Group](http://www.tk.informatik.tu-darmstadt.de) of the Technical University of Darmstadt as part of the [SmartVortex](http://smartvortex.eu) project funded by the [7th European framework program](http://ec.europa.eu/research/fp7/index_en.cfm).