Skip to content

Latest commit

 

History

History
348 lines (310 loc) · 10.1 KB

Portability.md

File metadata and controls

348 lines (310 loc) · 10.1 KB

Portability

Platforms and compilers

The table below summarizes the platforms and compilers which Duktape is known to work on, with portability notes where appropriate. This is not an exhaustive list 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.

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

Clang

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

MSVC

The /Wp64 (Detect 64-bit Portability Issues) option causes harmless compile warnings when compiling 32-bit code, e.g.:

duk_api.c(2419): warning C4311: 'type cast' : pointer truncation from 'duk_hstring *' to 'duk_uint32_t'

The warnings are caused by Duktape casting 32-bit pointers to 32-bit integers used by its internal value representation. These casts would be incorrect in a 64-bit environment which is reported by the /Wp64 option. When Duktape is compiled in a 64-bit environment a different value representation is used which doesn't use these casts at all, so the warnings are not relevant.

Compilation with /Wall is not clean at the moment.

TCC

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

VBCC (AmigaOS / TOS)

VBCC doesn't appear to provide OS or processor defines. To compile for M68K AmigaOS or TOS you must:

  • Define __MC68K__ manually.

  • Define either AMIGA or __TOS__ manually.

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

Emscripten

Needs a set of emcc options. When executed with V8, the following seem to work:

  • -DEMSCRIPTEN: mandatory option, 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.

  • -std=c99

  • -O2

  • --memory-init-file 0

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

Limitations

  • Pointer less-than/greater-than comparisons are expected to work like pointers were unsigned. This is incorrect on some platforms.

  • Two's complement signed arithmetic is required. This is not technically guaranteed by ANSI C, but there are very few environments where this assumption does not hold.

  • IEEE behavior is assumed for float and double types. This means e.g. gcc -ffast-math (see <https://gcc.gnu.org/wiki/FloatingPointMath) is not supported. Duktape also works directly with IEEE float and double memory representations.

  • ASCII is assumed, Duktape doesn't currently work on e.g. EBCDIC platforms.

Troubleshooting

  • Compile in C mode if possible. Although C++ compilation now works, it isn't as portable as C compilation.

  • Enable C99 mode if possible (-std=c99 or similar). Type detection without C99 is less reliable than with C99. Duktape also relies on (v)snprintf() which are C99/POSIX; there's a fill-in for MSVC but for other non-C99 platforms you may need to define DUK_SNPRINTF() and DUK_VSNPRINTF() manually in your duk_config.h header.

  • If Duktape compiles but doesn't seem to work correctly, enable self tests with DUK_OPT_SELF_TESTS. Self tests detect some compiler and platform issues which cannot be caught compile time.

  • If the target platform has specific alignment requirements and Duktape doesn't autodetect the platform correctly, you may need to provide either DUK_OPT_FORCE_ALIGN=4 or DUK_OPT_FORCE_ALIGN=8. The alignment number should match whatever alignment is needed for IEEE doubles and 64-bit integer values.

  • 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 DUK_OPT_FORCE_BYTEORDER 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.

  • Another typical portability issue on new/exotic 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 if they're not, you can implement an external "Date provider" which requires no Duktape changes, see: datetime.rst.

  • Some exotic platforms have broken double-to-integer or integer-to-double casts, which causes e.g. svaarala/duktape#336. At the moment there's no easy workaround because casts are used inside Duktape in several places. A possible future fix is to use macros for such casts, so that you can fix the casts in a platform dependent manner and edit duk_config.h to provide working casting macros.

  • Since Duktape 1.3 almost all portability related includes and defines are in an external duk_config.h header which you can modify freely to suit exotic platforms.