duktape/website/guide/compiling.html

<h2 id="compiling">Compiling</h2>

<h3>Automatic defaults</h3>

<p>If you compile Duktape with no compiler options, Duktape will detect the
compiler and the platform automatically and select defaults appropriate in
most cases.</p>

<p>The default features are, at a high level:</p>
<ul>
<li>Full Ecmascript compliance</li>
<li>Packed value representation (8 bytes per value) when available,
    unpacked value representation (12-16 bytes per value) when not</li>
<li>Reference counting and mark-and-sweep garbage collection</li>
<li>Full error messages and tracebacks</li>
<li>No debug printing, no asserts, etc</li>
</ul>

<h3>Feature options (DUK_OPT_xxx)</h3>

<p>If you wish to modify the defaults, you can provide feature options in the
form of <code>DUK_OPT_xxx</code> compiler defines.  These will be taken into
account by the internal <code>duk_features.h</code> file, which resolves the
final internal features based on feature requests, compiler features, and
platform features.</p>

<p>The available feature options can be found in <code>duk_features.h</code>.
The table below summarizes the available options (in no particular order):</p>

<table>
<thead>
<tr>
<th>Define</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="definename">DUK_OPT_NO_PACKED_TVAL</td>
<td>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.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_NO_REFERENCE_COUNTING</td>
<td>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.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_NO_MS_STRINGTABLE_RESIZE</td>
<td>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.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_NO_AUGMENT_ERRORS</td>
<td>Don't augment Ecmascript error objects with custom fields like
    <code>fileName</code>, <code>lineNumber</code>, and traceback data.
    Implies <code>DUK_OPT_NO_TRACEBACKS</code>.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_NO_TRACEBACKS</td>
<td>Don't record traceback data into Ecmascript error objects (but still record
    <code>fileName</code> and <code>lineNumber</code>).  Reduces footprint and
    makes error handling a bit faster, at the cost of less nformative Ecmascript
    errors.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_NO_VERBOSE_ERRORS</td>
<td>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.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_TRACEBACK_DEPTH</td>
<td>Override default traceback collection depth.  The default is currently 10.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_NO_FILE_IO</td>
<td>Disable use of ANSI C file I/O which might be a portability issue on some
    platforms.  Causes <code>duk_eval_file()</code> to throw an error,
    makes built-in <code>print()</code> and <code>alert()</code> no-ops,
    and suppresses writing of a panic message to <code>stderr</code> on panic.
    This option does not suppress debug printing so don't enable debug printing
    if you wish to avoid I/O.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_SEGFAULT_ON_PANIC</td>
<td>Cause the default panic handler to cause a segfault instead of using
    <code>abort()</code> or <code>exit()</code>.  This is useful when debugging
    with valgrind, as a segfault provides a nice C traceback in valgrind.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_SELF_TESTS</td>
<td>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.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_ASSERTIONS</td>
<td>Enable internal assert checks.  These slow down execution considerably
    so only use when debugging.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_DEBUG</td>
<td>Enable debug printouts.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_DDEBUG</td>
<td>Enable more debug printouts.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_DDDEBUG</td>
<td>Enable even more debug printouts.  Not recommended unless you have
    grep handy.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_DPRINT_COLORS</td>
<td>Enable coloring of debug prints with 
    <a href="http://en.wikipedia.org/wiki/ANSI_escape_code">ANSI escape codes</a>.
    The behavior is not sensitive to terminal settings.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_DPRINT_RDTSC</td>
<td>Print RDTSC cycle count in debug prints if available.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_DEBUG_BUFSIZE</td>
<td>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:
    <code>-DDUK_OPT_DEBUG_BUFSIZE=2048</code>.</td>
</tr>
<tr>
<td class="definename">DUK_OPT_HAVE_CUSTOM_H</td>
<td>Enable user-provided <code>duk_custom.h</code> customization header
    (see below for details).  Not recommended unless really necessary.</td>
</tr>
</tbody>
</table>

<h3>DUK_OPT_HAVE_CUSTOM_H and duk_custom.h</h3>

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

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

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

<h3>DUK_PANIC_HANDLER</h3>

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

<p>You can override the entire panic handler by defining
<code>DUK_PANIC_HANDLER</code>.  For example, you could add the
following to your compiler options:</p>
<pre>
'-DDUK_PANIC_HANDLER(code,msg)={printf("*** %d:%s\n",(code),(msg));abort();}'
</pre>

<p>Or perhaps:</p>
<pre>
'-DDUK_PANIC_HANDLER(code,msg)={my_panic_handler((code),(msg))}'
</pre>

<p>which calls your custom handler:</p>
<pre class="c-code">
void my_panic_handler(int code, const char *msg) {
    /* Your panic handling.  Must not return. */
}
</pre>

<h3>Adding new feature options</h3>

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

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