1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
<!-- HTML header for doxygen 1.8.8-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<!-- For Mobile Devices -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta name="generator" content="Doxygen 1.8.10"/>
<script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
<title>uSCXML: Building from Source</title>
<!--<link href="tabs.css" rel="stylesheet" type="text/css"/>-->
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { init_search(); });
</script>
<link href='https://fonts.googleapis.com/css?family=Roboto+Slab' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css">
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="doxy-boot.js"></script>
</head>
<body>
<nav class="navbar navbar-default" role="navigation">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand">uSCXML 2.0.0</a>
</div>
</div>
</nav>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div class="content" id="content">
<div class="container">
<div class="row">
<div class="col-sm-12 panel " style="padding-bottom: 15px;">
<div style="margin-bottom: 15px;">
<!-- end header part --><!-- Generated by Doxygen 1.8.10 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Building from Source </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#deps">Build Dependencies</a><ul><li class="level2"><a href="#optional-functionality">Optional Functionality</a></li>
</ul>
</li>
<li class="level1"><a href="#platform-notes">Platform Notes</a><ul><li class="level2"><a href="#macosx">Mac OSX</a><ul><li class="level3"><a href="#console-make">Console / Make</a></li>
<li class="level3"><a href="#xcode">Xcode</a></li>
</ul>
</li>
<li class="level2"><a href="#linux">Linux</a><ul><li class="level3"><a href="#apt-get">Preparing apt-get based distributions</a></li>
<li class="level3"><a href="#yum">Preparing yum based distributions</a></li>
<li class="level3"><a href="#console-make2">Console / Make</a></li>
<li class="level3"><a href="#eclipse-cdt">Eclipse CDT</a></li>
</ul>
</li>
<li class="level2"><a href="#windows">Windows</a><ul><li class="level3"><a href="#prepare-windows">Prepare compilation</a></li>
</ul>
</li>
<li class="level2"><a href="#raspberry">Raspberry Pi</a></li>
</ul>
</li>
<li class="level1"><a href="#language-bindings">Language Bindings</a><ul><li class="level2"><a href="#java">Java</a></li>
<li class="level2"><a href="#csharp">CSharp</a></li>
<li class="level2"><a href="#important-windows">Important Note for Windows</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>This page describes how to build uSCXML from source, starting with either a git checkout or from a downloaded archive. The source code is built using CMake and the process of building uscxml is essentially the same on every platform.</p>
<ol type="1">
<li>Read the <b><a href="#platform-notes">Platform Notes</a></b> below to prepare your system.</li>
<li>Checkout uscxml into a convenient directory.</li>
<li>Create a new directory for an <em>out-of-source</em> build. I usually create sub-directories in <code><USCXML_SRC>/build/</code>.</li>
<li>Run cmake (or ccmake / CMake-GUI) to create the files required by your actual build-system.</li>
<li>Use your actual build-system or development environment to build uscxml.</li>
<li>Optionally build the <a href="#language-bindings">language bindings</a> to embed the SCXML interpreter in another language.</li>
<li>Read the SCXML draft and have a look at the tests to get started.</li>
</ol>
<p>For <b>Makefiles on Unices</b>, these steps essentially boil down to: </p><pre class="fragment">$ git clone git://github.com/tklab-tud/uscxml.git
$ mkdir uscxml/build && cd uscxml/build
$ cmake .. && make
</pre><p>For <b>MSVC on Windows</b>, run form a developer command-prompt and substitute the last line above by: </p><pre class="fragment">$ cmake -G "NMake Makefiles" .. && nmake
</pre><p><b>Note:</b> If you want to build for another IDE or build-system, just create a new <em>out-of-source</em> build directory and start over with CMake. To get an idea of supported IDEs and build-environments on your platform, type <code>cmake –help</code> or run the CMake-GUI and look for the <em>Generators</em> section at the end of the output.</p>
<p><b>Note:</b> If you plan to use the Eclipse CDT generator, 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.</p>
<p><b>Note:</b> I could not build the language bindings with the Visual Studio generator as it croaks when calling SWIG, just have another build directory with the "NMake Makefiles" project generator.</p>
<p><b>Note:</b> In order to compile with <code>MinGW</code> on windows you will have to adapt the build scripts in <code>contrib/cmake/Build*</code>. If you succeed, a pull request would be most appreciated.</p>
<h1><a class="anchor" id="deps"></a>
Build Dependencies</h1>
<p>Overview of the uSCXML dependencies. See the <a href="#platform-notes">Platform Notes</a> for details.</p>
<p><b>Note:</b> We no longer maintain and download pre-compiled versions of the dependencies at configure-time. Instead, the build process is using <a href="http://www.kitware.com/media/html/BuildingExternalProjectsWithCMake2.8.html"><code>external_project_add</code></a> to download and compile the required dependencies on your machine.</p>
<table class="doxtable">
<tr>
<th>Platform</th><th>Dependency</th><th>Version</th><th>Comment </th></tr>
<tr>
<td rowspan="7"><b>Everyone</b> </td><td><a href="https://cmake.org/download/">CMake</a><br />
required </td><td>>= 2.8.6 </td><td>The build-system used for uSCXML. </td></tr>
<tr>
<td><a href="http://libevent.org">libevent</a><br />
required / auto-build </td><td>>= 2.0.22 </td><td>Delayed event queues with timed callbacks and the HTTP server. </td></tr>
<tr>
<td><a href="http://curl.haxx.se">curl</a><br />
required / auto-build </td><td>>= 7.48.0 </td><td>URL downloads. </td></tr>
<tr>
<td><a href="https://github.com/jezhiggins/arabica">Xerces-C++</a><br />
required / auto-build </td><td>>= 3.1.3 </td><td>XML Document Object Model </td></tr>
<tr>
<td><a href="http://uriparser.sourceforge.net">uriparser</a><br />
required / auto-build </td><td>>= 0.8.4 </td><td>URL resolving, referring and other operations </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://www.stack.nl/~dimitri/doxygen/">Doxygen</a><br />
optional </td><td>>= 1.8 </td><td>Used by <code>make docs</code> to generate this documentation from source comments. </td></tr>
<tr bgcolor="grey" height="0.5em">
<td bgcolor="#dddddd" colspan="4"></td></tr>
<tr>
<td rowspan="2"><b>Mac OSX</b> </td><td><a href="http://developer.apple.com/xcode/">XCode</a><br />
required </td><td>4.2 works </td><td>Apple's 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><p class="starttd">Build system for a wide selection of open-source packages. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td rowspan="1"><b>Linux</b> </td><td><a href="https://gcc.gnu.org">gcc</a> / <a href="http://clang.llvm.org">clang</a><br />
required </td><td>>= 4.8 / 3.3 </td><td><p class="starttd">C++ compiler with sufficient C++11 support. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td rowspan="1"><b>Windows</b> </td><td><a href="http://www.microsoft.com/visualstudio/en-us">Visual Studio / MSVC</a><br />
required </td><td>>= 2012 </td><td>You <em>need</em> a C++ compiler that understands C++11. </td></tr>
</table>
<h2><a class="anchor" id="optional-functionality"></a>
Optional Functionality</h2>
<p>At configure time, CMake will search for various libraries and conditionally compile only those components of uSCXML for which respective libraries have been found (e.g. the Lua or ECMAScript data-model implementations). On unices, it is straight forward to add libraries and CMake will usually pick them up.</p>
<p>On Windows, however, the process is more complicated. We primarily rely on the official CMake Modules to find the header files and libraries for various packages. This will, usually, take the file system destinations of popular installers into account. When you have trouble getting CMake to find some particular library, have a look at the <code>Find*</code> modules from the CMake distribution and the modules distributed with uSCXML in <code>contrib/cmake/</code> to get an idea where the files are expected.</p>
<h1><a class="anchor" id="platform-notes"></a>
Platform Notes</h1>
<p>The following sections will detail the preparation of the respective platforms to ultimately compile uscxml.</p>
<h2><a class="anchor" id="macosx"></a>
Mac OSX</h2>
<p>You will have to install <code>CMake</code> via Macports: </p><pre class="fragment"># 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 v8
</pre><p>The rest is pre-installed or downloaded and built at configure-time. Just download the source and invoke CMake to create Makefiles or a Xcode project.</p>
<h3><a class="anchor" id="console-make"></a>
Console / Make</h3>
<pre class="fragment">$ cd <USCXML_SRCDIR>
$ mkdir -p build/cli && cd build/cli
$ cmake ../..
[...]
-- Build files have been written to: .../build/cli
$ make
</pre><p>You can test whether everything works by starting the uscxml-browser with a test.scxml file: </p><pre class="fragment">$ ./bin/uscxml-browser ../../test/w3c/null/test436.scxml
</pre><h3><a class="anchor" id="xcode"></a>
Xcode</h3>
<pre class="fragment">$ cd <USCXML_SRCDIR>
$ mkdir -p build/xcode && cd build/xcode
$ cmake -G Xcode ../..
[...]
-- Build files have been written to: .../build/xcode
$ open uscxml.xcodeproj
</pre><p>You can of course reuse the same source directory for many build directories.</p>
<h2><a class="anchor" id="linux"></a>
Linux</h2>
<p>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.</p>
<p><b>Note:</b> If you need the ECMAscript data-model, we advise to use one of the <code>javascriptcoregtk</code> packages as the JavaScriptCore API is far more stable than V8. uSCXML will build with version 3.23 of V8 as it is currently distributed with MacPorts.</p>
<h3><a class="anchor" id="apt-get"></a>
Preparing apt-get based distributions</h3>
<p>This would be all distributions based on Debian, like Ubuntu, Linux Mint and the like. </p><pre class="fragment"># build system and compiler
$ sudo apt-get install git cmake cmake-curses-gui make g++
# uscxml required dependencies (built if not installed)
$ sudo apt-get install libxerces-c-dev libevent-dev libcurl4-openssl-dev
# optional dependencies for language bindings
$ sudo apt-get install ant swig liblua5.2-0-dev mono-devel
</pre><p>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.</p>
<h3><a class="anchor" id="yum"></a>
Preparing yum based distributions</h3>
<p>This would be all distributions based on Redhat, e.g. Fedora. </p><pre class="fragment"># build system and compiler
$ sudo yum install git cmake cmake-gui gcc-c++
# uscxml required dependencies
$ sudo yum install xerces-c-devel libevent-devel libcurl-devel
</pre><h3><a class="anchor" id="console-make2"></a>
Console / Make</h3>
<p>Instructions are a literal copy of building uscxml for MacOSX on the console from above: </p><pre class="fragment">$ cd <USCXML_SRCDIR>
$ mkdir -p build/cli && cd build/cli
$ cmake ../..
[...]
-- Build files have been written to: .../build/cli
$ make
</pre><p>You can test whether everything works by starting the uscxml-browser with a test.scxml file: </p><pre class="fragment">$ ./bin/uscxml-browser ../../test/w3c/null/test436.scxml
</pre><h3><a class="anchor" id="eclipse-cdt"></a>
Eclipse CDT</h3>
<p><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. </p><pre class="fragment">$ 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
</pre><p>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 <a href="http://www.cmake.org/Wiki/Eclipse_CDT4_Generator">detailed instruction</a> available in the CMake wiki as well.</p>
<h2><a class="anchor" id="windows"></a>
Windows</h2>
<p>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 2012.</p>
<h3><a class="anchor" id="prepare-windows"></a>
Prepare compilation</h3>
<ol type="1">
<li>Use git to <b>checkout</b> the source from <code>git://github.com/tklab-tud/uscxml.git</code> into any convenient directory.</li>
<li>Start the <b>CMake-GUI</b> and enter the checkout directory in the "Where is the source code" text field. Choose any convenient directory to build the binaries in.</li>
<li>Hit <b>Configure</b> and choose your toolchain and compiler - I only tested with Visual Studio 12. Hit <b>Configure</b> 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.</li>
</ol>
<p>Now you can generate the MS Visual Studio project file <code><USCXML_BUILDIR>/uscxml.sln</code>. Just open it up to continue in your IDE.</p>
<p><b>Note:</b> We only tested with the MSVC compiler. You can try to compile with MinGW but you would have to conditionalize the <a href="https://github.com/tklab-tud/uscxml/tree/master/contrib/cmake">build scripts</a> for e.g. MinGW.</p>
<h2><a class="anchor" id="raspberry"></a>
Raspberry Pi</h2>
<p>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. </p><pre class="fragment">$ sudo apt-get install cmake libxerces-c libcurl4-gnutls-dev
</pre><p>Now you can compile uSCXML like on any other platform: </p><pre class="fragment">$ git clone --depth 1 https://github.com/tklab-tud/uscxml.git
$ mkdir -p uscxml/build/raspberry && cd uscxml/build/raspberry
$ cmake ../..
$ make
</pre><p>If you want an ECMAScript datamodel or LUA, you will need to install additional packages: </p><pre class="fragment"># additional datamodels: ECMAScript, LUA
$ sudo apt-get install libjavascriptcoregtk-3.0-dev liblua5.2-dev
</pre><p>Finally, 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 <code>JAVA_HOME</code> is set correctly. </p><pre class="fragment"># 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
</pre><h1><a class="anchor" id="language-bindings"></a>
Language Bindings</h1>
<p>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: </p><pre class="fragment">$ cmake <USCXML_SRC>
...
-- Available custom elements ...... : respond file postpone fetch
-- Available language bindings .... : csharp java
-- General information:
...
</pre><h2><a class="anchor" id="java"></a>
Java</h2>
<p>We are relying on CMake's <a href="http://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:FindJNI">FindJNI.CMake</a> module to find the JNI headers and respective libraries. On unices, it's easiest to check whether <code>jni.h</code> is available in <code>JAVA_HOME</code>: </p><pre class="fragment">$ find $JAVA_HOME -name jni.h
/usr/lib/jvm/java-7-openjdk-i386/include/jni.h
</pre><p>In addition, you will need apache's <code>ant</code> in the path or in <code>$ENV{ANT_HOME}/bin</code>: </p><pre class="fragment">$ ant -version
Apache Ant(TM) version 1.8.2 compiled on September 22 2011
</pre><p>If both of these are given, you ought to get <code>java</code> as an available language binding and a new target called <code>java</code> for your build system. If you used plain Makefiles (default on unices), you will get everything you need via: </p><pre class="fragment">$ make && make jar
$ ls lib/*.jnilib lib/*.jar
lib/libuscxmlNativeJava64.jnilib lib/uscxml.jar
</pre><p>The <code>uscxml.jar</code> is to be added to your project's classpath, while the <code>libuscxmlNativeJava64.jnilib</code> (or .so, .dll) needs to be loaded <b>once</b> via <code>System.load()</code> before you can use native objects.</p>
<h2><a class="anchor" id="csharp"></a>
CSharp</h2>
<p>For the CSharp bindings, we need to find either <code>csc.exe</code> from the Microsoft.NET framework or <code>dmcs</code> from the mono project. We search the following places for these: </p><pre class="fragment">$ENV{CSC_HOME}; $ENV{DMCS_HOME}
"C:/Windows/Microsoft.NET/Framework/v3.5"
"C:/Windows/Microsoft.NET/Framework/v4.0.30319"
</pre><p>If we find one of those binaries (and SWIG obviously), we will enable the language bindings. </p><pre class="fragment">$ which dmcs
/opt/local/bin/dmcs
</pre><p>Again, if you used plain Makefiles, you will get everything you need via: </p><pre class="fragment">$ make && make csharp
$ find lib -type f -iname *csharp*
lib/csharp/libuscxmlNativeCSharp.so
lib/uscxmlCSharp.dll
</pre><p>The <code>libuscxmlNativeCSharp.so</code> has to be available to your C# runtime, either by installing it in <code>/usr/local/lib</code> or (preferred) by using <code>LD_PRELOAD</code> or <code>SetDllDirectory</code>. See the embedding examples. The <code>uscxmlCSharp.dll</code> contains the managed code portion and needs to be added to your C# project as a reference.</p>
<p><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.</p>
<h2><a class="anchor" id="important-windows"></a>
Important Note for Windows</h2>
<p>You cannot use CMake projects generated for Visual Studio to build the target language specific part of the various bindings - you have to use <code>nmake</code> at a command prompt. Open a <code>Visual Studio [x64 Win64] Command Prompt (2012)</code> and type: </p><pre class="fragment">> cd c:\path\to\build\dir
> cmake -G"NMake Makefiles" c:\path\to\uscxml\source
...
> nmake && nmake csharp && nmake jar
...</pre> </div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.8-->
<!-- start footer part -->
</div>
</div>
</div>
</div>
</div>
<!-- <hr class="footer"/><address class="footer"><small>
Generated on Mon Dec 12 2016 19:50:05 for uSCXML by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.10
</small></address> -->
</body>
</html>
|
