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.

The default features are, at a high level:

Full Ecmascript compliance (including the optional Annex B features)
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

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

Define	Description
DUK_OPT_NO_PACKED_TVAL	Don't use the packed 8-byte internal value representation even if otherwise possible. The packed representation has more platform/compiler portability issues than the unpacked one.
DUK_OPT_NO_REFERENCE_COUNTING	Disable reference counting and use only mark-and-sweep for garbage collection. Although this reduces memory footprint of heap objects, the downside is much more fluctuation in memory usage.
DUK_OPT_NO_MARK_AND_SWEEP	Disable mark-and-sweep and use only reference counting for garbage collection. This reduces code footprint and eliminates garbage collection pauses, but objects participating in unreachable reference cycles won't be collected until the Duktape heap is destroyed. In particular, function instances won't be collected because they're always in a reference cycle with their default prototype object. Unreachable objects are collected if you break reference cycles manually (and are always freed when a heap is destroyed).
DUK_OPT_NO_MS_STRINGTABLE_RESIZE	Disable forced string intern table resize during mark-and-sweep garbage collection. This may be useful when reference counting is disabled, as mark-and-sweep collections will be more frequent and thus more expensive.
DUK_OPT_GC_TORTURE	Development time option: force full mark-and-sweep on every allocation to stress test memory management.
DUK_OPT_NO_AUGMENT_ERRORS	Don't augment Ecmascript error objects with custom fields like `fileName`, `lineNumber`, and traceback data. Implies `DUK_OPT_NO_TRACEBACKS`.
DUK_OPT_NO_TRACEBACKS	Don't record traceback data into Ecmascript error objects (but still record `fileName` and `lineNumber`). Reduces footprint and makes error handling a bit faster, at the cost of less nformative Ecmascript errors.
DUK_OPT_NO_VERBOSE_ERRORS	Don't provide error message strings or filename/line information for errors generated by Duktape. Reduces footprint, at the cost of much less informative Ecmascript errors.
DUK_OPT_TRACEBACK_DEPTH	Override default traceback collection depth. The default is currently 10.
DUK_OPT_NO_FILE_IO	Disable use of ANSI C file I/O which might be a portability issue on some platforms. Causes `duk_eval_file()` to throw an error, makes built-in `print()` and `alert()` no-ops, and suppresses writing of a panic message to `stderr` on panic. This option does not suppress debug printing so don't enable debug printing if you wish to avoid I/O.
DUK_OPT_SEGFAULT_ON_PANIC	Cause the default panic handler to cause a segfault instead of using `abort()` or `exit()`. This is useful when debugging with valgrind, as a segfault provides a nice C traceback in valgrind.
DUK_OPT_SELF_TESTS	Perform run-time self tests when a Duktape heap is created. Catches platform/compiler problems which cannot be reliably detected during compile time. Not enabled by default because of the extra footprint.
DUK_OPT_ASSERTIONS	Enable internal assert checks. These slow down execution considerably so only use when debugging.
DUK_OPT_DEBUG	Enable debug printouts.
DUK_OPT_DDEBUG	Enable more debug printouts.
DUK_OPT_DDDEBUG	Enable even more debug printouts. Not recommended unless you have grep handy.
DUK_OPT_DPRINT_COLORS	Enable coloring of debug prints with ANSI escape codes. The behavior is not sensitive to terminal settings.
DUK_OPT_DPRINT_RDTSC	Print RDTSC cycle count in debug prints if available.
DUK_OPT_DEBUG_BUFSIZE	Debug code uses a static buffer as a formatting temporary to avoid side effects in debug prints. The static buffer is large by default, which may be an issue in constrained environments. You can set the buffer size manually with this option. Example: `-DDUK_OPT_DEBUG_BUFSIZE=2048`.
DUK_OPT_HAVE_CUSTOM_H	Enable user-provided `duk_custom.h` customization header (see below for details). Not recommended unless really necessary.

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_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_PANIC_HANDLER. For example, you could add the following to your compiler options:

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

Or perhaps:

'-DDUK_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. */
}

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. See note below on function instances and reference cycles.
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, by default, in a reference loop with an automatic prototype object created for the object. The function instance's prototype property points to the prototype object, and the prototype's constructor property points back to the function instance. Only mark-and-sweep is able to collect these reference loops at the moment. If you build with reference counting only, function instances may appear to leak memory; the memory will be released when the relevant heap is destroyed. You can also break the reference loops manually (although this is a bit cumbersome):

var f = function() { };
var g = function() { };
var h = function() { };
__duk__.setFinalizer(f, function() { print('finalizer for f'); });
__duk__.setFinalizer(g, function() { print('finalizer for g'); });
__duk__.setFinalizer(h, function() { print('finalizer for h'); });

// not collected until heap destruction in a reference counting only build
f = null;            // not collected immediately

// break cycle by deleting 'prototype' reference (alternative 1)
g.prototype = null;
g = null;            // collected immediately, finalizer runs

// break cycle by deleting 'constructor' reference (alternative 2)
h.prototype.constructor = null;
h = null;            // collected immediately, finalizer runs

// no-op with refcount only, with mark-and-sweep finalizer for 'f' runs
__duk__.gc();