Introduction

Version: XX.XX.XX (XXXX-XX-XX)

Document scope

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.

What is Duktape?

Duktape is an embeddable Ecmascript E5/E5.1 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.

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. Duktape is no exception, and provides the commonly used print() and alert() built-ins. Even so, we use the term Ecmascript throughout to refer to the language implemented by Duktape.

Conformance

Duktape conforms to the following Ecmascript specifications:

Duktape borrows a few features from Ecmascript E6:

TypedArray support is based on Khronos TypedArray specification with some ambiguous semantics resolved based on ES6 TypedArray (and comparison to other engines):

Node.js Buffer support is based on:

Features

Besides standard Ecmascript features, Duktape has the following additional features (some are visible to applications, while others are internal):

Goals

Compliance. Ecmascript E5/E5.1 and real world compliance. Ecmascript compliance requires regular expression and Unicode support. When possible, implement features from the upcoming Ecmascript E6 specification 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. 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.

Document organization

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), Ecmascript E6 features (features borrowed from ES6), Custom behavior (behavior differing from standard), Custom JSON formats, Custom directives, Buffer objects, Error objects (properties and traceback support), Function objects (properties), Debugger, Modules, Logging, Finalization, Coroutines, Virtual properties, Internal properties, 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 compile Duktape in detail, covering in particular available feature defines. 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.