[ceph.git] / ceph / src / civetweb / src / third_party / duktape-1.5.2 / README.rst

=======
Duktape
=======

Duktape is a small and portable Ecmascript E5/E5.1 implementation.  It is
intended to be easily embeddable into C programs, with a C API similar in
spirit to Lua's.

Duktape supports the full E5/E5.1 feature set including errors, Unicode
strings, and regular expressions, a subset of E6 features (e.g. Proxy
objects), Khronos/ES6 ArrayBuffer/TypedView, and Node.js Buffer bindings.

Duktape also provides a number of custom features such as error tracebacks,
additional data types for better C integration, combined reference counting
and mark-and sweep garbage collector, object finalizers, co-operative
threads a.k.a. coroutines, tail calls, built-in logging and module frameworks,
a built-in debugger protocol, function bytecode dump/load, and so on.

You can browse Duktape programmer's API and other documentation at:

* http://duktape.org/

In particular, you should read the getting started section:

* http://duktape.org/guide.html#gettingstarted

More examples and how-to articles are in the Duktape Wiki:

* http://wiki.duktape.org/

Building and integrating Duktape into your project is very straightforward:

* http://duktape.org/guide.html#compiling

See Makefile.hello for a concrete example::

  $ cd <dist_root>
  $ make -f Makefile.hello
  [...]
  $ ./hello
  Hello world!
  2+3=5

