Compiling

Overview

Duktape doesn't have an official Makefile or a build script: given the number of different portability targets, maintaining an official build script would be difficult. Instead, you should add Duktape to your existing build process in whatever way is most natural.

Duktape is compiled with a C or C++ compiler (C99 is recommended) and then linked to your program in some way; the exact details vary between platforms and toolchains. For example, you can:

There are two alternative distribution formats for the Duktape source: a single source file and separate source files. The single source file version consists of duktape.c, duktape.h, and duk_config.h. The separate source files version consists of duktape.h, duk_config.h and a set of separate source files. The single source file version is preferred, but separate files work better with some toolchains.

All Duktape API functions are potentially macros, and the implementation of a certain API primitive may change between a macro and an actual function even between compatible releases. This has two implications:

Duktape has many features which can be controlled during compilation, see feature options below. Some options after binary compatibility of Duktape and the application. Because of this:

Recommended compiler options

If you compile Duktape with no compiler options, Duktape will detect the compiler and the platform automatically and select defaults appropriate in most cases. Recommended compiler options (for GCC/clang, use similar options in your compiler):

If you're using Duktape on a platform where Duktape's automatic feature detection doesn't (yet) work, you may need to force a specific byte order or alignment requirements with feature options described below.

Duktape feature defaults

Duktape feature defaults are, at a high level:

Usually these automatic defaults are OK. If you're working on a constrained platform, you may need to add specific options to reduce memory footprint or to minimize garbage collection pauses.

Feature options (DUK_OPT_xxx)

If you wish to modify the defaults, you can provide feature options in the form of DUK_OPT_xxx compiler defines. These will be taken into account by the default duk_config.h file, which resolves the final internal features based on feature requests, compiler features, and platform features. The full list of feature options is described in Duktape feature options (if you're modifying duk_config.h directly, see Duktape config options).

See Configuring Duktape for build for more practical details.

If you use Duktape feature options, you must define the feature options both when compiling Duktape and when compiling any application code using the duktape.h header. This is necessary because some feature options affect the binary compatibility of the Duktape API.

Suggested feature options for some environments

Timing sensitive options

Timing sensitive applications include e.g. games. For such environments steady, predictable performance is important, often more important than absolute performance. Duktape provides some options to improve use in these environments; for instance, you can disable automatic mark-and-sweep and rely on reference counting and manually requested mark-and-sweep for garbage collection.

See timing-sensitive.rst for suggested feature options.

Memory constrained options

Duktape can work in 256kB flash memory (code footprint) and 96kB system RAM (including Duktape and a minimal OS), and provides a lot of feature options to minimize memory footprint. These feature options are intended for systems with less than 256kB of system RAM.

See low-memory.rst for suggested feature options.

Performance sensitive options

The default Duktape build has reasonable performance options for most environments. Even so there are some feature options which may be used to improve performance by e.g. enabling fast paths, enabling "fastint" support, or trading some API safety for performance.

See performance-sensitive.rst for suggested feature options.

DUK_OPT_PANIC_HANDLER

The default panic handler will print an error message to stdout unless I/O is disabled by DUK_OPT_NO_FILE_IO. It will then call abort() or cause a segfault if DUK_OPT_SEGFAULT_ON_PANIC is defined.

This is not always the best behavior for production applications which may already have better panic recovery mechanisms. To replace the default panic handler, see feature-options.rst.

Memory management alternatives

There are three supported memory management alternatives:

When using only reference counting it is important to avoid creating unreachable reference cycles. Reference cycles are usually easy to avoid in application code e.g. by using only forward pointers in data structures. Even if reference cycles are necessary, garbage collection can be allowed to work simply by breaking the cycles before deleting the final references to such objects. For example, if you have a tree structure where nodes maintain references to both children and parents (creating reference cycles for each node) you could walk the tree and set the parent reference to null before deleting the final reference to the tree.

Unfortunately every Ecmascript function instance is required to be in a reference loop with an automatic prototype object created for the function. You can break this loop manually if you wish. For internal technical reasons, named function expressions are also in a reference loop; this loop cannot be broken from user code and only mark-and-sweep can collect such functions. See Limitations.

Using an external Date provider

When porting to new or exotic platforms the Duktape built-in Date support may not work on the platform. In such a case you can implement an external "Date provider" which allows you to provide the necessary date/time primitives without Duktape changes. See datetime.rst.

Using a C++ compiler

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.

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

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:

$ 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

One fix is to use g++ for linking:

$ 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

Because duktape.h 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.

By default scope-based resource management (sometimes referred to as RAII) won't work in Duktape/C functions because Duktape uses longjmp() for internal long control transfers, bypassing C++ stack unwind mechanisms. You can use DUK_OPT_CPP_EXCEPTIONS to cause Duktape to use C++ exceptions for internal long control transfers, which allows scope-based resource management to work in Duktape/C functions.

Installing Duktape as a system-wide library

Duktape can be installed as a system-wide library; see system-install.rst.

Compiler warnings

Current goal is for the Duktape compile to be clean when:

There are still some warnings present when you compile with -Wextra or equivalent option.

There may be some warnings when compiling with a pre-C99 compiler (or a C99 compiler without a -std=c99 option or similar).