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.
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:
DUK_OPT_DLL_BUILD
).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 duktape.c
, duktape.h
, and
duk_config.h
. The separate source files version consists of
duktape.h
, duk_config.h
and a set of separate
source files. The single source file version is preferred, but separate
files work better with some toolchains.
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:
duktape.h
in application code. 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.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:
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):
-std=c99
: recommended to ensure C99 semantics
which improve C type detection and allows Duktape to use variadic
macros-Os
: optimize for smallest footprint, which is usually
desired when embedding Duktape-fomit-frame-pointer
: omit frame pointer, further reduces
footprint but may interfere with debugging (leave out from debug builds)-fstrict-aliasing
: use strict aliasing rules, Duktape
is compatible with these and they improve the resulting C code-DDUK_OPT_DLL_BUILD
: needed when Duktape is built as a DLL
(the option is needed for both Duktape and application build)setjmp()
and longjmp()
(or their variants) for internal long control transfers. If you're
compiling with a C++ compiler you may want to use
DUK_OPT_CPP_EXCEPTIONS
which causes Duktape to use C++
exceptions for long control transfers and allows scope-based resource
management (automatic destructors, etc) in Duktape/C functions to work
as expected.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.
Duktape feature defaults are, at a high level:
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.
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 default duk_config.h
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
Duktape feature options
(if you're modifying duk_config.h
directly, see
Duktape config options).
See Configuring Duktape for build for more practical details.
duktape.h
header. This is necessary because some feature options
affect the binary compatibility of the Duktape API.
Timing sensitive applications include e.g. games. For such environments steady, predictable performance is important, often more important than absolute performance. Duktape provides some options to improve use in these environments; for instance, you can disable automatic mark-and-sweep and rely on reference counting and manually requested mark-and-sweep for garbage collection.
See timing-sensitive.rst for suggested feature options.
Duktape can work in 256kB flash memory (code footprint) and 96kB system RAM (including Duktape and a minimal OS), and provides a lot of feature options to minimize memory footprint. These feature options are intended for systems with less than 256kB of system RAM.
See low-memory.rst for suggested feature options.
The default Duktape build has reasonable performance options for most environments. Even so there are some feature options which may be used to improve performance by e.g. enabling fast paths, enabling "fastint" support, or trading some API safety for performance.
See performance-sensitive.rst for suggested feature options.
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.
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 feature-options.rst.
There are three supported memory management alternatives:
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 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 Limitations.
When porting to new or exotic platforms the Duktape built-in Date support may not work on the platform. In such a case you can implement an external "Date provider" which allows you to provide the necessary date/time primitives without Duktape changes. See datetime.rst.
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.
The duktape.h
header contains the necessary glue to make all
of these combinations work. Specifically, all symbols needed by Duktape
public API are inside a extern "C" { ... }
wrapper (active only
if compiled with a C++ compiler). This ensures that such symbols are defined
and used without C++ name mangling. Specifically:
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:
$ 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
One fix is to use g++
for linking:
$ 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
Because duktape.h
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.
By default scope-based resource management (sometimes referred to
as RAII) won't work in Duktape/C functions because Duktape uses
longjmp()
for internal long control transfers, bypassing
C++ stack unwind mechanisms. You can use DUK_OPT_CPP_EXCEPTIONS
to cause Duktape to use C++ exceptions for internal long control transfers,
which allows scope-based resource management to work in Duktape/C functions.
Duktape can be installed as a system-wide library; see system-install.rst.
Current goal is for the Duktape compile to be clean when:
-Wall
in gcc/clang).There are still some warnings present when you compile with
-Wextra
or equivalent option.
There may be some warnings when compiling with a pre-C99 compiler
(or a C99 compiler without a -std=c99
option or similar).