diff options
author | Stefan Radomski <github@mintwerk.de> | 2016-05-12 13:12:33 (GMT) |
---|---|---|
committer | Stefan Radomski <github@mintwerk.de> | 2016-05-12 13:12:33 (GMT) |
commit | b62e7979600feee23dc7cdb61042a8fc7673122b (patch) | |
tree | f7351372f37979dd2d048e0b68a16a4cd3b2aadb /docs | |
parent | 1b11b310be61e51b3ac5ebb83f7c8a33aef3d6e8 (diff) | |
download | uscxml-b62e7979600feee23dc7cdb61042a8fc7673122b.zip uscxml-b62e7979600feee23dc7cdb61042a8fc7673122b.tar.gz uscxml-b62e7979600feee23dc7cdb61042a8fc7673122b.tar.bz2 |
Major Refactoring v2.0
Diffstat (limited to 'docs')
-rw-r--r-- | docs/BUILDING.md | 467 | ||||
-rw-r--r-- | docs/COMPARISON.md | 89 | ||||
-rw-r--r-- | docs/CentOS.txt | 47 | ||||
-rw-r--r-- | docs/EXTENSIONS.md | 185 | ||||
-rw-r--r-- | docs/GETTING_STARTED.md | 132 | ||||
-rw-r--r-- | docs/ISSUES.md | 62 | ||||
-rw-r--r-- | docs/NATIVE_CODE.md | 204 | ||||
-rw-r--r-- | docs/OVERVIEW.md | 48 | ||||
-rw-r--r-- | docs/PUBLICATIONS.md | 83 | ||||
-rw-r--r-- | docs/Performance_Microstep.png | bin | 115802 -> 0 bytes | |||
-rw-r--r-- | docs/Ubuntu-LTS.txt | 55 |
11 files changed, 0 insertions, 1372 deletions
diff --git a/docs/BUILDING.md b/docs/BUILDING.md deleted file mode 100644 index 29721b4..0000000 --- a/docs/BUILDING.md +++ /dev/null @@ -1,467 +0,0 @@ -# Building from Source - -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** - -- [General](#general) -- [Build Dependencies](#build-dependencies) -- [Platform Notes](#platform-notes) - - [Mac OSX](#mac-osx) - - [Linux](#linux) - - [Windows](#windows) - - [iOS](#ios) - - [Raspberry Pi](#raspberry-pi) -- [Language Bindings](#language-bindings) - - [Java](#java) - - [CSharp](#csharp) - - [Important Note for Windows](#important-note-for-windows) -- [Optional Functionality](#optional-functionality) -- [About 32/64Bit Support](#about-3264bit-support) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## General - -The source code is built using CMake, the process of building uscxml is -essentially the same on every platform: - -1. Read the <b>[Platform Notes](#platforn-notes)</b> below to prepare your system. -2. Checkout uscxml into a convenient directory: - - <tt>git clone git://github.com/tklab-tud/uscxml.git</tt> - -3. Create a new directory for an *out-of-source* build. I usually create sub-directories -in <tt><USCXML_SRC>/build/</tt>. -4. Run cmake (or ccmake / CMake-GUI) to create the files required by your actual build-system. -5. Use your actual build-system or development environment to build uscxml. -6. Optionally build the [language bindings](#language-bindings) to embed the SCXML interpreter in another language. -7. Read the SCXML draft and have a look at the tests to get started. - -If you want to build for another IDE or build-system, just create a new -*out-of-source* build directory and start over with CMake. To get an idea of -supported IDEs and build-environments on your platform, type <tt>cmake --help</tt> -or run the CMake-GUI and look for the *Generators* section at the end of the -output. Default on Unices is Makefiles. - -<b>Note:</b> If you plan to use Eclipse CDT, you cannot have a build directory anywhere under -the source directory - just create the build directory anywhere else. This only applies to the Eclipse CDT -project generator. - -<b>Note:</b> You cannot build the language bindings with the Visual Studio project as it croaks when calling SWIG, -just have another build directory with the "NMake Makefiles" project generator. - -## Build Dependencies - -Overview of the uscxml dependencies. See the [Platform Notes](#platform-notes) for details. - -<b>Note:</b> We download pre-compiled versions of most dependencies at CMake configure-time. If you want -to provide you own libraries, remove them from <tt><USCXML_SRC>/contrib/prebuilt/</tt> and provide -your own. - -<table> - <tr><th>Platform</th><th>Dependency</th><th>Version</th><th>Comment</th></tr> - <tr> - <td rowspan="10"><b>Everyone</b></td> - <td><a href="http://www.cmake.org/cmake/resources/software.html">CMake</a><br />required</td> - <td>>= 2.8.6</td> - <td>The build-system used for uscxml.</td></tr> - <tr> - <td><a href="http://www.swig.org">SWIG</a><br />optional</td> - <td>>= 2.0.6</td> - <td>Generates language bindings to embed uSCXML in other target languages.</td></tr> - <tr> - <td><a href="http://libevent.org">libevent</a><br />pre-compiled</td> - <td>>= 2.1.x</td> - <td>Event queues with callbacks and the HTTP server.</td></tr> - <tr> - <td><a href="http://curl.haxx.se">curl</a><br />pre-compiled / required</td> - <td>>= 7.29.0</td> - <td>URL downloads.</td></tr> - <tr> - <td><a href="http://code.google.com/p/v8/">v8</a><br />pre-compiled</td> - <td>svn checkout</td> - <td>ECMAScript datamodel implementation.</td></tr> - <tr> - <td><a href="http://www.swi-prolog.org">SWI Prolog</a><br />pre-compiled for unices</td> - <td>>= 6.3.x</td> - <td>Prolog datamodel implementation.</td></tr> - <tr> - <td><a href="http://code.google.com/p/google-glog/">glog</a><br />pre-compiled</td> - <td>>= 0.3.3</td> - <td>Logging library.</td></tr> - <tr> - <td><a href="https://github.com/jezhiggins/arabica">Arabica</a><br />pre-compiled</td> - <td>>= git checkout</td> - <td>XML DOM / XPath / XML Events.</td></tr> - <tr> - <td><a href="http://www.sqlite.org">SQLite</a><br />optional</td> - <td>>= 3.7.15.2</td> - <td>Persistence and sqlite invoker.</td></tr> - <tr> - <td><a href="http://www.openscenegraph.com">OpenSceneGraph</a><br />optional</td> - <td>>= 3.1.X</td> - <td>3D invokers (scenegraph, osgconvert).</td></tr> - <tr> - <td><a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a><br />recommended</td> - <td></td> - <td>Used by <tt>make docs</tt> to generate documentation from source comments.</td></tr> - </tr> - <tr bgcolor="grey"><td bgcolor="#dddddd" colspan="4"></td></tr> - - <tr> - <td rowspan="3"><b>Mac OSX</b></td> - <td><a href="http://developer.apple.com/xcode/">XCode</a><br />required</td> - <td>4.2.1 works</td> - <td>Apples SDK with all the toolchains.</td></tr> - <tr> - <td><a href="http://www.macports.org/">MacPorts</a><br />recommended</td> - <td>>= 2.0.3</td> - <td>Build system for a wide selection of open-source packages.</td></tr> - <tr> - <td><a href="http://www.xmlsoft.org">libxml2</a><br />pre-installed</td> - <td>>= 2.6.16</td> - <td>Actual XML parser used by Arabica.</td></tr> - </tr> - - <tr> - <td rowspan="1"><b>Linux</b></td> - <td><a href="http://www.xmlsoft.org">libxml2</a><br />required</td> - <td>>= 2.6.16</td> - <td>Actual XML parser used by Arabica.</td></tr> - </tr> - - <tr> - <td rowspan="1"><b>Windows</b></td> - <td<a href="http://www.microsoft.com/visualstudio/en-us">Visual Studio 10</a><br />required</td> - <td>v10 pro works</td> - <td>As a student, you can get your version through MSAA.</td></tr> - </tr> -</table> - -## Platform Notes - -The following sections will detail the preparation of the respective platforms to ultimately compile uscxml. - -## Mac OSX - -You will have to install <tt>CMake</tt> via Macports: - - # required dependencies - $ sudo port install cmake - - # optional dependencies for language bindings - $ sudo port install apache-ant swig-java swig-php swig-csharp - - # other optional dependencies - $ sudo port install lua swi-prolog-devel ffmpeg-devel libical expect libpurple OpenSceneGraph-devel protobuf-cpp - -The rest is pre-installed or downloaded at configure-time as pre-compiled libraries. -Just download the source and invoke CMake to create Makefiles or a Xcode project. - -### Console / Make - - $ cd <USCXML_SRCDIR> - $ mkdir -p build/cli && cd build/cli - $ cmake ../.. - [...] - -- Build files have been written to: .../build/cli - $ make - -You can test whether everything works by starting the uscxml-browser with a test.scxml file: - - $ ./bin/uscxml-browser ../../test/uscxml/test-ecmascript.scxml - -### Xcode - - $ cd <USCXML_SRCDIR> - $ mkdir -p build/xcode && cd build/xcode - $ cmake -G Xcode ../.. - [...] - -- Build files have been written to: .../build/xcode - $ open uscxml.xcodeproj - -You can of course reuse the same source directory for many build directories. - -## Linux - -Depending on your distribution, you will most likely have apt-get or yum available as package managers. -If you do not, I'll have to assume that you are knowledgable enough to resolve build dependencies on your own. - -### Preparing *apt-get based* distributions - -This would be all distributions based on Debian, like Ubuntu, Linux Mint and the like. - - # build system and compiler - $ sudo apt-get install git cmake cmake-curses-gui make g++ - - # uscxml required dependencies - $ sudo apt-get install libxml2-dev libcurl4-openssl-dev - -There may still be packages missing due to the set of dependencies among packages -in the various distributons. Try to run CMake and resolve dependencies until you -are satisfied. - -### Preparing *yum based* distributions - -This would be all distributions based on Redhat, e.g. Fedora. - - # build system and compiler - $ sudo yum install git cmake cmake-gui gcc-c++ - - # uscxml required dependencies - $ sudo yum install xml2-devel libcurl-devel - -### Fedora 20 - -Here is a complete walk-through to get uscxml running on Fedora 20, starting with the net installer. - - # get us git and the developer tools - $ sudo yum install git gcc-c++ cmake - - # uscxml required dependencies - $ sudo yum install libxml2-devel libcurl-devel - -This is sufficient to get uscxml to build. If you want some more functionality, install some more libraries: - - # SWI prolog datamodel - $ sudo yum install pl-devel - - # OpenAL invoker - $ sudo yum install openal-soft-devel libsndfile-devel - - # scenegraph and osgconvert invoker - $ sudo yum install OpenSceneGraph-devel mesa-libGL-devel - - # ffmpeg invoker (add repository from http://rpmfusion.org) - $ sudo yum install ffmpeg-devel ffmpeg-compat-devel - - # calendar invoker - $ sudo yum install libical-devel - - # expect invoker - $ sudo yum install expect-devel tk-devel - - # instant messaging invoker - $ sudo yum install libpurple-devel - -### Console / Make - -Instructions are a literal copy of building uscxml for MacOSX on the console from above: - - $ cd <USCXML_SRCDIR> - $ mkdir -p build/cli && cd build/cli - $ cmake ../.. - [...] - -- Build files have been written to: .../build/cli - $ make - -You can test whether everything works by starting the uscxml-browser with a test.scxml file: - - $ ./bin/uscxml-browser ../../test/uscxml/test-ecmascript.scxml - -### Eclipse CDT - -<b>Note:</b> Eclipse does not like the project to be a subdirectory in the source. -You have to choose your build directory with the generated project accordingly. - - $ mkdir -p ~/Desktop/build/uscxml/eclipse && cd ~/Desktop/build/uscxml/eclipse - $ cmake -G "Eclipse CDT4 - Unix Makefiles" <USCXML_SRCDIR> - [...] - -- Build files have been written to: .../build/uscxml/eclipse - -Now open Eclipse CDT and import the out-of-source directory as an existing project into workspace, leaving the "Copy projects -into workspace" checkbox unchecked. There are some more [detailed instruction](http://www.cmake.org/Wiki/Eclipse_CDT4_Generator) available -in the CMake wiki as well. - -## Windows - -Building from source on windows is somewhat more involved and instructions are necessarily in prose form. These -instructions were created using Windows 7 and MS Visual Studio 2010. - -### Prepare compilation - -1. Use git to **checkout** the source from <tt>git://github.com/tklab-tud/uscxml.git</tt> - into any convenient directory. - -2. Start the **CMake-GUI** and enter the checkout directory in the "Where is the source - code" text field. Choose any convenient directory to build the binaries in. - -3. Hit "**Configure**" and choose your toolchain and compiler - I only tested with - Visual Studio 10. Hit "Configure" again until there are no more red items in - the list. If these instructions are still correct and you did as described - above, you should be able to "Generate" the Visual Project Solution. - -Now you can generate the MS Visual Studio project file <tt><USCXML_BUILDIR>/uscxml.sln</tt>. -Just open it up to continue in your IDE. - -<b>Note:</b> We only tested with the MSVC compiler. You can try to compile -with MinGW but you would have to build all the dependent libraries as well. - -<b>Note:</b> We do no provide prebuilt dependencies for MSVC18.x (Visual Studio 2012 / 2013). -You can still use the bindings for C#, but not the native C++ libraries. - -## iOS - -We provide prebuilts and CMake toolchain files for iOS and the iOS simulator. The easiest way to get iOS binaries is -to run: - - $ pwd - <USCXML_SRC> - $ ./contrib/build-scripts/build-uscxml-ios.sh - -This will build uSCXML with the latest iOS SDK that is installed on your system. If you prefer an older SDK, you can -<tt>export IOS_SDK_VERSION=6.1</tt> but you have to make sure it's actually installed. Have a look at the build -script and the toolchain files at <tt>contrib/cmake/CrossCompile-*</tt> if you run into issues. - -The build script above will build a universal binary for simulator and device, both in release and debug configuration. -If you just want a specific configuration for e.g. the simulator, you can invoke CMake yourself: - - $ pwd - <USCXML_SRC> - $ mkdir build/iossim && cd build/iossim - $ cmake -DCMAKE_TOOLCHAIN_FILE=../../contrib/cmake/CrossCompile-iOS-Sim.cmake ../.. - $ make -j4 - -<b>Note</b>: We did not compile the prebuilts for iOS with 64Bit yet. As such, you will not get binaries build for -arm64. The main culprit is, again, curl which assumes the size of an int to be the identical. - -## Raspberry Pi - -To compile uSCXML on Raspberry Pi you will need to, at a minimum, install the following packages. This assumes that -you run Raspberry, the Debian variant. - - $ sudo apt-get install cmake libxml2-dev libcurl4-gnutls-dev - -Now you can compile uSCXML like on any other platform: - - $ git clone --depth 1 https://github.com/tklab-tud/uscxml.git - $ mkdir -p uscxml/build/raspberry && cd uscxml/build/raspberry - $ cmake ../.. - $ make - -If you want an ECMAScript datamodel or LUA, you will need to install additional packages: - - # additional datamodels: ECMAScript, LUA, Prolog - $ sudo apt-get install libjavascriptcoregtk-3.0-dev liblua5.2-dev swi-prolog-nox - - # additional invokers - $ sudo apt-get install libical-dev libpurple-dev libopenal-dev libsndfile1-dev libopenscenegraph-dev - -Lastly, to get the language bindings install SWIG and the developer kits of the respective language. Older Java -versions will work as well (>= 1.5), just make sure <tt>JAVA_HOME</tt> is set correctly. - - # language bindings: Java, CSharp - $ sudo apt-get install swig ant oracle-java8-jdk mono-mcs - $ echo $JAVA_HOME - /usr/lib/jvm/jdk-8-oracle-arm-vfp-hflt - -<b>Note:</b> The version of the V8 JavaScript engine in Raspbian is not compatible with uSCXML. - -## Language Bindings - -In order to build any language bindings, you will need to have SWIG and the development kit of your target language -installed. The set of available language bindings is printed at the end of the CMake invocation: - - $ cmake <USCXML_SRC> - ... - -- Available custom elements ...... : respond file postpone fetch - -- Available language bindings .... : csharp java - -- General information: - ... - -### Java - -We are relying on CMake's [FindJNI.CMake](http://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:FindJNI) module -to find the JNI headers and respective libraries. On unices, it's easiest to check whether <tt>jni.h</tt> is available -in <tt>JAVA_HOME</tt>: - - $ find $JAVA_HOME -name jni.h - /usr/lib/jvm/java-7-openjdk-i386/include/jni.h - -In addition, you will need apache's <tt>ant</tt> in the path or in <tt>$ENV{ANT_HOME}/bin</tt>: - - $ ant -version - Apache Ant(TM) version 1.8.2 compiled on September 22 2011 - -If both of these are given, you ought to get <tt>java</tt> as an available language binding and a new target called -<tt>java</tt> for your build system. If you used plain Makefiles (default on unices), you will get everything you need via: - - $ make && make java - $ ls lib/*.jnilib lib/*.jar - lib/libuscxmlNativeJava64.jnilib lib/uscxml.jar - -The <tt>uscxml.jar</tt> is to be added to your project's classpath, while the <tt>libuscxmlNativeJava64.jnilib</tt> -(or .so, .dll) needs to be loaded <b>once</b> via <tt>System.load()</tt> before you can use native objects. - -### CSharp - -For the CSharp bindings, we need to find either <tt>csc.exe</tt> from the Microsoft.NET framework or <tt>dmcs</tt> -from the mono project. We search the following places for these: - - $ENV{CSC_HOME}; $ENV{DMCS_HOME} - "C:/Windows/Microsoft.NET/Framework/v3.5" - "C:/Windows/Microsoft.NET/Framework/v4.0.30319" - -If we find one of those binaries (and SWIG obviously), we will enable the language bindings. - - $ which dmcs - /opt/local/bin/dmcs - -Again, if you used plain Makefiles, you will get everything you need via: - - $ make && make csharp - $ find lib -type f -iname *csharp* - lib/csharp/libuscxmlNativeCSharp.so - lib/uscxmlCSharp.dll - -The <tt>libuscxmlNativeCSharp.so</tt> has to be available to your C# runtime, either by installing it in -<tt>/usr/local/lib</tt> or (preferred) by using <tt>LD_PRELOAD</tt> or <tt>SetDllDirectory</tt>. See the -embedding examples. The <tt>uscxmlCSharp.dll</tt> contains the managed code portion and needs to be added -to your C# project as a reference. - -<b>Note:</b> You cannot use uSCXML with Xamarin Studio / Mono on Mac out of the box, as they <emph>still</emph> -have no 64Bit support. The last Macintosh without 64Bit support was the (late 2006) Mac Mini with an Intel Core Duo. - -### Important Note for Windows - -You cannot use CMake projects generated for Visual Studio to build the target language specific part of the -various bindings - you have to use <tt>nmake</tt> at a command prompt. Open a <tt>Visual Studio [x64 Win64] -Command Prompt (2010)</tt> and type: - - > cd c:\path\to\build\dir - > cmake -G"NMake Makefiles" c:\path\to\uscxml\source - ... - > nmake && nmake csharp && nmake java - ... - -## Optional Functionality - -At configure time, CMake will search for various libraries and conditionally compile only the part of uSCXML for -which libraries have been found. On unices, it is straight forward to add libraries and - if you installed them to -their default location - CMake will usually pick them up. On Windows, however, the process is more complicated. -While we try to search in the locations where the various installers saved the header files and libraries, there are -some of distributed only as an archive. - -If you want to give CMake the best chance of picking up these libraries, put them into the <emph>platform prebuilt path</emph>. -This path is located in <tt><USCXML_SRC>/contrib/prebuilt/<PLATFORM>/<COMPILER></tt>. For Windows 32bit, -with MSVC this path is <tt><USCXML_SRC>/contrib/prebuilt/windows-x86/msvc</tt>. - -For instance, in order to enable the <tt>lua</tt> datamodel on windows, download the static lua libraries and save -the dll in <tt><PREBUILT>/lib/lua52.lib</tt> and the header files directly in <tt><PREBUILT>/include/</tt>. -When you run CMake for the first time, it will automatically create these paths for you. - -<b>Note:</b> Actually, we would have to differentiate the various MSVC versions as well: v16 (VS2010) and v18 (VS2012/13) -employ a different application binary interface (ABI). This is approach is taken e.g. in uMundo with <tt>msvc16</tt> -vs <tt>msvc18</tt>, but not yet realized for uSCXML. - -## About 32/64Bit Support - -We do support both, 32 and 64Bit for Linux and Windows. On Macintosh, most prebuilt dependencies are compiled as -universal binaries with 32/64Bit but we build 64Bit binaries exclusively. The reason is that e.g. <tt>curl</tt> -cannot be compiled as a universal binary as its header files make assumptions about the size of an int. -Furthermore, most libraries used by invokers are provided by brew or Macports will be 64Bit only and fail to link. - -If you feel adventurous, you can uncomment <tt>set(CMAKE_OSX_ARCHITECTURES "i386;x86_64")</tt> in the topmost -<tt>CMakeLists.txt</tt> and fight your way through the linker errors. -
\ No newline at end of file diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md deleted file mode 100644 index 94e8d3b..0000000 --- a/docs/COMPARISON.md +++ /dev/null @@ -1,89 +0,0 @@ -# Comparison of SCXML Interpreters - -In this document, I will make an attempt to compare and measure the performance -of the various, freely available SCXML interpreters. If you are the author of -one of these interpreters and feel that I misrepresented your work, please do -not hesitate to contact me and I will reevaluate / correct any factual errors. - -This selection is based on the list of available implementations on the [SCXML -wiki](https://en.wikipedia.org/wiki/SCXML) page, plus a few interpreters I know -from the [W3C mailing list](https://lists.w3.org/Archives/Public/www-voice/) -and the [SCXML workshops](http://scxmlworkshop.de). I will list all -interpreters known to me, but only benchmark those that pass the W3C IRP tests -as is required for an actual SCXML interpreter. - -# Methodology - -The benchmarks were performed with a [huge -SCXML](https://github.com/tklab-tud/uscxml/tree/master/test/w3c/compound) file -containing all of the automatic W3C IRP tests that do not rely on timeouts to -pass. - -## scxmlcc - -| Platforms | Tested on | Tested | Website | -|---------------|---------------------|------------------|---------------| -| Linux only | Debian Jessie 64Bit | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [http://scxmlcc.org](http://scxmlcc.org) | - -### How to build - - $ sudo apt-get install build-essential libboost-all-dev autorevision - $ git clone https://github.com/jp-embedded/scxmlcc.git - $ cd scxmlcc/src - $ make - -### Evaluation - - $ ./scxmlcc -i ./test-ecma-all.scxml |sort |uniq - warning: event asteriks not currently supported - warning: event tokens not currently supported - warning: parallel support is not fully implemented/tested - warning: unknown action type 'script' - warning: unknown item 'assign' in <onentry> or <onexit> - warning: unknown item 'assign' in <transition> - warning: unknown item 'cancel' in <transition> - warning: unknown item 'datamodel' in <state> - warning: unknown item 'donedata' in <state> - warning: unknown item 'foreach' in <onentry> or <onexit> - warning: unknown item 'if' in <onentry> or <onexit> - warning: unknown item 'invoke' in <state> - warning: unknown item 'send' in <onentry> or <onexit> - warning: unknown item 'send' in <transition> - -The subset of SCXML implemented in <tt>scxmlcc</tt> is insufficient to run the -performance / compliance benchmarks. - -## SCXML Lab - -| Platforms | Tested on | Tested | Website | -|---------------|---------------------|-----------|---------------| -| HTML5 | Safari 9.0.3 | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [http://www.ling.gu.se/~lager/Labs/SCXML-Lab/](http://www.ling.gu.se/~lager/Labs/SCXML-Lab/) | - -I pasted the file above into their web-frontend and got a <tt>validation-error</tt> - - Unexpected attribute 'datamodel' in <scxml>. Hint: - Valid attributes are: 'id', 'initialstate', 'version', 'xmlns'. - -The <tt>datamodel</tt> is indeed not required for a compliant interpreter, but -we will not be able to pass any meaningful subset of the SCXML IRP tests -without support for a datamodel. - -## Legian - -| Platforms | Tested on | Tested | Website | -|---------------|---------------------|-----------|---------------| -| Java | Java(TM) SE (build 1.8.0_45-b14) | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [https://github.com/pelatimtt/Legian](https://github.com/pelatimtt/Legian/) | - -Does not claim W3C compliance and will, therefore, not pass the compound IRP tests. - -## Qt SCXML Engine - -| Platforms | Tested on | Tested | Website | -|---------------|---------------------|-----------|---------------| -| Any | Mac OSX 10.11.3 with Macports 2.3.4 | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [https://qt.gitorious.org/qt-labs/scxml](https://qt.gitorious.org/qt-labs/scxml/) | - -[No -support](https://qt.gitorious.org/qt-labs/scxml?p=qt-labs:scxml.git;a=blob_plain;f=doc/scxml.qdoc;hb=HEAD) -for <tt><donedata></tt>, <tt><finalize></tt>. Furthermore the -<tt>profile</tt> (now <tt>datamodel</tt> with finalized SCXML recommendation) -attribute is ignored. diff --git a/docs/CentOS.txt b/docs/CentOS.txt deleted file mode 100644 index 8a3424e..0000000 --- a/docs/CentOS.txt +++ /dev/null @@ -1,47 +0,0 @@ -Install CentOS -Minimal Profile -sudo yum install wget -sudo yum groupinstall "Development tools" - - -$ wget http://sourceforge.net/projects/boost/files/latest/download -$ tar xvjf boost* -$ cd boost* -$ ./bootstrap.sh -$ sudo ./b2 --layout=tagged install - -sudo yum install libtool-ltdl-devel libxml2-devel libpng-devel libjpeg-devel libtiff-devel libcurl-devel mesa-libGL-devel pcre-devel -sudo yum remove swig - -$ wget http://sourceforge.net/projects/openvrml/files/latest/download -$ tar xvjf openvrml* -$ cd openvrml* -$ ./configure --disable-render-text-node --disable-script-node-javascript --disable-script-node-java --disable-gl-renderer --disable-xembed --disable-player --disable-examples --disable-mozilla-plugin -$ sudo make install - -$ wget http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz -$ tar xvzf cmake-2.8.10.2.tar.gz -$ cd cmake-2.8.10 -$ ./configure -$ make install - -$ svn co http://www.openscenegraph.org/svn/osg/OpenSceneGraph/tags/OpenSceneGraph-3.1.5 OpenSceneGraph -$ cd OpenSceneGraph -$ mkdir build && cd build -$ cmake .. -$ make -j4 -$ sudo make install - -$ wget http://sourceforge.net/projects/swig/files/latest/download -$ tar xvjf swig* -$ cd swig* -$ ./configure -$ make -$ make install - -$ git clone git://github.com/tklab-tud/uscxml.git -$ cd uscxml -$ mkdir build && cd build -$ cmake .. -$ make - diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md deleted file mode 100644 index 9eb1726..0000000 --- a/docs/EXTENSIONS.md +++ /dev/null @@ -1,185 +0,0 @@ -# Extensions - -## Invokers - -Most platform specific extensions are realized via special invokers. These are components that you can load via: - - <invoke type="invokerName" id="something.unique"> - <param name="paramatername" expr="'paramatervalue'"> - <param name="othername" expr="'othervalue'"> - <content> - <invoker:someXML> - <invoker:here> - </invoker:someXML> - </content> - </invoke> - -When invoked, you can send them events via: - - <send target="#_something.unique"> - <param name="paramatername" expr="'paramatervalue'"> - <param name="othername" expr="'othervalue'"> - </send> - -To get an idea which parameters can be passed for invoke and send, the source as linked below is the ultimate reference. - -<b>Note:</b> Every <tt>expr</tt> attribute is subject to evaluation by the datamodel. If you want to pass a literal string -with the <tt>ecmascript</tt> datamodel, you will have to 'quote' it. - -### FFMPEG - * <b>[FFMPEGInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/ffmpeg/FFMPEGInvoker.cpp)</b> - -### Directory Monitor - * <b>[DirMonInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/filesystem/dirmon/DirMonInvoker.cpp)</b> - -Monitors a directory for modifications. - -<table> - <tr><th colspan="4" align="left">Invoke</th></tr> - <tr><td><tt>type</tt></td><td colspan="3"> - <tt>dirmon</tt><br /> - <tt>DirectoryMonitor</tt><br /> - <tt>http://uscxml.tk.informatik.tu-darmstadt.de/#dirmon</tt> - </td></tr> - <tr><th align="left">param</th><th align="left">expr</th><th align="left">default</th><th align="left">comment</th></tr> - <tr> - <td><tt>dir</tt></td> - <td>A valid system directory</td> - <td>none</td> - <td>Anything that evaluates to a valid directory with the given datamodel</td> - </tr> - <tr> - <td><tt>recurse</tt></td> - <td>"true" or "false"</td> - <td><tt>false</tt></td> - <td>Whether or not to monitor subdirectories as well.</td> - </tr> - <tr> - <td><tt>suffix</tt><br /><tt>suffixes</tt></td> - <td>filename suffixes</td> - <td>all</td> - <td>A single or space-seperated list of suffixes of files that will get reported</td> - </tr> - <tr><td colspan="4"><hr /></td></tr> - <tr><th colspan="4" align="left">Send</th></tr> - <tr> - <td colspan="4">Will not accept anything yet.</td> - </tr> - <tr><td colspan="4"><hr /></td></tr> - <tr><th colspan="4" align="left">Emitted Events</th></tr> - <tr><td>Example</td><td colspan="3"><pre> -'invokeid' => "dirmon.vrml" -'origintype' => "dirmon" -'origin' => "#_dirmon.vrml" -'name' => "file.existing" -'data' ... - 'file' ... - 'atime' => "1361746741" - 'ctime' => "1350452789" - 'dir' => "/Users/sradomski/data" - 'extension' => "wrl" - 'mtime' => "1328012634" - 'name' => "HARD_MP_VAL_035.wrl" - 'path' => "/Users/sradomski/data/HARD_MP_VAL_035.wrl" - 'relPath' => "/HARD_MP_VAL_035.wrl" - 'size' => "1509110"</pre> - </td></tr> - <tr><th align="left">Field</th><th colspan="3" align="left">Details</th></tr> - <tr><td><tt>name</tt></td> - <td colspan="3">One of <tt>file.[existing|added|deleted|modified]</tt></td></tr> - <tr><td><tt>data.file.dir</tt></td> - <td colspan="3">The directory as passed per <tt>dir</tt> param to invoke.</td></tr> - <tr><td><tt>data.file.path</tt></td> - <td colspan="3">The full path to the file we found.</td></tr> - <tr><td><tt>data.file.relPath</tt></td> - <td colspan="3">The relative path starting from <tt>data.file.dir</tt> to the file we found.</td></tr> - <tr><td><tt>data.file.size</tt></td> - <td colspan="3">File size in bytes.</td></tr> - -</table> - -### 3D Scenegraph - * <b>[OSGInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/graphics/openscenegraph/OSGInvoker.cpp)</b> - -Accepts a simplified scenegraph XML notation as content and opens a set of windows with scenes. This invoker registers -as an event listener on the XML in the content and will allow changes to the scenegraph per ecmascript. - - * <b>[OSGConverter.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/graphics/openscenegraph/OSGConverter.cpp)</b> - -Transfer model files into other representations and make screenshots of models. - -### Heartbeat - * <b>[HeartbeatInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/heartbeat/HeartbeatInvoker.cpp)</b> - -Continuously sends events. - -<table> - <tr><th colspan="4" align="left">Invoke</th></tr> - <tr><td><tt>type</tt></td><td colspan="3"> - <tt>heartbeat</tt><br /> - <tt>http://uscxml.tk.informatik.tu-darmstadt.de/#heartbeat</tt> - </td></tr> - <tr><th align="left">param</th><th align="left">expr</th><th align="left">default</th><th align="left">comment</th></tr> - <tr> - <td><tt>interval</tt></td> - <td>e.g. <tt>'3s'</tt> or <tt>'1200ms'</tt></td> - <td>none</td> - <td>A time designation as defined in CSS2</td> - </tr> - <tr> - <td><tt>eventname</tt></td> - <td>The name of the event to send in the given interval</td> - <td>Defaults to <tt>heartbeat.<interval></tt></td> - <td></td> - </tr> - <tr><td colspan="4"><hr /></td></tr> - <tr><th colspan="4" align="left">Send</th></tr> - <tr> - <td colspan="4">Will not accept anything yet.</td> - </tr> - <tr><td colspan="4"><hr /></td></tr> - <tr><th colspan="4" align="left">Emitted Events</th></tr> - <tr><td>Example</td><td colspan="3"><pre> -'invokeid' => "heartbeat" -'origintype' => "heartbeat" -'origin' => "#_heartbeat" -'name' => "heartbeat.100ms" -'data' => "undefined"</pre> - </td></tr> - <tr><th align="left">Field</th><th colspan="3" align="left">Details</th></tr> - <tr><td><tt>name</tt></td> - <td colspan="3">One of <tt>file.[existing|added|deleted|modified]</tt></td></tr> - <tr><td><tt>data.file.dir</tt></td> - <td colspan="3">The directory as passed per <tt>dir</tt> param to invoke.</td></tr> - <tr><td><tt>data.file.path</tt></td> - <td colspan="3">The full path to the file we found.</td></tr> - <tr><td><tt>data.file.relPath</tt></td> - <td colspan="3">The relative path starting from <tt>data.file.dir</tt> to the file we found.</td></tr> - <tr><td><tt>data.file.size</tt></td> - <td colspan="3">File size in bytes.</td></tr> -</table> - -### HTTP Servlet - * <b>[HTTPServletInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/http/HTTPServletInvoker.cpp)</b> - -### SCXML - * <b>[HTTPServletInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/scxml/USCXMLInvoker.cpp)</b> - -### uMundo Publish / Subscribe - * <b>[UmundoInvoker.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/invoker/umundo/UmundoInvoker.cpp)</b> - -## Elements - -### Fetch - * <b>[FetchElement.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/element/fetch/FetchElement.cpp)</b> - -### Postpone - * <b>[PostponeElement.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/element/postpone/PostponeElement.cpp)</b> - -### Response - * <b>[ResponseElement.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/element/response/ResponseElement.cpp)</b> - -## IO Processors - -### BasicHTTP - * <b>[EventIOProcessor.cpp](https://github.com/tklab-tud/uscxml/blob/master/src/uscxml/plugins/ioprocessor/basichttp/libevent/EventIOProcessor.cpp)</b> diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md deleted file mode 100644 index 8c585bf..0000000 --- a/docs/GETTING_STARTED.md +++ /dev/null @@ -1,132 +0,0 @@ -# Getting Started - -In order to use the interpreter, you need to <tt>#include "uscxml/Interpreter.h"</tt> and instantiate -objects of <tt>uscxml::Interpreter</tt>. - -### Non-Blocking Interpretation with SCXML from URL - Interpreter scxml = Interpreter::fromURL("http://www.example.com/fancy.scxml"); - scxml.start(); // non-blocking in own thread - -There are some cases, i.e. with graphical invokers, where the main thread is <emph>required</emph> in order -to react to UI events. You will have to deligate control flow from the main thread into the interpreter -every now and then: - - interpreter.runOnMainThread(25); - -This will perform a single iteration on the invoked components with a maximum of 25 frames per seconds -or return immediately. You will have to call this method every now and then if you are using e.g. the -<tt>scenegraph</tt> invoker. - -<b>Note:</b> Running the interpreter in its own thread via <tt>start</tt> is not exposed into the -language bindings. Just use the threading concepts native to your language to call <tt>step</tt> or -<tt>interpret</tt> as outlined below. - -### Blocking Interpretation with inline SCXML - Interpreter scxml = Interpreter::fromXML("<scxml><final id="exit"/></scxml>"); - scxml.interpret(); // blocking - -When using blocking interpretation, it is assumed that it is running on the main thread and -it will call <tt>runOnMainThread</tt> between stable configurations. - -### Interleaved Interpretation with inline SCXML - Interpreter scxml = Interpreter::fromXML("<scxml><final id="exit"/></scxml>"); - InterpreterState state; - do { - state = interpreter.step(ms); - } while(state != InterpreterState::USCXML_FINISHED) - -Using <tt>step</tt>, you can run a single macrostep of the interpreter and interleave -interpretation with the rest of your code. The <tt>step</tt> function will take an optional integer as -the time in milliseconds it will block and wait if no more events are available, default is to block -indefinitely until an event arrives or the interpreter finished. - -### Callbacks for an Interpreter - -You can register an <tt>InterpreterMonitor</tt> prior to start in order to receive -control-flow upon various events in the Interpreter. - - class StatusMonitor : public uscxml::InterpreterMonitor { - void onStableConfiguration(...) - void beforeCompletion(...) - void afterCompletion(...) - void beforeMicroStep(...) - void beforeTakingTransitions(...) - void beforeEnteringStates(...) - void afterEnteringStates(...) - void beforeExitingStates(...) - void afterExitingStates(...) - }; - - StatusMonitor statMon; - Interpreter scxml = Interpreter::fromXML("<scxml><final id="exit"/></scxml>"); - scxml.addMonitor(&statMon); - scxml.start(); - -This will cause the interpreter to invoke the callbacks from the monitor whenever the corresponding -internal phase is reached. - -## Advanced Topics - -### Embedding uSCXML - -There are bindings for [Java](https://github.com/tklab-tud/uscxml/tree/master/embedding/java) and -[C#](https://github.com/tklab-tud/uscxml/tree/master/embedding/csharp) with some examples in the -<tt>embedding</tt> directory. The bindings consist of two parts each - -1. The C++ uscxml interpreter compiled as a loadable module for the target language and -2. A target language specific module (uscxml.jar / uscxmlCSharp.dll) with the wrapper classes. - -The first one is loaded by the target language (System.loadLibrary / SetDLLDirectory) while the second is to be -included in your actual project. Have a look at the examples in <tt>embedding</tt> and adapt the paths to reflect -your setup. See the [build instructions](https://github.com/tklab-tud/uscxml/blob/master/docs/BUILDING.md) for -details on how to build these. - -### Extending uSCXML - -The uSCXML interpreter can be extended by introducing new - -1. Data models as embedded scripting languages (e.g. ECMAScript, Prolog and XPath) -2. Invokers to represent external components that deliver and accept events (e.g. iCal, SceneGraph, DirectoryMonitor) -3. I/O-Processors to provide communication with external systems (e.g. BasicHTTP, SCXML). -4. Elements for Executable Content (e.g. <respond>, <fetch>, <postpone>). -5. Data model extionsions to establish callbacks from the data model into the host language. - -The basic approach to extend the interpreter is the same in all cases: - -1. Write a class inheriting the abstract base class (e.g. <tt>DataModelImpl</tt>, <tt>InvokerImpl</tt>, <tt>IOProcessorImpl</tt>, <tt>ExecutableContentImpl</tt>). -2. Instantiate your class and register it as a prototype at the <tt>Factory</tt> via one of its static <tt>register*</tt> methods. - 1. You can register at the global Factory Singleton via <tt>Factory::register*(prototypeInstance)</tt> - 2. Or provide a new Factory instance to selected interpreters as an in-between. -3. Write an interpreter using your new functionality. - -<b>Note:</b> Within the language bindings, you will have to inherit the base classes without the <tt>Impl</tt> -suffix. Have a look at the examples in <tt>embedding</tt> for examples. - -#### Ad-hoc Extensions - -Sometimes, it is more suited to provide an interpreter with an already instantiated extension (e.g. an -IOProcessor with an existing connection). In this case, it is somewhat awkward to register a prototype and -have all initialization in its <tt>create(Interpreter interpreter)</tt> method. While you can still dispatch -over the interpreter instance and access information from some global Interpreter->Data map, there is a -more straight-forward approach, e.g. in Java: - - Interpreter interpreter = Intepreter.fromURI(uri); - AdhocIOProcessor ioProc = new AdhocIOProcessor(Whatever youLike); - ioProc.setParameter1(something); - interpreter.addIOProcessor(ioProc); - -This will cause the interpreter to use the given instance for all send requests targeting one of the types -returned by <tt>ioProc.getNames()</tt> and not instantiate an instance via the factory. The instance can -deliver events into the interpreter via <tt>returnEvent(Event e, boolean toInternalQueue = false)</tt>. The same -approach can be used for invokers: - - Interpreter interpreter = Intepreter.fromURI(uri); - TestAdhocInvoker invoker1 = new TestAdhocInvoker(Whatever youLike); - invoker1.setParameter1(something); - interpreter.setInvoker("invokeId", invoker1); - -This will cause the interpreter to use the given instance for a given <tt>invokeId</tt> and not instantiate via -the factory. Similarly, data models can be registered via <tt>interpreter.setDataModel(DataModel dm)</tt>. - -<b>Note:</b> Providing ad-hoc extensions is only supported before the interpreter is started. If you change -instances with a running interpreter, the behavior is undefined.
\ No newline at end of file diff --git a/docs/ISSUES.md b/docs/ISSUES.md deleted file mode 100644 index c5d4ac5..0000000 --- a/docs/ISSUES.md +++ /dev/null @@ -1,62 +0,0 @@ -# Open Issues - -## Ad-hoc extensions are deallocated by their interpreter - -If you register any ad-hoc extension with an interpreter, be it in C++ or a language binding, this extension's -instance <emph>belongs</emph> to the interpreter. This means i.e. that (i) the interpreter's destructor will -deallocate the extension instance, (ii) you cannot reuse it for another interpreter and (iii) you may not call -its destructor. - -For the language bindings, this means furthermore that you have to call <tt>swigReleaseOwnership()</tt> on the -extension instance to prevent the target language's memory management form calling the instances C++ native -destructor. The destructor can only be called once and the interpreter's destructor will do it. - -If allocating additional extension instances per interpreter is expensive, consider using aggregation as a "has a" -relationship with the expensive part. - -## Not all exceptions are propagated into the target languages - -Only exceptions raised during the following methods are propagated into the target language: - - Interpreter::fromXML - Interpreter::fromURI - Interpreter::step - Interpreter::interpret - -If you dig around in the exposed APIs, there are other methods that may raise exceptions (e.g. -<tt>interpreter.getDataModel().eval()</tt>). Be careful when calling these. Ultimately, all exceptions ought to be -propagated into the target language to be handled accordingly. We are currently evaluating different approaches to -do so. - -## Where is the Android Port? - -When I originally tried to compile the required libraries for uSCXML on Android (libevent, curl, libxml2), it would -not work out of the box and I postponed. If there is a demand for an Android port, I can have another look. uSCXML -itself is written in a subset of C++99 and ought to compile just fine. - -## UTF8 support - -Currently, we use <tt>std::string</tt> to represent all strings. This is not a problem as e.g. the ECMAScript -data models will just interpret these as character arrays and handle Unicode respectively. Though it is a problem if -you like to use non-ASCII characters e.g. in the <tt>id</tt> attribute of states. - -## Performance - -The performance of uSCXML depends on many things like the employed data model and the platform it runs on. Using a -MacBook Pro with an Intel i7 @2.4Ghz and the ECMAScript data model (<tt>test/uscxml/test-performance.scxml</tt>), we -achieve about 20.000 events/sec. On a Raspberry Pi, however, only 350 events/sec are achieved. - -If performance ought to be increased further, the first place to look would be most likely the employed DOM -implementation, which uses the rather expensive <tt>dynamic_cast</tt> somewhat too liberally. For a real -performance boost, the explicit SCXML DOM representation at runtime might be dropped in favor of some simple -structs representing the states and transitions. This has been no priority for us so far as even 350 events/sec is -plenty for our use-cases. - -## What about some code documentation? - -Up until recently, the APIs of uSCXML were still subject to rather substantial changes. If there is one thing worse -than no documentation, it is wrong documentation, so we did not document the source. Another stumbling block was the -fact that documentation would not show up in the language bindings. - -Both issues are resolved by now: The APIs have not changed substantially in about 8 month and the new version of SWIG -will allow doxygen comments to be show up in various target languages; so we will document somewhen soon. diff --git a/docs/NATIVE_CODE.md b/docs/NATIVE_CODE.md deleted file mode 100644 index c6f2416..0000000 --- a/docs/NATIVE_CODE.md +++ /dev/null @@ -1,204 +0,0 @@ -# Generating Native Code - -You can use the <tt>uscxml-transform</tt> tool to create native code from an -SCXML document. In this case, you will not use an instance of the -<tt>uscxml::Interpreter</tt> class, but instantiate an SCXML context from a -native description of the state-chart. - -## Embedding ANSI C - -To embed the control flow described within an SCXML document in most variances -of the C language, we provide a transformation onto ANSI C (C89) as a proper -subset of virtually any more modern C/C++ dialect. First, you need to transform -your SCXML state-chart onto ANSI C by invoking <tt>uscxml-transform</tt>: - - $ uscxml-transform -tc -i INPUT_FILE -o OUTPUT_FILE - -This transformation will create a single file that you can compile and link or -include directly. I advice to include the file into another compilation unit -and not to compile it directly, as it allows for more convenience and is -generally a more flexible approach. The file will contain: - -1. A set of pre-processor **macros** for convenience and definitions, all starting -with an <tt>USCXML_</tt> prefix. Of special note are the following macros that -allow you to influence important characteristics of you state-machine. - - * <tt>**USCXML_NR_STATES_TYPE** / **USCXML_NR_TRANS_TYPE**</tt>: - - The type for unsigned integers that is of sufficient size to contain - the number of states / transitions of your largest state machine. The - transformation will automatically choose one of the <tt>uint*_t</tt> - types, though a popular extension, they are only available in C99 - (<tt>stdint.h</tt>). Also, if you like to reuse parts of the file (e.g. - the types below) in another compilation unit, you might need to - predefine them explicitly to a sufficient size. - - * <tt>**USCXML_MAX_NR_STATES_BYTES** / **USCXML_MAX_NR_TRANS_BYTES**</tt>: - - The minimial size for the bit-arrays as <tt>char[N]</tt> containing the - states and transitions in the various types and on the stack during a - microstep. It has to be larger or equal to the smallest positive - integer that, when multiplied by 8 is larger or equal to the number of - states and transitions repsectively. - - In other words, make sure that - <tt>states[USCXML_MAX_NR_STATES_BYTES]</tt> has room for one bit per - state and <tt>transitions[USCXML_MAX_NR_TRANS_BYTES]</tt> for one bit - per transition. - - * <tt>**USCXML_ELEM_X_IS_SET**</tt>: - - These macros are defined for <tt>DATA</tt>, <tt>PARAM</tt> and - <tt>DONEDATA</tt> and allow to iterate instances. For all of the - corresponding SCXML elements, a callback might be supplied with a set - of instances (e.g. <tt>invoke</tt> takes a set of <tt><param></tt> - elements). They are contained in a continuous memory region and can be - iterated by merely increasing the respective pointer. The macros allow - to check whether the pointer is still valid or whether there are no - more instances of the given structure. - - * There are some other macros defined, but they are rather for - micro-optimizations. Have a look at a generated file. - - -2. All compound data **types** (<tt>struct</tt>) to encode an SCXML state-machine. -These will refer to the macros above to require memory for a state-chart's -states and transitions, so make sure that the macros are set if you -conditionally include parts of the generated file and double-check that the -type definitions are the same in every compilation unit if you want to access -state-machines from other units (i.e. same value for macros above!). - -3. The actual **symbols** for one or many state-machines from the input SCXML -file. Their identifiers are all prefixed by an identifier derived from the -content of a given SCXML document. As such, if you transform any given SCXML -document twice, you might end up with duplicate symbols, yet again, the -state-chart's will be functionally identical as they contained the same content. - - In order for not having to guess the prefix when referring to any machine - in user-supplied application code, the tranformation will define three - additional macros: - - #ifndef USCXML_MACHINE - # define USCXML_MACHINE _uscxml_BC220711_machine - #endif - #define USCXML_MACHINE_0 _uscxml_BC220711_machine - #define USCXML_MACHINE_NAME_HERE _uscxml_BC220711_machine - - The first macro is useful if you only transformed a single SCXML - state-chart as it will always refer to the very first state-chart - encountered. If there is more than one SCXML state-chart within a document - (i.e. an invocation of nested machines) you can also refer to them by index - or their eventual name. - -4. Some **helper functions**, most notably bit operations for arbitrary length -bit arrays. - -5. The **micro-step function** <tt>uscxml_step</tt>, which will perform a -micro-step on a given context and delegate control flow accordingly. - -These elements are always contained and you can, selectively, disable their -inclusion by pre-defining respective macros (have a look at a generated source -file). - -Now in order to actually use an SCXML document to manage the control flow among -a set of functions, you will need to allocate and clear memory for a -<tt>uscxml_ctx</tt> structure, set its machine field to a -<tt>uscxml_machine</tt> structure and register user-supplied callbacks. - -### Context Callbacks - -An SCXML interpreter does more than to perform a series of microsteps for an -event over a set of states and transitions and there are quite a few -responsibilities not implemented in the generated ANSI C code. These will be -delegated to user-supplied code via callbacks if they are required for the interpretation of a given SCXML file. - -There is already a scaffolding providing most of the callbacks implemented in -the [test-c-machine.c](../test/src/test-c-machine.c) test file and you can just -isolate the <tt>StateMachine</tt> class contained within. It does everything -but custom invocations but requires linking with <tt>libuscxml</tt> for the -datamodel implementations and several other functions. Depending on the number -of SCXML language features you employ, you can get away with providing -considerably fewer callbacks as detailled below. - -1. **Event Queues**: - - A compliant interpreter is required to maintain two event queues, an - internal and an external one. These queues can grow to arbitrary size and - we made a decision, not to employ <tt>malloc</tt> for heap allocations in - the generated ANSI-C source. As such, it is the responsibility of the - user-supplied code to manage the queues via the following callbacks: - - | Callback | Comments | Required For | - |-|-|-| - | <tt>**dequeue_internal**</tt> | This callback is invoked whenever the interpreter needs an event from the internal event queue. It is passed an instance of a <tt>uscxml_ctx</tt> structure and is supposed to return an opaque pointer to an event. If the internal queue is empty, <tt>NULL</tt> is to be returned. | Dequeuing *internal* events | - | <tt>**dequeue_external**</tt> | This callback is functionally equivalent to <tt>uscxml_ctx.dequeue_internal</tt> but invoked, when an external event is to be dequeued. | Dequeuing *external* events | - | <tt>**exec_content_send**</tt> | Whenever there is an <tt><send></tt> element encountered in executable content, the generated ANSI C code will invoke this callback with a context and an <tt>uscxml_elem_send</tt> instance and the user code registered at the callback is expected to handle the send request as per SCXML recommendation. | Delivering events via <tt><send></tt> | - | <tt>**exec_content_raise**</tt> | This callback is invoked for any <tt><raise></tt> element processed as part of executable content and is expected to deliver an event to the internal event queue. | Delivering events via <tt><raise></tt> | - - The events themselves are represented as opaque pointers and the generated ANSI-C code will never access any of its members. - -2. **Transition Matching / Enabling** - - An event will match and enable a set of transitions. The generated ANSI C - source will already make sure that only valid sets of transitions can be - selected to constitute the optimal transition set for a microstep, but - user-supplied code will have to decide whether a transition is matched and - enabled. - - | Callback | Comments | Required For | - |-|-|-| - | <tt>**is_matched**</tt> | This callback receives a context, an <tt>uscxml_transition</tt> structure and the opaque event pointer. It is expected to return <tt>0</tt> for when the transition is not matched by the given event and <tt>1</tt> if it is. You can assume that non-spontaneous transitions are not checked for the null-event and vice versa. | Event name *matching* of a transition. | - | <tt>**is_enabled**</tt> | This callback receives a context and a <tt>uscxml_transition</tt> structure. It is expected to return <tt>0</tt> for when the transition is not enabled and <tt>1</tt> if it is. Only transitions with an actual <tt>condition</tt> attribute will be checked. | Determining *enabled* status of a transition. | - -3. **Invocations** - - The transformation will generate machine structures for all SCXML - state-charts found within a document, but will make no attempt to invoke - them automatically. Instead, the generated ANSI-C code will call upon the respective callback in the <tt>uscxml_ctx</tt> structure: - - | Callback | Comments | Required For | - |-|-|-| - | <tt>**invoke**</tt> | The call back is provided with a context and an <tt>uscxml_elem_invoke</tt> structure. This structure will contain all the information pertaining to the <tt><invoke></tt> element, with an additional optional member <tt>machine</tt>, which points to the <tt>uscxml_machine</tt> structure in case another, nested SCXML machine is to be invoked. It is your responsibility to create a <tt>uscxml_ctx</tt> for this new machine and run it or start any other type of invocation specified in the given structure. | Invoking external components via <tt><invoke></tt> | - -4. **Executable Content** - - In general, every instance of an element for executable content has a respective callback in the <tt>uscxml_ctx</tt> structure. There are a few examples, wherein an element is transformed onto control flow that will invoke multiple callbacks: - - | Callback | Comments | Required For | - |-|-|-| - | <tt>**exec_content_log**</tt> | | <tt><log></tt> | - | <tt>**exec_content_raise**</tt> | | <tt><raise></tt> | - | <tt>**exec_content_send**</tt> | | <tt><send></tt> | - | <tt>**is_true**</tt> | | <tt><if> / <elseif> / <else></tt> | - | <tt>**exec_content_foreach_init**</tt> <tt>**exec_content_foreach_next**</tt> <tt>**exec_content_foreach_done**</tt> | | <tt><foreach></tt> | - | <tt>**exec_content_assign**</tt> | | <tt><assign></tt> | - | <tt>**exec_content_init**</tt> | | <tt><data></tt> | - | <tt>**exec_content_cancel**</tt> | | <tt><cancel></tt> | - | <tt>**exec_content_script**</tt> | | <tt><script></tt> | - -5. **Done Events** - - Finally, there is a callback that is invoked if a <tt><final></tt> state is entered. - - | Callback | Comments | Required For | - |-|-|-| - | <tt>**raise_done_event**</tt> | The callback is provided with a context, the state for which a done event is to be raised and a <tt>uscxml_elem_donedata</tt> structure. | <tt><final></tt> | - - -### Inline SCXML - -An alternative to writing an external SCXML file is to embed the document into the actual C code as a comment: - - /** INLINE SCXML BEGIN - <scxml name="test-inline" datamodel="native"> - <state id="foo"> - <onentry> - enteredFoo(); - </onentry> - </state> - </scxml> - INLINE SCXML END */ - -If you pass an arbitrary input file to <tt>uscxml_transform</tt>, it will realize that it does not constitute a proper SCXML document and attempt to isolate an actual SCXML state-chart by searching for the string literals <tt>INLINE SCXML BEGIN</tt> and <tt>INLINE SCXML END</tt>. Everything in between is isolated and treated as if it was a proper SCXML document. - -Here, you can also see a variation with the <tt>datamode="native"</tt> attribute. If this is given, the transformation will write any text child of executable content as an unescaped, verbatim string literal into the respective function, allowing you to address any of your C functions and variables directly.
\ No newline at end of file diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md deleted file mode 100644 index e930e80..0000000 --- a/docs/OVERVIEW.md +++ /dev/null @@ -1,48 +0,0 @@ -# uSCXML Developer Overview - -The core concept with uSCXML is a state chart and its syntax with regard to valid elements and attributes is given -in the [SCXML specification](http://www.w3.org/TR/scxml/). uSCXML is standards compliant with the exception of -transitions in history elements which were added rather recently. - -## Events - -To bring a state-chart to life it needs to receive events. After you instantiated and started SCXML interpreter it -will assume a stable configuration and wait for events. You can send events via <tt>interpreter.receive(Event)</tt>. -An event consists (foremost) of the following attributes: - - std::string name; // the name of the event - std::string origin; // where the event originated - std::string origintype; // the type of the event's source - std::string content; // literal string content to be space-normalized - Data data; // complex, JSON-like event data (conflicts with literal string content) - -The first three attributes are available as simple attributes of the datamodel's <tt>_event</tt> object at runtime. If -content is given as a literal string, it will be represented as a space-normalized string in <tt>_event.data</tt>. The -more interesting case is to pass more complex data, in which case, you need to populate the <tt>data</tt> attribute. - -### Data - -The data attribute, as an instance of the Data class contains a nested tree of arbitrary content and can be used to -pass more complex data structures than space-normalized string literals into the interpreter as <tt>_event.data</tt>. - - std::map<std::string, Data> compound; // Associative array, key/value pairs - std::list<Data> array; // Simple array of things - Blob binary; // Binary data - Arabica::DOM::Node<std::string> node; // A DOM node - std::string atom; // String literal or identifier/value, depending on type - Type type; // [VERBATIM | INTERPRETED], - -Not all datamodels support all types of data, e.g. neither the Prolog nor the Lua datamodel support binary data. -When in doubt, you will have to have a look at the <tt>setEvent(Event)</tt> method of the respective datamodel -implementation. The most complete datamodel's in terms of supported types are those with ECMAScript, supporting -Core Level 2 for XML data and TypedArrays to handle binary data. - -When you populate a data object, you can only ever set a single attribute. You can, for example, not set a key in the -compound and an index in the array and expect something meaningful at runtime. For nesting use compound and array, for -scalar data use atom, binary or node. - -### DOM Nodes in the Language Bindings - -We do not wrap DOM nodes into the target language but pass its serialized XML string representation to be reparsed in -the target languages. There are some examples in the <tt>embedding</tt> directory. In order to pass XML via an event, -the Data class in the language bindings support <tt>setXML()</tt>, which will accept a valid XML string.
\ No newline at end of file diff --git a/docs/PUBLICATIONS.md b/docs/PUBLICATIONS.md deleted file mode 100644 index b417b9c..0000000 --- a/docs/PUBLICATIONS.md +++ /dev/null @@ -1,83 +0,0 @@ -# Publications - -### 2015 - -Stefan Radomski. **Formal verification for multimodal dialogs in pervasive -environments**. Ph.D. Thesis, Dec. 2015, Technische Universität Darmstadt, -tuprints. - -Dirk Schnelle-Walka and Stefan Radomski. **Modern standards for VoiceXML in -pervasive multimodal applications**. In International Journal of Mobile Human -Computer Interaction, Hershey, PA, USA, 2015. IGI Global. - -Dirk Schnelle-Walka, Stefan Radomski, J. Barnett, and Max Mühlhäuser. -**Proceedings of the 2nd EICS Workshop on Engineering Interactive Computer -Systems with SCXML**, July 2015. - -Dirk Schnelle-Walka, Stefan Radomski, and Max Mühlhäuser. **Modern standards -for VoiceXML in pervasive multimodal applications**. Emerging Perspectives on -the Design, Use, and Evaluation of Mobile and Handheld Devices, page 22, 2015. - -Dirk Schnelle-Walka, Stephan Radeck-Arneth, and Jürgen Striebinger. -**Multimodal dialog management in a smart home context with SCXML**. 2nd SCXML -Workshop on Engineering Interactive Computer Systems with SCXML, page 10, 2015. - -### 2014 - -Stefan Radomski, Tim Neubacher, and Dirk Schnelle-Walka. **From Harel to -Kripke: A provable datamodel for SCXML**. In EICS2014 Engineering Interactive -Systems with SCXML Workshop Proceedings, 2014. - -Stefan Radomski, Dirk Schnelle-Walka, Torbjörn Lager, Jim Barnett, Deborah -Dahl, and Max Mühlhäuser. **Proceedings of the 1st EICS Workshop on Engineering -Interactive Computer Systems with SCXML**, July 2014. - -Stefan Radomski, Dirk Schnelle-Walka, and Leif Singer. **A debugger for SCXML -documents**. In EICS’14 Workshop on Engineering Interactive Systems with SCXML, -2014. - -Dirk Schnelle-Walka, Stefan Radomski, Stephan Radeck-Arneth, and Max -Mühlhäuser. **Towards an information state update model approach for nonverbal -communication**. In 14th International Conference on Computers Helping People -with Special Needs. Springer, 2014. - -Dirk Schnelle-Walka, Stefan Radomski, and Max Mühlhäuser. **Multimodal fusion -and fission within W3C standards for nonverbal communication with blind -persons**. In 14th International Conference on Computers Helping People with -Special Needs. Springer, 2014. - -### 2013 - -Stefan Radomski and Dirk Schnelle-Walka. **Spatial audio with the W3C -architecture for multimodal interfaces**. In Workshop on Speech in Mobile and -Pervasive Environments 2013, in conjunction with mobileHCI, 2013. - -Stefan Radomski, Dirk Schnelle-Walka, and Stephan Radeck-Arneth. **A Prolog -datamodel for State Chart XML**. In Proceedings of the SIGDIAL 2013 Conference, -pages 127–131, 2013. - -Dirk Schnelle-Walka, Stefan Radomski, and Max Mühlhäuser. **JVoiceXML as a -modality component in the W3C multimodal architecture**. Journal on Multimodal -User Interfaces, pages 1–12, 2013. - -Dirk Schnelle-Walka, Stefan Radomski, and Stephan Radeck-Arneth. -**Probabilistic dialogue management**. In Proceedings of VikingPLoP 2013 -Conference, pages 114–125, 2013. - -### 2012 - -Stefan Radomski and Dirk Schnelle-Walka. **VoiceXML for pervasive -environments**. International Journal of Mobile Human Computer Interaction, -4(2):18–36, 2012. - -Dirk Schnelle-Walka and Stefan Radomski. **Entwicklung multimodaler Anwendungen -mit W3C Standards**. OBJEKTspektrum, 03:28–32, 2012. - -Dirk Schnelle-Walka and Stefan Radomski. **A pattern language for dialogue -management**. In Proceedings of VikingPLoP 2012 Conference, pages 122–141, 2012. - -### 2011 - -Dirk Schnelle-Walka and Stefan Radomski. **Augmenting VoiceXML with information -from pervasive environments**. In Proceedings of SiMPE 2011, Joint Workshop -with mobileHCI, 2011. diff --git a/docs/Performance_Microstep.png b/docs/Performance_Microstep.png Binary files differdeleted file mode 100644 index 50d30d5..0000000 --- a/docs/Performance_Microstep.png +++ /dev/null diff --git a/docs/Ubuntu-LTS.txt b/docs/Ubuntu-LTS.txt deleted file mode 100644 index 632b38a..0000000 --- a/docs/Ubuntu-LTS.txt +++ /dev/null @@ -1,55 +0,0 @@ -Install Ubuntu LTS 12 - -For core functionality without fancy plugins: - -$ sudo apt-get install cmake build-essential libxml2-dev libcurl4-openssl-dev - -For OpenSceneGraph invoker (version in repositories lacks vrml plugin): - -$ sudo apt-get install libpng12-dev libjpeg-dev libboost-all-dev libltdl-dev -$ sudo apt-get install libopenscenegraph-dev # just for the dependencies -$ sudo apt-get remove libopenscenegraph-dev - -$ wget http://sourceforge.net/projects/openvrml/files/latest/download -$ tar xvjf openvrml* -$ cd openvrml* -$ ./configure --disable-render-text-node --disable-script-node-javascript --disable-script-node-java --disable-gl-renderer --disable-xembed --disable-player --disable-examples --disable-mozilla-plugin -$ sudo make install -$ cd .. - -for mavericks: -PNG_CFLAGS="-I/opt/local/include" PNG_LIBS="-L/opt/local/lib" XML_CFLAGS="-I`xcrun --show-sdk-path`/usr/include/libxml2" XML_LIBS="-L`xcrun --show-sdk-path`/usr/lib" CPPFLAGS="--sysroot=`xcrun --show-sdk-path` -I/opt/local/include -I`xcrun --show-sdk-path`/usr/include/libxml2" LDFLAGS="--sysroot=`xcrun --show-sdk-path` -L/opt/local/lib -lboost_system-mt -lxml2 -lpng" ./configure --disable-render-text-node --disable-script-node-javascript --disable-script-node-java --disable-gl-renderer --disable-xembed --disable-player --disable-examples --disable-mozilla-plugin - - -$ sudo apt-get install git -$ git clone https://github.com/openscenegraph/osg -$ cd osg -$ nano src/osgPlugins/vrml/IndexedFaceSet.cpp # Edit line 207 and remove the else block - -$ mkdir build && cd build -$ cmake .. -$ make -j4 -$ sudo make install - -For ffmpeg invoker: - -Follow http://ffmpeg.org/trac/ffmpeg/wiki/UbuntuCompilationGuide for a version of recent version of ffmpeg -on ubuntu. The various libav* packages that come with the distribution are inadequate. - -Install uscxml: -$ git clone https://github.com/tklab-tud/uscxml.git -$ cd uscxml -$ mkdir build && cd build -$ cmake .. -$ make - -Now, to run the VRML server make sure there is an X-Server running for OpenGL to create contexts or run a virtual -X-Server in a framebuffer: - -XVFB_RUNNING=`ps ax |grep 'Xvfb :7' |grep -v grep` -if [ ! "${XVFB_RUNNING}" ]; then - Xvfb :7 -screen 0 800x600x24 & -fi -export DISPLAY=":7" - -$ bin/uscxml-browser -v -t8086 ../apps/samples/vrml/vrml-server.scxml --vrml-path=/scratch/vrml --tmp-path=/scratch/vrml-processed
\ No newline at end of file |