Compiling

Automatic defaults

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):

• -std=c99: recommended to ensure C99 semantics which improve C type detection and allows Duktape to use variadic macros (without these you may get harmless compiler warnings because of the way Duktape works around the lack of variadic macros)
• -Os: optimize for smallest footprint, which is usually desired when embedding Duktape
• -fomit-frame-pointer: omit frame pointer, further reduces footprint but may interfere with debugging (leave out from debug builds)
• -fstrict-aliasing: use strict aliasing rules, Duktape is compatible with these and they improve the resulting C code

Duktape feature defaults are, at a high level:

• Full Ecmascript compliance (including the optional Annex B features), except for intentional real world compatibility deviations (see Custom behavior)
• Packed value representation (8 bytes per value) when available, unpacked value representation (12-16 bytes per value) when not
• Reference counting and mark-and-sweep garbage collection
• Full error messages and tracebacks
• No debug printing, no asserts, etc

Usually the automatic defaults are OK. 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.

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 internal duk_features.h file, which resolves the final internal features based on feature requests, compiler features, and platform features.

The available feature options can be found in duk_features.h. The table below summarizes the available options, in no particular order:

Suggested feature options for some environments

Timing sensitive applications (e.g. games)

• Use the default memory management settings (reference counting and mark-and-sweep) but enable DUK_OPT_NO_VOLUNTARY_GC to eliminate mark-and-sweep pauses. Use explicit GC calls (either duk_gc() from C or Duktape.gc() from Ecmascript) when possible to collect circular references.

Memory constrained applications

• Use the default memory management settings: although reference counting increases heap header size, it also reduces memory usage fluctuation which is often more important than absolute footprint.
• Reduce error handling footprint with one or more of: DUK_OPT_NO_AUGMENT_ERRORS, DUK_OPT_NO_TRACEBACKS, DUK_OPT_NO_VERBOSE_ERRORS, DUK_OPT_NO_PC2LINE.
• If you don't need the Duktape-specific additional JSONX/JSONC formats, use both DUK_OPT_NO_JSONX and DUK_OPT_NO_JSONC.
• If you don't need regexp support, use DUK_OPT_NO_REGEXP_SUPPORT.
• Duktape debug code uses a large, static temporary buffer for formatting debug log lines. Use e.g. -DDUK_OPT_DEBUG_BUFSIZE=2048 to reduce this overhead.

DUK_OPT_HAVE_CUSTOM_H and duk_custom.h

Normally you define DUK_OPT_xxx feature options and the internal duk_features.h header resolves these with platform/compiler constraints to determine effective compilation options for Duktape internals. The effective options are provided as DUK_USE_xxx defines which you normally never see.

If you define DUK_OPT_HAVE_CUSTOM_H, Duktape will include duk_custom.h after determining the appropriate DUK_USE_xxx defines but before compiling any code. The duk_custom.h header, which you provide, can then tweak the active DUK_USE_xxx defines freely. See duk_features.h for the available defines.

This approach is useful when the DUK_OPT_xxx feature options don't provide enough flexibility to tweak the build. The downside is that you can easily create inconsistent DUK_USE_xxx flags, the customization header will be version specific, and you need to peek into Duktape internals to know what defines to tweak.

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.

You can override the entire panic handler by defining DUK_OPT_PANIC_HANDLER. For example, you could add the following to your compiler options:

'-DDUK_OPT_PANIC_HANDLER(code,msg)={printf("*** %d:%s\n",(code),(msg));abort();}'

You can also use:

'-DDUK_OPT_PANIC_HANDLER(code,msg)={my_panic_handler((code),(msg))}'

which calls your custom handler:

void my_panic_handler(int code, const char *msg) {
    /* Your panic handling.  Must not return. */
}

The DUK_OPT_PANIC_HANDLER macro is used internally by Duktape, so your panic handler function needs to be declared for Duktape compilation to avoid compiler warnings about undeclared functions. You can "inject" a declaration for your function into Duktape compilation with:

'-DDUK_OPT_DECLARE=extern void my_panic_handler(int code, const char *msg);'

After this you might still get a compilation warning like "a noreturn function must not return" as the compiler doesn't know your panic handler doesn't return. You can fix this by either using a (compiler specific) "noreturn" declaration, or by modifying the panic handler macro to something like:

'-DDUK_OPT_PANIC_HANDLER(code,msg)={my_panic_handler((code),(msg));abort()}'

As abort() is automatically a "noreturn" function the panic macro body can no longer return. Duktape always includes stdlib.h which provides the abort() prototype so no additional include files are needed.

Adding new feature options

This section only applies if you customize Duktape internals and wish to submit a patch to be included in the mainline distribution:

• Add a descriptive DUK_OPT_xxx for the custom feature. The custom feature should only be enabled if the feature option is explicitly given.
• Modify duk_features.h to detect your custom feature option and define appropriate internal DUK_USE_xxx define(s). Conflicts with other features should be detected. Code outside duk_features.h should only listen to DUK_USE_xxx defines so that the resolution process is fully contained in duk_features.h.

Memory management alternatives

There are three supported memory management alternatives:

• Reference counting and mark-and-sweep (default): heap objects are freed immediately when they become unreachable except for objects participating in unreachable reference cycles. Such objects are freed by a periodic voluntary, stop the world mark-and-sweep collection. Mark-and-sweep is also used as the emergency garbage collector if memory allocation fails.
• Reference counting only: reduces code footprint and eliminates garbage collection pauses, but objects in unreachable reference cycles are not collected until the Duktape heap is destroyed. This alternative is not recommended unless the reference cycles are not an issue. See notes below.
• Mark-and-sweep only: reduces code footprint and memory footprint (heap headers don't need to store a reference count), but there is more memory usage variance than in the default case. The frequency of voluntary, stop the world mark-and-sweep collections is also higher than in the default case where reference counting is expected to handle almost all memory management.

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.

Compiler warnings

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

• using a major compiler (e.g. gcc, clang, MSVC, mingw);
• the compiler is in C99 mode; and
• warnings are enabled (e.g. -Wall in gcc/clang).

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

When your compiler is not C99 compliant, Duktape uses an awkward replacement for variadic macros. This may cause, as a side effect, a lot of harmless warnings if you set the compiler warning level too high. This is difficult to fix, so C99 compilation may not be clean at the moment.