duktape/website/guide/portability.html

<h1 id="portability">Portability</h1>

<h2>Platforms and compilers</h2>

<p>The table below summarizes the platforms and compilers which Duktape is known
to work on, with portability notes where appropriate.  This is <b>not an exhaustive
list</b> of supported/unsupported platforms, rather a list of what is known to work
(and not to work).  Platform and compiler specific issues are discussed in more
detail below the table.</p>

<table>
<thead>
<tr>
<th>Operating system</th>
<th>Compiler</th>
<th>Processor</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Linux</td>
<td>GCC</td>
<td>x86</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>GCC</td>
<td>x64</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>GCC</td>
<td>x32</td>
<td>No known issues, use <code>-mx32</code>.</td>
</tr>
<tr>
<td>Linux</td>
<td>GCC</td>
<td>ARM</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>GCC</td>
<td>MIPS</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>Clang</td>
<td>x86</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>Clang</td>
<td>x64</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>Clang</td>
<td>ARM</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>Clang</td>
<td>MIPS</td>
<td>No known issues.</td>
</tr>
<tr>
<td>Linux</td>
<td>TCC</td>
<td>x64</td>
<td>Zero sign issues (see below).</td>
</tr>
<tr>
<td>FreeBSD</td>
<td>Clang</td>
<td>x86</td>
<td>Aliasing issues with clang 3.3 on 64-bit FreeBSD, <code>-m32</code>, and packed <code>duk_tval</code> (see below).</td>
</tr>
<tr>
<td>FreeBSD</td>
<td>Clang</td>
<td>x64</td>
<td>No known issues.</td>
</tr>
<tr>
<td>NetBSD</td>
<td>GCC</td>
<td>x86</td>
<td>No known issues (NetBSD 6.0).  There are some <code>pow()</code> function incompatibilities on NetBSD, but
    there is a workaround for them.</td>
</tr>
<tr>
<td>OpenBSD</td>
<td>GCC</td>
<td>x86</td>
<td>No known issues (FreeBSD 5.4).</td>
</tr>
<tr>
<td>Windows</td>
<td>MinGW</td>
<td>x86</td>
<td><code>-std=c99</code> recommended, only ISO 8601 date format supported (no platform specific format).</td>
</tr>
<tr>
<td>Windows</td>
<td>MinGW-w64</td>
<td>x64</td>
<td><code>-m64</code>, <code>-std=c99</code> recommended, only ISO 8601 date format supported (no platform specific format).</td>
</tr>
<tr>
<td>Windows</td>
<td>MSVC<br />(Visual Studio Express 2010)</td>
<td>x86</td>
<td>Only ISO 8601 date format supported (no platform specific format).</td>
</tr>
<tr>
<td>Windows</td>
<td>MSVC<br />(Visual Studio Express 2013 for Windows Desktop)</td>
<td>x64</td>
<td>Only ISO 8601 date format supported (no platform specific format).</td>
</tr>
<tr>
<td>Windows</td>
<td>MSVC<br />(Visual Studio 2010)</td>
<td>x64</td>
<td>Only ISO 8601 date format supported (no platform specific format).
    May require explicit <code>DUK_OPT_NO_PACKED_TVAL</code> with
    Duktape 0.10.0.</td>
</tr>
<tr>
<td>Android</td>
<td>GCC<br />(Android NDK)</td>
<td>ARM</td>
<td>No known issues.</td>
</tr>
<tr>
<td>OSX</td>
<td>Clang</td>
<td>x64</td>
<td>Tested on OSX 10.9.2 with XCode.</td>
</tr>
<tr>
<td>Darwin</td>
<td>GCC</td>
<td>x86</td>
<td>No known issues.</td>
</tr>
<tr>
<td>QNX</td>
<td>GCC</td>
<td>x86</td>
<td><code>-std=c99</code> recommended.  Architectures other than x86 should also work.</td>
</tr>
<tr>
<td>AmigaOS</td>
<td>VBCC</td>
<td>M68K</td>
<td>Requires some preprocessor defines, datetime resolution limited to full seconds.</td>
</tr>
<tr>
<td>TOS<br />(Atari ST)</td>
<td>VBCC</td>
<td>M68K</td>
<td>Requires some preprocessor defines, datetime resolution limited to full seconds.</td>
</tr>
<tr>
<td>Emscripten</td>
<td>Emscripten</td>
<td>n/a</td>
<td>Requires additional options, see below. At least V8/NodeJs works.</td>
</tr>
<tr>
<td>Adobe Flash Runtime</td>
<td>CrossBridge<br />(GCC-4.2 with Flash backend)</td>
<td>n/a</td>
<td><code>-std=c99</code> recommended, may need <code>-jvmopt=-Xmx1G</code> if running
    32-bit Java.  Tested with <a href="http://adobe-flash.github.io/crossbridge/">CrossBridge</a>
    1.0.1 on 64-bit Windows 7.</td>
