Skip to content

Latest commit

 

History

History
172 lines (151 loc) · 6.48 KB

Configuring1x.md

File metadata and controls

172 lines (151 loc) · 6.48 KB
Raw

Configuring Duktape 1.x for build

Duktape 1.3 to 1.7

In Duktape 1.3 there are three supported ways of configuring Duktape features for build:

  • Use the duk_config.h in the distributable (src/duk_config.h or src-separate/duk_config.h). If default features are not desirable, provide DUK_OPT_xxx feature options when compiling both Duktape and the application. This matches Duktape 1.2, but there's an external duk_config.h header:

    # src/ contains default duk_config.h (comes with distributable)
$ gcc -std=c99 -Os -o hello -Isrc -DDUK_OPT_FASTINT \
        src/duktape.c hello.c -lm

  • Generate a new autodetect duk_config.h using genconfig with config option overrides given either on the command line or in YAML/header files. For example, to enable fastint support and to disable bufferobjects:

    $ sudo apt-get install python-yaml

$ python config/genconfig.py \
        --metadata config/genconfig_metadata.tar.gz \
        --output myinclude/duk_config.h \
        -DDUK_USE_FASTINT \
        -UDUK_USE_BUFFEROBJECT_SUPPORT \
        autodetect-header

# Ensure myinclude/duk_config.h comes first in include path.
$ gcc -std=c99 -Os -o hello -Imyinclude -Isrc \
        src/duktape.c hello.c -lm

    There are several alternatives to defining option overrides, see: https://github.com/svaarala/duktape/blob/master/doc/duk-config.rst#genconfig-option-overrides

  • Edit duk_config.h manually. This is a bit messy but allows everything to be modified, e.g. typedefs and #include directives.

Duktape 1.2

In Duktape 1.2 Duktape features are configured through feature options:

  • If defaults are acceptable, compile Duktape as is. For example:

    $ gcc -std=c99 -Os -o hello -Isrc src/duktape.c hello.c -lm

  • Otherwise use DUK_OPT_xxx feature options on the compiler command line when compiling both Duktape and your application (if they're compiled separately). For example:

    $ gcc -std=c99 -Os -o hello -Isrc -DDUK_OPT_FASTINT \
        src/duktape.c hello.c -lm

    For available feature options, see: https://github.com/svaarala/duktape/blob/master/doc/feature-options.rst

  • When compiling Duktape as a Windows DLL, you must define DUK_OPT_DLL_BUILD for both Duktape and application build. For example:

    > cl /O2 /W3 /DDUK_OPT_DLL_BUILD /Isrc /LD src\duktape.c
> cl /O2 /W3 /DDUK_OPT_DLL_BUILD /Fehello.exe /Isrc hello.c duktape.lib
> hello.exe

The table below summarizes the most commonly needed feature options, in no particular order:

Define Description
DUK_OPT_DLL_BUILD Build Duktape as a DLL, affects symbol visibility declarations. Most concretely, enables __declspec(dllexport) and __declspec(dllimport) on Windows builds. This option must be used also for application build when Duktape is linked as a DLL (otherwise __declspec(dllimport) won't be used).
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_FORCE_ALIGN Use -DDUK_OPT_FORCE_ALIGN=4 or -DDUK_OPT_FORCE_ALIGN=8 to force a specific struct/value alignment instead of relying on Duktape's automatic detection. This shouldn't normally be needed.
DUK_OPT_FORCE_BYTEORDER Use this to skip byte order detection and force a specific byte order: 1 for little endian, 2 for ARM "mixed" endian (integers little endian, IEEE doubles mixed endian), 3 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.
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_VOLUNTARY_GC 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.
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_PANIC_HANDLER(code,msg) Provide a custom panic handler, see detailed description below.
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.