Version: XX.XX.XX (XXXX-XX-XX)
This guide provides an introduction to using Duktape in your programs. Once you're familiar with the basics, there is a concise API reference for looking up API details. The Duktape Wiki provides more detailed examples and best practices.
This document doesn't cover Duktape internals, see the Duktape repo if you wish to tinker with them.
Duktape is an embeddable Ecmascript engine with a focus on portability and compact footprint. By integrating Duktape into your C/C++ program you can easily extend its functionality through scripting. You can also build the main control flow of your program in Ecmascript and use fast C code functions to do heavy lifting.
Embeddability means that Duktape makes minimal assumptions about the underlying platform and its capabilities; instead, the application which embeds Duktape is in control of which native bindings are provided and in what manner. For example, there are no default bindings for printing text to the console or to interact with the file system. Duktape distributable package includes example providers which you can easily integrate if they suit your needs.
The terms Ecmascript and Javascript are often considered more or less equivalent, although Javascript and its variants are technically just one environment where the Ecmascript language is used. The line between the two is not very clear in practice: even non-browser Ecmascript environments often provide some browser-specific built-ins. Even so, we use the term Ecmascript throughout to refer to the language implemented by Duktape.
Duktape conforms to ES5.0/ES5.1 with semantics updated from ES2015 or later where appropriate:
Duktape tracks the latest Ecmascript specification for semantics and built-ins (however support for ES2015 and later is still incomplete), see:
In some specific cases Duktape may follow a specification draft, see work in progress in TC39/ecma262. This is done when a feature in the latest specifications conflicts with real world code (see e.g. RegExp.prototype issues).
TypedArray support is based on ES2016 TypedArray; initial implementation was based on Khronos TypedArray specification:
svn co -r 30720 https://cvs.khronos.org/svn/repos/registry/trunk/public/typedarrayNode.js Buffer support is based on:
TextEncoder() and TextDecoder() bindings are based on:
Performance.now() binding is based on:
Besides standard Ecmascript features, Duktape has the following additional features (some are visible to applications, while others are internal):
setPrototypeOf/__proto__,
a subset of Proxy objects, Reflect, computed property names,
and minimal const support**, **=)Duktape global objectCompliance. Ecmascript E5/E5.1 and real world compliance. Ecmascript compliance requires regular expression and Unicode support. When possible, implement features from latest or draft Ecmascript specifications to minimize Duktape custom features.
Portability. Minimal system dependencies are nice when porting,
so Duktape depends on very few system libraries. For example, number
formatting and parsing, regular expressions, and Unicode are all implemented
internally by Duktape. One of the few dependencies that cannot be fully
eliminated is system date/time integration in the Date built-in.
Duktape supports major platforms directly but you can also use an external
Date provider on exotic platforms.
Easy C interface. The interface between Duktape and C programs should be natural and error-tolerant. As a particular issue, string representation should be UTF-8 with automatic NUL terminators to match common C use.
Small footprint. Code and data footprint should be as small as possible, even for small programs. Duktape is portable even to "bare metal" targets with no standard libraries. This is more important than performance, as there are already several very fast engines but fewer very compact, portable engines.
Reasonable performance. Small footprint (and portability, to some extent) probably eliminates the possibility of a competitive JIT-based engine, so there is no practical way of competing with very advanced JIT-based engines like SpiderMonkey (and its optimized variants) or Google V8. Performance should still be reasonable for typical embedded programs. Lua is a good benchmark in this respect. (Adding optional, modular support for JITing or perhaps off-line compilation would be nice.)
ASCII string performance. It's important that operations dealing with plain ASCII strings be very fast: ASCII dominates most embedded use. Operations dealing with non-ASCII strings need to perform reasonably but are not critical. This is a necessary trade-off: using C-compatible strings means essentially using UTF-8 string representation which makes string indexing and many other operations slower than with fixed size character representations. It's still important to support common idioms like iterating strings sequentially (in either direction) efficiently.
Getting started guides you through downloading, compiling, and integrating Duktape into your program. It also provides concrete examples of how you can integrate scripting capabilities into your program.
Programming model, Stack types, and C types discuss core Duktape concepts such as heap, context, value stacks, Duktape API, and Duktape/C functions. Duktape stack types and C type wrappers are discussed in detail.
Duktape specific Ecmascript features are discussed in multiple sections: Type algorithms (for custom types), Duktape built-ins (additional built-ins), Post-ES5 features (features implemented from ES2016 and beyond), Custom behavior (behavior differing from standard), Custom JSON formats, Custom directives, Buffer objects, Error objects (properties and traceback support), Function objects (properties), Date and time, Random numbers, Debugger, Modules, Finalization, Coroutines, Virtual properties, Symbols, Bytecode dump/load, Threading, Sandboxing.
Performance provides a few Duktape-specific tips for improving performance and avoiding performance pitfalls. Memory usage summarizes Duktape memory usage and gives pointers for minimizing it. Compiling describes how to configure and compile Duktape as part of your application. Portability covers platform and compiler specific issues and other portability issues. Compatibility discusses Duktape's compatibility with Ecmascript dialects, extensions, and frameworks. Versioning describes Duktape versioning and what version compatibility to expect. Limitations summarizes currently known limitations and provides possible workarounds.
Comparison to Lua discusses some differences between Lua and Duktape; it may be useful reading if you're already familiar with Lua.