mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
210 lines
11 KiB
210 lines
11 KiB
<h1 id="introduction">Introduction</h1>
|
|
|
|
<p>Version: <span class="duktape-version">XX.XX.XX</span>
|
|
(<span class="current-date">XXXX-XX-XX</span>)</p>
|
|
|
|
<h2>Document scope</h2>
|
|
|
|
<p>This guide provides an introduction to using Duktape in your programs.
|
|
Once you're familiar with the basics, there is a concise
|
|
<a href="api.html">API reference</a> for looking up API details. The
|
|
<a href="http://wiki.duktape.org">Duktape Wiki</a> provides more detailed
|
|
examples and best practices.</p>
|
|
|
|
<p>This document doesn't cover Duktape internals, see the
|
|
<a href="https://github.com/svaarala/duktape/tree/master/doc">Duktape repo</a>
|
|
if you wish to tinker with them.</p>
|
|
|
|
<h2>What is Duktape?</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>Conformance</h2>
|
|
|
|
<p>Duktape conforms to ES5.0/ES5.1 with semantics updated from ES2015 or
|
|
later where appropriate:</p>
|
|
<ul>
|
|
<li><a href="http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262%205th%20edition%20December%202009.pdf">ECMAScript Language Specification 5th Edition</a></li>
|
|
<li><a href="http://www.ecma-international.org/ecma-262/5.1/">ECMAScript® Language Specification 5.1 Edition</a></li>
|
|
</ul>
|
|
|
|
<p>Duktape tracks the latest Ecmascript specification for semantics and
|
|
built-ins (however support for ES2015 and later is still incomplete), see:</p>
|
|
<ul>
|
|
<li><a href="http://www.ecma-international.org/ecma-262/6.0/">ECMAScript® 2015 Language Specification</a></li>
|
|
<li><a href="http://www.ecma-international.org/ecma-262/7.0/">ECMAScript® 2016 Language Specification</a></li>
|
|
</ul>
|
|
|
|
<p>In some specific cases Duktape may follow a specification draft,
|
|
see work in progress in <a href="https://github.com/tc39/ecma262">TC39/ecma262</a>.
|
|
This is done when a feature in the latest specifications conflicts
|
|
with real world code (see e.g. <a href="https://github.com/tc39/ecma262/pull/263">RegExp.prototype issues</a>).</p>
|
|
|
|
<p>TypedArray support is based on ES2016 TypedArray; initial implementation
|
|
was based on Khronos TypedArray specification:</p>
|
|
<ul>
|
|
<li><a href="https://www.khronos.org/registry/typedarray/specs/latest/">Typed Array Specification (Editor's Draft 18 July 2013)</a> (Note: link is to latest)</li>
|
|
<li><code>svn co -r 30720 https://cvs.khronos.org/svn/repos/registry/trunk/public/typedarray</code></li>
|
|
</ul>
|
|
|
|
<p>Node.js Buffer support is based on:</p>
|
|
<ul>
|
|
<li><a href="https://nodejs.org/docs/v6.9.1/api/buffer.html">Buffer Node.js v6.9.1</a></li>
|
|
</ul>
|
|
|
|
<p>TextEncoder() and TextDecoder() bindings are based on:</p>
|
|
<ul>
|
|
<li><a href="https://encoding.spec.whatwg.org/#api">Encoding API</a>, WHATWG Encoding Living Standard</li>
|
|
</ul>
|
|
|
|
<p>Performance.now() binding is based on:</p>
|
|
<ul>
|
|
<li><a href="https://www.w3.org/TR/hr-time/#dom-performance-now">High Resolution Time Level 2</a></li>
|
|
</ul>
|
|
|
|
<h2>Features</h2>
|
|
|
|
<p>Besides standard Ecmascript features, Duktape has the following additional
|
|
features (some are visible to applications, while others are internal):</p>
|
|
<ul>
|
|
<li>ES2015 <a href="https://www.khronos.org/registry/typedarray/specs/latest/">TypedArray</a>
|
|
and <a href="https://nodejs.org/docs/v6.9.1/api/buffer.html">Node.js Buffer</a> bindings,
|
|
plain buffer type (lightweight Uint8Array)</li>
|
|
<li>From Ecmascript 2015 (ES6): <code>setPrototypeOf</code>/<code>__proto__</code>,
|
|
a subset of <code>Proxy</code> objects, <code>Reflect</code>, computed property names,
|
|
and minimal <code>const</code> support</li>
|
|
<li>From Ecmascript 2016 (ES7): exponentiation operator (<code>**</code>, <code>**=</code>)</li>
|
|
<li><a href="https://encoding.spec.whatwg.org/#api">Encoding API</a> bindings based on the WHATWG Encoding Living Standard</li>
|
|
<li>Duktape specific built-ins: provided by the <code>Duktape</code> global object</li>
|
|
<li>Extended types: custom "buffer" and "pointer" types, extended string type
|
|
which supports arbitary binary strings and
|
|
non-<a href="http://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane">BMP</a>
|
|
strings (standard Ecmascript only supports 16-bit codepoints)</li>
|
|
<li>Combined reference counting and mark-and-sweep garbage collection,
|
|
with finalizers and emergency garbage collection (you can also build
|
|
with just mark-and-sweep)</li>
|
|
<li>Coroutine support</li>
|
|
<li>Tail call support</li>
|
|
<li>Built-in debugger framework based on a debugger protocol</li>
|
|
<li>Built-in regular expression engine with no platform dependencies</li>
|
|
<li>Built-in Unicode support with no platform dependencies</li>
|
|
<li>Built-in number parsing and formatting with no platform dependencies</li>
|
|
<li>Additional custom JSON formats (JX and JC)</li>
|
|
<li>Bytecode dump/load mechanism for caching compiled functions</li>
|
|
</ul>
|
|
|
|
<h2>Goals</h2>
|
|
|
|
<p><b>Compliance</b>. 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.</p>
|
|
|
|
<p><b>Portability</b>. 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 <code>Date</code> built-in.
|
|
Duktape supports major platforms directly but you can also use an external
|
|
Date provider on exotic platforms.</p>
|
|
|
|
<p><b>Easy C interface</b>. 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.</p>
|
|
|
|
<p><b>Small footprint</b>. 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.</p>
|
|
|
|
<p><b>Reasonable performance</b>. 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.
|
|
<a href="http://www.lua.org/">Lua</a> is a good benchmark in this respect.
|
|
(Adding optional, modular support for JITing or perhaps off-line compilation
|
|
would be nice.)</p>
|
|
|
|
<p><b>ASCII string performance</b>. 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.</p>
|
|
|
|
<h2>Document organization</h2>
|
|
|
|
<p><a href="#gettingstarted">Getting started</a> 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.</p>
|
|
|
|
<p><a href="#programming">Programming model</a>, <a href="#stacktypes">Stack types</a>,
|
|
and <a href="#ctypes">C types</a>
|
|
discuss core Duktape concepts such as <i>heap</i>, <i>context</i>, <i>value stacks</i>,
|
|
<i>Duktape API</i>, and <i>Duktape/C functions</i>. Duktape stack types and C type
|
|
wrappers are discussed in detail.</p>
|
|
|
|
<p>Duktape specific Ecmascript features are discussed in multiple sections:
|
|
<a href="#typealgorithms">Type algorithms</a> (for custom types),
|
|
<a href="#duktapebuiltins">Duktape built-ins</a> (additional built-ins),
|
|
<a href="#postes5features">Post-ES5 features</a> (features implemented from ES2016 and beyond),
|
|
<a href="#custombehavior">Custom behavior</a> (behavior differing from standard),
|
|
<a href="#customjson">Custom JSON formats</a>,
|
|
<a href="#customdirectives">Custom directives</a>,
|
|
<a href="#bufferobjects">Buffer objects</a>,
|
|
<a href="#errorobjects">Error objects</a> (properties and traceback support),
|
|
<a href="#functionobjects">Function objects</a> (properties),
|
|
<a href="#datetime">Date and time</a>,
|
|
<a href="#random">Random numbers</a>,
|
|
<a href="#debugger">Debugger</a>,
|
|
<a href="#modules">Modules</a>,
|
|
<a href="#finalization">Finalization</a>,
|
|
<a href="#coroutines">Coroutines</a>,
|
|
<a href="#virtualproperties">Virtual properties</a>,
|
|
<a href="#symbols">Symbols</a>,
|
|
<a href="#bytecodedumpload">Bytecode dump/load</a>,
|
|
<a href="#threading">Threading</a>,
|
|
<a href="#sandboxing">Sandboxing</a>.
|
|
</p>
|
|
|
|
<p><a href="#performance">Performance</a> provides a few Duktape-specific tips
|
|
for improving performance and avoiding performance pitfalls.
|
|
<a href="#memoryusage">Memory usage</a> summarizes Duktape memory usage and
|
|
gives pointers for minimizing it.
|
|
<a href="#compiling">Compiling</a> describes how to configure and compile Duktape
|
|
as part of your application.
|
|
<a href="#portability">Portability</a> covers platform and compiler specific
|
|
issues and other portability issues.
|
|
<a href="#compatibility">Compatibility</a> discusses Duktape's compatibility
|
|
with Ecmascript dialects, extensions, and frameworks.
|
|
<a href="#versioning">Versioning</a> describes Duktape versioning and what version
|
|
compatibility to expect.
|
|
<a href="#limitations">Limitations</a> summarizes currently known limitations
|
|
and provides possible workarounds.</p>
|
|
|
|
<p><a href="#comparisontolua">Comparison to Lua</a> discusses some differences
|
|
between Lua and Duktape; it may be useful reading if you're already familiar with Lua.</p>
|
|
|