</tr>
<tr>
<td>Linux</td>
<td>BCC<br />(Bruce's C compiler)</td>
<td>i386</td>
<td><code>-3</code> and <code>-ansi</code> required; compiles but doesn't link.  This is an
    old compiler useful for portability torture tests (for instance 16-bit <code>int</code> type).</td>
</tr>
</tbody>
</table>

<h3>Clang</h3>

<p>Clang 3.3 on FreeBSD has some aliasing issues (at least) when using
<code>-m32</code> and when Duktape ends up using a packed <code>duk_tval</code>
value representation type.  You can work around the problem by defining
<code>DUK_OPT_NO_PACKED_TVAL</code> to disable packed value type.  The
problem does not appear in all clang versions.  Duktape self tests cover
this issue (define <code>DUK_OPT_SELF_TESTS</code> when compiling).
See internal test file <code>misc/clang_aliasing.c</code>.</p>

<h3>TCC</h3>

<p>TCC has zero sign handling issues; Duktape mostly works but zero sign is
not handled correctly.  This results in Ecmascript non-compliance, for
instance <code>1/-0</code> evaluates to <code>Infinity</code>, not <code>-Infinity</code>
as it should.</p>

<h3>VBCC (AmigaOS / TOS)</h3>

<p>VBCC doesn't appear to provide OS or processor defines.  To compile for
M68K AmigaOS or TOS you must:</p>
<ul>
<li>Define <code>__MC68K__</code> manually.</li>
<li>Define either <code>AMIGA</code> or <code>__TOS__</code> manually.</li>
</ul>

<p>Datetime resolution is limited to full seconds only when using VBCC on
AmigaOS or TOS.</p>

<h3>Emscripten</h3>

<p>Needs a set of <code>emcc</code> options.  When executed with
V8, the following seem to work:</p>
<ul>
<li><code>-DEMSCRIPTEN</code>: <b>mandatory option</b>, needed by Duktape
    to detect Emscripten.  Without this Duktape may use unaligned accesses
    which Emscripten does not allow.  This results in odd and inconsistent
    behavior, and is not necessarily caught by Duktape self tests.</li>
<li><code>-std=c99</code></li>
<li><code>-O2</code></li>
<li><code>-s ASM_JS=0</code></li>
<li><code>-s MAX_SETJMPS=1000</code></li>
<li><code>-s OUTLINING_LIMIT=20000</code></li>
</ul>

<p>Dukweb is compiled using Emscripten, so you can also check out the Duktape
git repository to see how Dukweb is compiled.</p>

<h2 id="duktape-cplusplus">Duktape and C++</h2>

<p>Duktape works with both C and C++ compilers and applications.  You can
compile Duktape and the application with a C or a C++ compiler in any
combination.  Even so, it is recommended to compile both Duktape and the
application with the same compiler (i.e. both with a C compiler or both
with a C++ compiler) and with the same compiler options.</p>

<p>The <code>duktape.h</code> header contains the necessary glue to make all
of these combinations work.  Specifically, all symbols needed by Duktape
public API are inside a <code>extern "C" { ... }</code> wrapper (active only
if compiled with a C++ compiler).  This ensures that such symbols are defined
and used without C++ name mangling.  Specifically:</p>

<ul>
<li>When compiling Duktape itself with a C++ compiler, symbols needed by
    Duktape public API are not mangled.  Other Duktape internal symbols will
    be mangled, but are not externally visible and should thus cause no
    problems even if the application is compiled with a C compiler.</li>
<li>When compiling an application with a C++ compiler, the wrapper ensures
    that Duktape public API symbols used by the application are looked up
    without mangling.</li>
</ul>

<p>If you mix C and C++ compilation, you should do the final linking with the
C++ toolchain.  At least when mixing gcc/g++ you may encounter something like:</p>
<pre>
$ g++ -c -o duktape.o -Isrc/ src/duktape.c
$ gcc -c -o duk_cmdline.o -Isrc/ examples/cmdline/duk_cmdline.c
$ gcc -o duk duktape.o duk_cmdline.o -lm -lreadline -lncurses
duktape.o:(.eh_frame+0x1ab): undefined reference to `__gxx_personality_v0'
collect2: error: ld returned 1 exit status
</pre>

<p>One fix is to use <code>g++</code> for linking:</p>
<pre>
$ g++ -c -o duktape.o -Isrc/ src/duktape.c
$ gcc -c -o duk_cmdline.o -Isrc/ examples/cmdline/duk_cmdline.c
$ g++ -o duk duktape.o duk_cmdline.o -lm -lreadline -lncurses
</pre>

<p>Because <code>duktape.h</code> selects C/C++ data types needed by
Duktape and also does other feature detection, mixing C and C++ compilers
could theoretically cause the C and C++ compilers to end up with different
active features or data types.  If that were to happen, Duktape and the
application would be binary incompatible (which would be difficult to
diagnose).  This is usually not an issue, but to avoid the potential, compile
Duktape and the application with the same compiler.</p>

<h2>Limitations</h2>

<ul>
<li>The <code>int</code> type is assumed to be at least 32 bits.  This is
    incorrect even on some platforms which provide a 32-bit type.</li>
<li>Pointer less-than/greater-than comparisons are expected to work like
    pointers were unsigned.  This is incorrect on some platforms.</li>
</ul>

<h2>Troubleshooting</h2>

<ul>
<li>Compile in C mode if possible.  Although C++ compilation now works,
    it isn't as portable as C compilation.</li>
<li>Enable C99 mode if possible (<code>-std=c99</code> or similar).  Type
    detection without C99 is less reliable than with C99.</li>
<li>If Duktape compiles but doesn't seem to work correctly, enable
    self tests with <code>DUK_OPT_SELF_TESTS</code>.  Self tests
    detect some compiler and platform issues which cannot be caught
    compile time.</li>
<li>If the target platform has specific alignment requirements and Duktape
    doesn't autodetect the platform correctly, you may need to provide
    either <code>DUK_OPT_FORCE_ALIGN=4</code> or <code>DUK_OPT_FORCE_ALIGN=8</code>.
    The alignment number should match whatever alignment is needed for IEEE
    doubles and 64-bit integer values.</li>
<li>If compilation fails in endianness detection, Duktape probably doesn't
    (yet) support the platform specific endianness headers of your platform.
    Such headers are unfortunately non-standardized, so endianness detection
    is a common (and usually trivial) portability issue on custom platforms.
    Use <code>DUK_OPT_FORCE_BYTEORDER</code> to force endianness as a workaround.
    If you know how the endianness detection should work on your platform,
    please send an e-mail about the issue or contribute a patch.</li>
<li>Another typical portability issue on new platforms is the Date built-in,
    which requires a few platform specific functions for dealing with date and
    time.  Often existing Date functions are sufficient but platform detection
    in <code>duk_features.h</code> does not yet handle the target platform
    correctly.  This is usually trivial to fix; please contribute a patch if
    you do so.  At other times the platform has no standard time APIs (like
    POSIX).  In this case you'll need to add a few platform specific Date
    functions into <code>duk_bi_date.c</code>, and implement platform detection
    into <code>duk_features.h</code>; again, please contribute a patch if you
    do so.  You can look at <code>duk_bi_date.c</code> for POSIX and Windows
    Date API examples.</li>
</ul>