To build an example command line tool, use the following::

  $ cd <dist_root>
  $ make -f Makefile.cmdline
  [...]

  $ ./duk
  ((o) Duktape
  duk> print('Hello world!');
  Hello world!
  = undefined

  $ ./duk mandel.js
  [...]

This distributable contains:

* ``src/``: main Duktape library in a "single source file" format (duktape.c,
  duktape.h, and duk_config.h).

* ``src-noline/``: contains a variant of ``src/duktape.c`` with no ``#line``
  directives which is preferable for some users.  See discussion in
  https://github.com/svaarala/duktape/pull/363.

* ``src-separate/``: main Duktape library in multiple files format.

* ``config/``: genconfig utility for creating duk_config.h configuration
  files, see: http://wiki.duktape.org/Configuring.html.

* ``examples/``: further examples for using Duktape.  Although Duktape
  itself is widely portable, some of the examples are Linux only.
  For instance the ``eventloop`` example illustrates how ``setTimeout()``
  and other standard timer functions could be implemented on Unix/Linux.

* ``extras/``: utilities and modules which don't comfortably fit into the
  main Duktape library because of footprint or portability concerns.
  Extras are maintained and bug fixed code, but don't have the same version
  guarantees as the main Duktape library.

* ``polyfills/``: a few replacement suggestions for non-standard Javascript
  functions provided by other implementations.

* ``debugger/``: a debugger with a web UI, see ``debugger/README.rst`` and
  https://github.com/svaarala/duktape/blob/master/doc/debugger.rst for
  details on Duktape debugger support.  Also contains a JSON debug proxy
  (one written in Node.js and another in DukLuv) to make talking to the
  debug target easier.

* ``licenses/``: licensing information.

You can find release notes at:

* https://github.com/svaarala/duktape/blob/master/RELEASES.rst

This distributable contains Duktape version 1.5.2, created from git
commit cad34ae155acb0846545ca6bf2d29f9463b22bbb (v1.5.2).

Duktape is copyrighted by its authors (see ``AUTHORS.rst``) and licensed
under the MIT license (see ``LICENSE.txt``).  String hashing algorithms are
based on the algorithm from Lua (MIT license), djb2 hash, and Murmurhash2
(MIT license).  Duktape module loader is based on the CommonJS module
loading specification (without sharing any code), CommonJS is under the
MIT license.

Have fun!

Sami Vaarala (sami.vaarala@iki.fi)
Commit	Line	Data
7c673cae FG	1	=======
	2	Duktape
	3	=======
	4
	5	Duktape is a small and portable Ecmascript E5/E5.1 implementation. It is
	6	intended to be easily embeddable into C programs, with a C API similar in
	7	spirit to Lua's.
	8
	9	Duktape supports the full E5/E5.1 feature set including errors, Unicode
	10	strings, and regular expressions, a subset of E6 features (e.g. Proxy
	11	objects), Khronos/ES6 ArrayBuffer/TypedView, and Node.js Buffer bindings.
	12
	13	Duktape also provides a number of custom features such as error tracebacks,
	14	additional data types for better C integration, combined reference counting
	15	and mark-and sweep garbage collector, object finalizers, co-operative
	16	threads a.k.a. coroutines, tail calls, built-in logging and module frameworks,
	17	a built-in debugger protocol, function bytecode dump/load, and so on.
	18
	19	You can browse Duktape programmer's API and other documentation at:
	20
	21	* http://duktape.org/
	22
	23	In particular, you should read the getting started section:
	24
	25	* http://duktape.org/guide.html#gettingstarted
	26
	27	More examples and how-to articles are in the Duktape Wiki:
	28
	29	* http://wiki.duktape.org/
	30
	31	Building and integrating Duktape into your project is very straightforward:
	32
	33	* http://duktape.org/guide.html#compiling
	34
	35	See Makefile.hello for a concrete example::
	36
	37	$ cd <dist_root>
	38	$ make -f Makefile.hello
	39	[...]
	40	$ ./hello
	41	Hello world!
	42	2+3=5
	43
	44	To build an example command line tool, use the following::
	45
	46	$ cd <dist_root>
	47	$ make -f Makefile.cmdline
	48	[...]
	49
	50	$ ./duk
	51	((o) Duktape
	52	duk> print('Hello world!');
	53	Hello world!
	54	= undefined
	55
	56	$ ./duk mandel.js
	57	[...]
	58
	59	This distributable contains:
	60
	61	* ``src/``: main Duktape library in a "single source file" format (duktape.c,
	62	duktape.h, and duk_config.h).
	63
11fdf7f2 TL	64	* ``src-noline/``: contains a variant of ``src/duktape.c`` with no ``#line``
	65	directives which is preferable for some users. See discussion in
	66	https://github.com/svaarala/duktape/pull/363.
	67
7c673cae FG	68	* ``src-separate/``: main Duktape library in multiple files format.
	69
	70	* ``config/``: genconfig utility for creating duk_config.h configuration
	71	files, see: http://wiki.duktape.org/Configuring.html.
	72
	73	* ``examples/``: further examples for using Duktape. Although Duktape
	74	itself is widely portable, some of the examples are Linux only.
	75	For instance the ``eventloop`` example illustrates how ``setTimeout()``
	76	and other standard timer functions could be implemented on Unix/Linux.
	77
	78	* ``extras/``: utilities and modules which don't comfortably fit into the
	79	main Duktape library because of footprint or portability concerns.
	80	Extras are maintained and bug fixed code, but don't have the same version
	81	guarantees as the main Duktape library.
	82
	83	* ``polyfills/``: a few replacement suggestions for non-standard Javascript
	84	functions provided by other implementations.
	85
	86	* ``debugger/``: a debugger with a web UI, see ``debugger/README.rst`` and
	87	https://github.com/svaarala/duktape/blob/master/doc/debugger.rst for
11fdf7f2 TL	88	details on Duktape debugger support. Also contains a JSON debug proxy
	89	(one written in Node.js and another in DukLuv) to make talking to the
	90	debug target easier.
7c673cae FG	91
	92	* ``licenses/``: licensing information.
	93
	94	You can find release notes at:
	95
	96	* https://github.com/svaarala/duktape/blob/master/RELEASES.rst
	97
11fdf7f2 TL	98	This distributable contains Duktape version 1.5.2, created from git
11fdf7f2 TL	99	commit cad34ae155acb0846545ca6bf2d29f9463b22bbb (v1.5.2).
7c673cae FG	100
7c673cae FG	101	Duktape is copyrighted by its authors (see ``AUTHORS.rst``) and licensed
11fdf7f2 TL	102	under the MIT license (see ``LICENSE.txt``). String hashing algorithms are
	103	based on the algorithm from Lua (MIT license), djb2 hash, and Murmurhash2
	104	(MIT license). Duktape module loader is based on the CommonJS module
	105	loading specification (without sharing any code), CommonJS is under the
	106	MIT license.
7c673cae FG	107
	108	Have fun!
	109
	110	Sami Vaarala (sami.vaarala@iki.fi)