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_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_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 DUK_OPT_NO_FILE_IO.  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>