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

<h2>Overview</h2>

<p>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.</p>

<p>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:</p>

<li>Compile Duktape together with your program without an explicit linking

step.</li>

<li>Compile Duktape as a static library, and link the static library with

your program.</li>

<li>Compile Duktape as a dynamic library, and link the dynamic library with

your program (you'll need <code>DUK_OPT_DLL_BUILD</code>).</li>

<p>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 <code>duktape.h</code> and <code>duktape.c</code>.

The separate source files version consists of <code>duktape.h</code> and

a set of separate source files. The single source file version is preferred,

but separate files work better with some toolchains.</p>

<p>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:</p>

<li><b>Include <code>duktape.h</code> in application code</b>. This is

good practice in general, but without the header your compiler will

incorrectly assume that all Duktape API functions are actual functions

which will cause linking to fail.</li>

<li><b>Compile Duktape and your application with the exactly same Duktape

version</b>. Even compatible versions may be binary incompatible

because a function was changed into a macro or vice versa.</li>

<p>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:</p>

<li><b>Use the same feature options and the same compiler when compiling

Duktape and your application</b>. This is especially important when

Duktape is compiled as a library in a separate step.</li>

<h2>Recommended compiler options</h2>

<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. Recommended compiler options (for GCC/clang, use similar options

in your compiler):</p>

<li><code>-std=c99</code>: recommended to ensure C99 semantics

which improve C type detection and allows Duktape to use variadic

macros</li>

<li><code>-Os</code>: optimize for smallest footprint, which is usually

desired when embedding Duktape</li>

<li><code>-fomit-frame-pointer</code>: omit frame pointer, further reduces

footprint but may interfere with debugging (leave out from debug builds)</li>

<li><code>-fstrict-aliasing</code>: use strict aliasing rules, Duktape

is compatible with these and they improve the resulting C code</li>

<li><code>-DDUK_OPT_DLL_BUILD</code>: needed when Duktape is built as a DLL

(the option is needed for both Duktape and application build)</li>

<p>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.</p>

<h2>Duktape feature defaults</h2>

<p>Duktape feature defaults are, at a high level:</p>

<li>Full Ecmascript E5/E5.1 compliance

(including the optional

<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-B">Annex B</a>

features), except for intentional real world compatibility deviations

(see <a href="#custombehavior">Custom behavior</a>)</li>

<li>Some <a href="#es6features">features borrowed from ES6</a></li>

<li>Packed value representation (8 bytes per value) when available,

unpacked value representation (usually 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>

<p>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.</p>

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

<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. The full list of feature options is described in

<a href="https://github.com/svaarala/duktape/blob/master/doc/feature-options.rst">feature-options.rst</a>.</p>

<div class="note">

If you use Duktape feature options, you must define the feature options both

when compiling Duktape and when compiling any application code using the

<code>duktape.h</code> header. This is necessary because some feature options

affect the binary compatibility of the Duktape API.

<p>The table below summarizes the most commonly needed feature options, in no

particular order:</p>

<th>Define</th>

<th>Description</th>

<td class="definename">DUK_OPT_DLL_BUILD</td>

<td>Build Duktape as a DLL, affects symbol visibility declarations.

Most concretely, enables <code>__declspec(dllexport)</code> and

<code>__declspec(dllimport)</code> on Windows builds. This option

must be used also for application build when Duktape is linked as

a DLL (otherwise <code>__declspec(dllimport)</code> won't be used).</td>

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

<td class="definename">DUK_OPT_FORCE_ALIGN</td>

<td>Use <code>-DDUK_OPT_FORCE_ALIGN=4</code> or <code>-DDUK_OPT_FORCE_ALIGN=8</code>

to force a specific struct/value alignment instead of relying on Duktape's

automatic detection. This shouldn't normally be needed.</td>

<td class="definename">DUK_OPT_FORCE_BYTEORDER</td>

<td>Use this to skip byte order detection and force a specific byte order:

<code>1</code> for little endian, <code>2</code> for ARM "mixed" endian

(integers little endian, IEEE doubles mixed endian), <code>3</code> for

big endian. Byte order detection relies on unstandardized platform

specific header files, so this may be required for custom platforms if

compilation fails in endianness detection.</td>

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

<td class="definename">DUK_OPT_NO_MARK_AND_SWEEP</td>

<td>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).</td>

<td class="definename">DUK_OPT_NO_VOLUNTARY_GC</td>

<td>Disable voluntary periodic mark-and-sweep collection. A mark-and-sweep

collection is still triggered in an out-of-memory condition. This option

should usually be combined with reference counting, which collects all

non-cyclical garbage. Application code should also request an explicit

garbage collection from time to time when appropriate. When this option

is used, Duktape will have no garbage collection pauses in ordinary use,

which is useful for timing sensitive applications like games.</td>

<td class="definename">DUK_OPT_TRACEBACK_DEPTH</td>

<td>Override default traceback collection depth. The default is currently 10.</td>

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

<td class="definename">DUK_OPT_PANIC_HANDLER(code,msg)</td>

<td>Provide a custom panic handler, see detailed description below.</td>

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

<td class="definename">DUK_OPT_ASSERTIONS</td>

<td>Enable internal assert checks. These slow down execution considerably

so only use when debugging.</td>

<h2>Suggested feature options for some environments</h2>

<li id="timing-sensitive-options">Timing sensitive applications, e.g. games: see

<a href="https://github.com/svaarala/duktape/blob/master/doc/timing-sensitive.rst">timing-sensitive.rst</a></li>

<li id="memory-constrained-options">Memory constrained applications: see

<a href="https://github.com/svaarala/duktape/blob/master/doc/low-memory.rst">low-memory.rst</a></li>

<h2>DUK_OPT_PANIC_HANDLER</h2>

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

<a href="https://github.com/svaarala/duktape/blob/master/doc/feature-options.rst">feature-options.rst</a>.</p>

<h2>Memory management alternatives</h2>

<p>There are three supported memory management alternatives:</p>

<li><b>Reference counting and mark-and-sweep (default)</b>: 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.</li>

<li><b>Reference counting only</b>: 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.</li>

<li><b>Mark-and-sweep only</b>: 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.</li>

<p>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 <code>null</code> before deleting

the final reference to the tree.</p>

<p>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 <a href="#limitations">Limitations</a>.</p>

<h2 id="duktape-cplusplus">Using a C++ compiler</h2>

<p>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.</p>

<p>The <code>duktape.h</code> header contains the necessary glue to make all

of these combinations work. Specifically, all symbols needed by Duktape

public API are inside a <code>extern "C" { ... }</code> wrapper (active only

if compiled with a C++ compiler). This ensures that such symbols are defined

and used without C++ name mangling. Specifically:</p>

<li>When compiling Duktape itself with a C++ compiler, symbols needed by

Duktape public API are not mangled. Other Duktape internal symbols will

be mangled, but are not externally visible and should thus cause no

problems even if the application is compiled with a C compiler.</li>

<li>When compiling an application with a C++ compiler, the wrapper ensures

that Duktape public API symbols used by the application are looked up

without mangling.</li>

<p>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:</p>

$ 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

<p>One fix is to use <code>g++</code> for linking:</p>

$ 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

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

<h2>Compiler warnings</h2>

<p>Current goal is for the Duktape compile to be clean when:</p>

<li>using a major compiler (e.g. gcc, clang, MSVC, mingw);</li>

<li>the compiler is in C99 mode; and</li>

<li>warnings are enabled (e.g. <code>-Wall</code> in gcc/clang).</li>

<p>There are still some warnings present when you compile with

<code>-Wextra</code> or equivalent option.</p>

<p>There may be some warnings when compiling with a pre-C99 compiler

(or a C99 compiler without a <code>-std=c99</code> option or similar).</p>