diff --git a/config/README.rst b/config/README.rst index 58dae2ed..7be861f2 100644 --- a/config/README.rst +++ b/config/README.rst @@ -2,38 +2,18 @@ Duktape genconfig ================= -Overview -======== - ``genconfig`` is a helper script for coming up with a ``duk_config.h`` for compiling Duktape for your platform. To support this: -* It creates a Duktape 1.2.x compatible ``duk_config.h`` with automatic - platform detection and ``DUK_OPT_xxx`` feature options. - * It helps to create a ``duk_config.h`` for your platform/compiler combination. You can give a base configuration and then force certain values manually based on a YAML configuration file. -* It autogenerates documentation for config options (and Duktape 1.2.x - feature options) based on option metadata files written in YAML. - -Usage -===== - -To create an autodetect duk_config.h header (compatible with Duktape 1.2.x):: - - $ python tools/genconfig.py --metadata config --output /tmp/duk_config.h \ - duk-config-header - -To create a barebones duk_config.h header for a specific platform (easier to -edit manually):: - - $ python tools/genconfig.py --metadata config --output /tmp/duk_config.h \ - --platform linux --compiler gcc --architecture x64 \ - duk-config-header +* It autogenerates documentation for config options based on option metadata + files written in YAML. -There are further commands to e.g. autogenerate config option documentation; -see ``genconfig.py`` for details. +NOTE: ``tools/configure.py`` is now the preferred tool for preparing a config +header (using genconfig.py) and Duktape source files (using other tools) for +build. diff --git a/debugger/README.rst b/debugger/README.rst index f60b3506..1d837d5e 100644 --- a/debugger/README.rst +++ b/debugger/README.rst @@ -24,14 +24,13 @@ Some prerequisites: * You'll need Node.js v0.10.x or newer. Older Node.js versions don't support the required packages. -Compile Duktape command line tool with debugger support (for further options -see http://wiki.duktape.org/FeatureOptions.html): +Compile Duktape command line tool with debugger support: -* ``DUK_OPT_DEBUGGER_SUPPORT`` +* Enable ``DUK_USE_DEBUGGER_SUPPORT`` and ``DUK_USE_INTERRUPT_COUNTER`` for + ``tools/configure.py``. -* ``DUK_OPT_INTERRUPT_COUNTER`` - -* ``DUK_CMDLINE_DEBUGGER_SUPPORT`` +* Enable ``DUK_CMDLINE_DEBUGGER_SUPPORT`` on compiler command line for Duktape + command line utility. The source distributable contains a Makefile to build a "duk" command with debugger support:: diff --git a/doc/benchmarking-notes.rst b/doc/benchmarking-notes.rst index 4aca990e..897cae26 100644 --- a/doc/benchmarking-notes.rst +++ b/doc/benchmarking-notes.rst @@ -115,8 +115,7 @@ particular, if memory were to run out (in concrete terms, an attempt to allocate memory would fail), an emergency mark-and-sweep pass would free that memory which would then be available for other use. -Enabling ``DUK_OPT_GC_TORTURE`` (or ``DUK_USE_GC_TORTURE`` if editing ``duk_config.h`` -directly) we get a very different result:: +Enabling ``DUK_USE_GC_TORTURE`` we get a very different result:: ... KB diff --git a/doc/bytecode.rst b/doc/bytecode.rst index 2b8e0553..a2650b86 100644 --- a/doc/bytecode.rst +++ b/doc/bytecode.rst @@ -139,8 +139,8 @@ That said, concrete issues to consider when using bytecode for obfuscation: * Line number information in the ``_Pc2line`` property: this can be deleted or changed, or you can configure Duktape not to store this information in the - first place (``DUK_OPT_NO_PC2LINE`` or ``DUK_USE_PC2LINE``). Without line - information tracebacks will of course be less useful. + first place (using option ``DUK_USE_PC2LINE``). Without line information + tracebacks will of course be less useful. When not to use bytecode dump/load ================================== diff --git a/doc/code-issues.rst b/doc/code-issues.rst index b6a96a2d..3f557944 100644 --- a/doc/code-issues.rst +++ b/doc/code-issues.rst @@ -957,40 +957,6 @@ The downsides include: * Indirection obscures the strings emitted from each call site a bit, and makes the code less modular. -Feature detection in duktape.h -============================== - -The ``duktape.h`` header which provides the Duktape public API defines and -also handles portability, such as: - -* Detecting compiler / platform combinations and choosing appropriate - values for byte order, alignment requirements, availability of variadic - macros, etc. - -* Provides type wrappers (typedefs) for all types required by Duktape both - in its public API and internally. - -* Resolve user feature options (``DUK_OPT_xxx``) into effective feature - options used internally (``DUK_USE_xxx``). - -* Includes system headers needed for e.g. type detection. - -* When compiling Duktape itself (distinguished through the ``DUK_COMPILING_DUKTAPE`` - define provided by ``duk_internal.h``) defines critical feature selection - defines (like ``_POSIX_C_SOURCE``) needed by e.g. system date headers. - When compiling user code, avoids defining feature selection defines to - minimize conflicts with application code. - -The ``duktape.h`` header is built from individual parts to make it easier to -manage during development. - -Originally public and internal feature detection were done separately, but -increasingly the public API started needing typedefs and also became -dependent on effective feature options. The initial workaround was to do a -minimal platform and feature detection in the public header and consistency -check it against internal feature detection, but this became more and more -unwieldy. - Portability concerns ==================== @@ -2025,16 +1991,11 @@ Using ``const`` for tables allows tables to compiled into the text section. This is important on some embedded platforms where RAM is tight but there is more space for code and fixed data. -Feature defines -=============== - -All feature detection is concentrated into ``duk_config.h`` which considers -inputs from various sources: - -* ``DUK_OPT_xxx`` defines, which allow a user to request a specific feature - or provide a specific value (such as traceback depth). +Config options +============== -* Compiler and platform specific defines and features. +All feature detection is concentrated into ``duk_config.h`` which detects +the compiler, platform, and architecture via preprocessor defines. As a result, ``duk_config.h`` defines ``DUK_USE_xxx`` macros which enable and disable specific features and provide parameter values (such as traceback @@ -2043,9 +2004,7 @@ internal Duktape code. The ``duk_config.h`` defines, especially typedefs, are also visible for the public API header. When adding specific hacks and workarounds which might not be of interest -to all users, add a ``DUK_OPT_xxx`` flag for them and translate it to a -``DUK_USE_xxx`` flag in ``duk_config.h``. If the ``DUK_OPT_xxx`` flag -is absent, the custom behavior MUST NOT be enabled. +to all users, add a ``DUK_USE_xxx`` flag metadata into the build. Platforms and compilers ======================= diff --git a/doc/debugger.rst b/doc/debugger.rst index fe30ec05..082d85ec 100644 --- a/doc/debugger.rst +++ b/doc/debugger.rst @@ -60,10 +60,9 @@ Getting started: debugging your target To integrate debugger support into your target, you need to: -* **Check your feature options**: define ``DUK_OPT_DEBUGGER_SUPPORT`` and - ``DUK_OPT_INTERRUPT_COUNTER`` to enable debugger support in Duktape. - Also consider other debugging related feature options, like forwarding - logging (``DUK_OPT_DEBUGGER_FWD_LOGGING``) to the debug client. +* **Check your config options**: enable ``DUK_USE_DEBUGGER_SUPPORT`` and + ``DUK_USE_INTERRUPT_COUNTER`` to enable debugger support in Duktape. + Also consider other debugging related config options. * **Implement a concrete stream transport mechanism**: needed for both the target device and the Duktape debugger. The best transport depends on the @@ -116,7 +115,7 @@ debug transport. The example debugger stuff includes: * Duktape command line tool ``--debugger`` option which is enabled by using - both ``DUK_CMDLINE_DEBUGGER_SUPPORT`` and ``DUK_OPT_DEBUGGER_SUPPORT``. + both ``DUK_CMDLINE_DEBUGGER_SUPPORT`` and ``DUK_USE_DEBUGGER_SUPPORT``. The command line tool uses a TCP socket based example transport provided in ``examples/debug-trans-socket/``. @@ -613,7 +612,7 @@ This topic is covered in a separate section. Development time transport torture option ----------------------------------------- -The feature option DUK_OPT_DEBUGGER_TRANSPORT_TORTURE causes Duktape to do +The config option DUK_USE_DEBUGGER_TRANSPORT_TORTURE causes Duktape to do all debug transport read/write operations in 1-byte steps, which is useful to catch any incorrect assumptions about reading or writing chunks of a certain size. @@ -2645,7 +2644,7 @@ Overview This section contains some implementation notes on the Duktape internals. -Duktape debugger support is optional and enabled with a feature option. +Duktape debugger support is optional and enabled with a config option. The bytecode executor interrupt feature is also mandatory when debugger support is enabled. diff --git a/doc/fastint.rst b/doc/fastint.rst index 83bee019..f5898f9c 100644 --- a/doc/fastint.rst +++ b/doc/fastint.rst @@ -35,7 +35,7 @@ to user C and Ecmascript code: all conversions are automatic. To enable fastint support, simply define: -* ``DUK_OPT_FASTINT`` / ``DUK_USE_FASTINT`` +* ``DUK_USE_FASTINT`` You should measure the impact of enabling fastint support for your target platform and Ecmascript code base. Fastint support is not an automatic diff --git a/doc/feature-options.rst b/doc/feature-options.rst deleted file mode 100644 index 49676c5f..00000000 --- a/doc/feature-options.rst +++ /dev/null @@ -1,71 +0,0 @@ -======================= -Duktape feature options -======================= - -Overview -======== - -The effective set of Duktape features is resolved in three steps in Duktape 1.x: - -* User defines ``DUK_OPT_xxx`` feature options. These are essentially - requests to enable/disable some feature. (These will be removed in - Duktape 2.x and ``DUK_USE_xxx`` flags will be used directly.) - -* Duktape feature resolution in the default "auto-detecting" ``duk_config.h`` - (previously internal ``duk_features.h.in``) takes into account the - requested features, the platform, the compiler, the operating system - etc, and defines ``DUK_USE_xxx`` internal use flags. Other parts of - Duktape only listen to these "use flags", so that feature resolution is - strictly contained. - -* The final ``DUK_USE_xxx`` flags can be tweaked in several ways: - - - The generated ``duk_config.h`` header can be edited directly (manually, - through scripting, etc). - - - The ``genconfig`` utility can be used to generate a ``duk_config.h`` - header with user-supplied option overrides given either as YAML config - file(s) or C header snippets included in the config header. - - - User may optionally have a ``duk_custom.h`` header which can tweak the - defines (see ``DUK_OPT_HAVE_CUSTOM_H`` for more discussion; this feature - option will be removed in Duktape 2.x.) - -Starting from Duktape 1.3 an external ``duk_config.h`` is required; it may -be a prebuilt multi-platform header or a user-modified one. Duktape 2.x -will remove support for ``DUK_OPT_xxx`` feature options entirely so that -all config changes are made by editing ``duk_config.h`` or by regenerating -it e.g. using genconfig. - -Feature option naming -===================== - -Feature options that enable a certain (default) feature are named:: - - DUK_OPT_MY_FEATURE - -Feature options that disable a (default) feature are named:: - - DUK_OPT_NO_MY_FEATURE - -Both flags are reserved at the same time. One of the options will match -the default behavior, so it won't actually be implemented. - -Some feature options have a value associated with them. This is the case -for e.g. ``DUK_OPT_PANIC_HANDLER`` or ``DUK_OPT_FORCE_ALIGN``. These are -handled case by case. - -Avoid using words like "disable" in the feature naming. This will lead to -odd names if the default behavior changes and a "no disable" flag is needed. - -Feature option documentation -============================ - -Feature documentation is automatically generated from config/feature option -metadata: - -* http://wiki.duktape.org/Configuring.html - -* http://wiki.duktape.org/ConfigOptions.html - -* http://wiki.duktape.org/FeatureOptions.html diff --git a/doc/lightweight-functions.rst b/doc/lightweight-functions.rst index 5c17a458..fac4c241 100644 --- a/doc/lightweight-functions.rst +++ b/doc/lightweight-functions.rst @@ -56,10 +56,10 @@ lightfunction values with ``duk_push_c_lightfunc()``. Lightfunc limits: * Magic must be between -128 to 127 (-0x80 to 0x7f). -DUK_OPT_LIGHTFUNC_BUILTINS +DUK_USE_LIGHTFUNC_BUILTINS -------------------------- -The feature option ``DUK_OPT_LIGHTFUNC_BUILTINS`` converts most built-in +The config option ``DUK_USE_LIGHTFUNC_BUILTINS`` converts most built-in functions forcibly into lightweight functions, reducing memory usage on low memory platforms by around 14 kB. diff --git a/doc/low-memory.rst b/doc/low-memory.rst index f0443da2..b80bfbdc 100644 --- a/doc/low-memory.rst +++ b/doc/low-memory.rst @@ -44,7 +44,7 @@ realistic memory targets are roughly: - Requires a bare metal system, possibly a custom C library, etc. - Requires use of ROM strings and objects to reduce Duktape startup - RAM usage (which drops to around 3-4kB with ROM strings/objects). + RAM usage (which drops to around 2-3kB with ROM strings/objects). There are four basic goals for low memory optimization: @@ -125,7 +125,7 @@ Example using GCC: compile the Duktape command line utility without removing unused API symbols:: $ gcc -o duk -Os -pedantic -std=c99 -Wall -fstrict-aliasing \ - -fomit-frame-pointer -I./src -DDUK_OPT_SELF_TESTS src/duktape.c \ + -fomit-frame-pointer -I./src src/duktape.c \ examples/cmdline/duk_cmdline.c -lm $ size duk text data bss dec hex filename @@ -136,7 +136,7 @@ Add GCC specific options to remove unused symbols:: # With -fdata-sections -ffunction-sections -Wl,--gc-sections: $ gcc -o duk -Os -pedantic -std=c99 -Wall -fstrict-aliasing \ -fomit-frame-pointer -I./src -fdata-sections \ - -ffunction-sections -Wl,--gc-sections -DDUK_OPT_SELF_TESTS \ + -ffunction-sections -Wl,--gc-sections \ src/duktape.c examples/cmdline/duk_cmdline.c -lm $ size duk text data bss dec hex filename @@ -172,13 +172,13 @@ Suggested options * Reduce error handling footprint with one or more of: - - ``DUK_OPT_NO_AUGMENT_ERRORS`` + - ``#undef DUK_USE_AUGMENT_ERRORS`` - - ``DUK_OPT_NO_TRACEBACKS`` + - ``#undef DUK_USE_TRACEBACKS`` - - ``DUK_OPT_NO_VERBOSE_ERRORS`` + - ``#undef DUK_USE_VERBOSE_ERRORS`` - - ``DUK_OPT_NO_PC2LINE`` + - ``#undef DUK_USE_PC2LINE`` * Use slower but more compact lexer algorithm (saves on code footprint): @@ -198,39 +198,35 @@ Suggested options * If you don't need Node.js Buffer and Khronos/ES6 typed array support, use: - - ``DUK_OPT_NO_BUFFEROBJECT_SUPPORT`` - - ``#undef DUK_USE_BUFFEROBJECT_SUPPORT`` * If you don't need the Duktape-specific additional JX/JC formats, use: - - ``DUK_OPT_NO_JX`` + - ``#undef DUK_USE_JX`` - - ``DUK_OPT_NO_JC`` + - ``#undef DUK_USE_JC`` * Features borrowed from Ecmascript E6 can usually be disabled: - - ``DUK_OPT_NO_ES6_OBJECT_SETPROTOTYPEOF`` + - ``#undef DUK_USE_ES6_OBJECT_SETPROTOTYPEOF`` - - ``DUK_OPT_NO_ES6_OBJECT_PROTO_PROPERTY`` + - ``#undef DUK_USE_ES6_OBJECT_PROTO_PROPERTY`` - - ``DUK_OPT_NO_ES6_PROXY`` + - ``#undef DUK_USE_ES6_PROXY`` * If you don't need regexp support, use: - - ``DUK_OPT_NO_REGEXP_SUPPORT`` + - ``#undef DUK_USE_REGEXP_SUPPORT`` * Disable unnecessary parts of the C API: - - ``DUK_OPT_NO_BYTECODE_DUMP_SUPPORT`` - - ``#undef DUK_USE_BYTECODE_DUMP_SUPPORT`` * Duktape debug code uses a large, static temporary buffer for formatting debug log lines. If you're running with debugging enabled, use e.g. the following to reduce this overhead: - - ``-DDUK_OPT_DEBUG_BUFSIZE=2048`` + - ``#define DUK_USE_DEBUG_BUFSIZE 2048`` * If strict Unicode support is not critical in your application, you can: @@ -252,14 +248,12 @@ system RAM): * Consider using lightweight functions for your Duktape/C bindings and to force Duktape built-ins to be lightweight functions: - - ``DUK_OPT_LIGHTFUNC_BUILTINS`` + - ``#define DUK_USE_LIGHTFUNC_BUILTINS`` * If code footprint is a significant issue, disabling reference counting reduces code footprint by several kilobytes at the cost of more RAM fluctuation: - - ``DUK_OPT_NO_REFERENCE_COUNTING`` - - ``#undef DUK_USE_REFERENCE_COUNTING`` - ``#undef DUK_USE_DOUBLE_LINKED_LIST`` @@ -267,39 +261,39 @@ system RAM): * Enable other 16-bit fields to reduce header size; these are typically used together (all or none): - - ``DUK_OPT_REFCOUNT16`` + - ``#define DUK_USE_REFCOUNT16`` - - ``DUK_OPT_STRHASH16`` + - ``#define DUK_USE_STRHASH16`` - - ``DUK_OPT_STRLEN16`` + - ``#define DUK_USE_STRLEN16`` - - ``DUK_OPT_BUFLEN16`` + - ``#define DUK_USE_BUFLEN16`` - - ``DUK_OPT_OBJSIZES16`` + - ``#define DUK_USE_OBJSIZES16`` - ``#undef DUK_USE_HSTRING_CLEN`` * Enable heap pointer compression, assuming pointers provided by your allocator can be packed into 16 bits: - - ``DUK_OPT_HEAPPTR16`` + - ``#define DUK_USE_HEAPPTR16`` - - ``DUK_OPT_HEAPPTR_ENC16(udata,p)`` + - ``#define DUK_USE_HEAPPTR_ENC16(udata,p) ...`` - - ``DUK_OPT_HEAPPTR_DEC16(udata,x)`` + - ``#define DUK_USE_HEAPPTR_DEC16(udata,x) ...`` - - Note: you cannot currently enable Duktape debug prints (DUK_OPT_DEBUG and - DUK_OPT_DPRINT etc) when heap pointer compression is enabled. + - Note: you cannot currently enable Duktape debug prints (DUK_USE_DEBUG) + when heap pointer compression is enabled. * Enable data pointer compression if possible. Note that these pointers can point to arbitrary memory locations (outside Duktape heap) so this may not be possible even if Duktape heap pointers can be compressed: - - ``DUK_OPT_DATAPTR16`` + - ``#define DUK_USE_DATAPTR16`` - - ``DUK_OPT_DATAPTR_ENC16(udata,p)`` + - ``#define DUK_USE_DATAPTR_ENC16(udata,p) ...`` - - ``DUK_OPT_DATAPTR_DEC16(udata,x)`` + - ``#define DUK_USE_DATAPTR_DEC16(udata,x) ...`` - **UNIMPLEMENTED AT THE MOMENT** @@ -307,11 +301,11 @@ system RAM): around 200kB of code, so assuming an alignment of 4 this may only be possible if there is less than 56kB of user code: - - ``DUK_OPT_FUNCPTR16`` + - ``#define DUK_USE_FUNCPTR16`` - - ``DUK_OPT_FUNCPTR_ENC16(udata,p)`` + - ``#define DUK_USE_FUNCPTR_ENC16(udata,p) ...`` - - ``DUK_OPT_FUNCPTR_DEC16(udata,x)`` + - ``#define DUK_USE_FUNCPTR_DEC16(udata,x) ...`` - **UNIMPLEMENTED AT THE MOMENT** @@ -320,18 +314,18 @@ system RAM): memory behavior more predictable and avoids a large continuous allocation used by the default string table: - - ``DUK_OPT_STRTAB_CHAIN`` + - ``#define DUK_USE_STRTAB_CHAIN`` - - ``DUK_OPT_STRTAB_CHAIN_SIZE=128`` (other values possible also) + - ``#define DUK_USE_STRTAB_CHAIN_SIZE 128`` (other values possible also) * Use "external" strings to allocate most strings from flash (there are multiple strategies for this, see separate section): - - ``DUK_OPT_EXTERNAL_STRINGS`` + - ``#define DUK_USE_EXTERNAL_STRINGS`` - - ``DUK_OPT_EXTSTR_INTERN_CHECK(udata,ptr,len)`` + - ``#define DUK_USE_EXTSTR_INTERN_CHECK(udata,ptr,len) ...`` - - ``DUK_OPT_EXTSTR_FREE(udata,ptr)`` + - ``#define DUK_USE_EXTSTR_FREE(udata,ptr) ...`` - As of Duktape 1.5 an alternative to external strings is to move strings (including the string heap header) to ROM, see below. @@ -360,7 +354,7 @@ The following may be appropriate when even less memory is available enabled by default because it increases the size of ``duktape.c`` considerably. Add the option ``--rom-auto-lightfunc`` to convert built-in function properties into lightfuncs to reduce ROM footprint. - (See ``util/example_rombuild.sh`` for some very simple examples.) + (See repo Makefile ``ajduk-rom`` target for some very simple examples.) - Moving built-ins into ROM makes them read-only which has some side effects. Some side effects are technical compliance issues while @@ -388,8 +382,8 @@ The following may be appropriate when even less memory is available + ``src/builtins.yaml``: documents some more format details - + ``util/example_rombuild.sh``: illustrates how to run ``configure.py`` - with user builtins + + Repo Makefile ``ajduk-rom`` target: illustrates how to run + ``configure.py`` with user builtins * Consider using lightfuncs for representing function properties of ROM built-ins. @@ -427,7 +421,7 @@ ROM pointers, and to use a ROM pointer table to compress/decompress ROM pointers. See ``examples/cmdline/duk_cmdline_ajduk.c`` for an example. -External string strategies (DUK_OPT_EXTSTR_INTERN_CHECK) +External string strategies (DUK_USE_EXTSTR_INTERN_CHECK) ======================================================== The feature can be used in two basic ways: @@ -496,11 +490,11 @@ of pool usage, allocated bytes, waste bytes, etc. It also provides some tools to optimize pool counts for one or multiple application "profiles". See detailed description below. -You can also get a dump of Duktape's internal struct sizes by enabling -``DUK_OPT_DPRINT``; Duktape will debug print struct sizes when a heap is -created. The struct sizes will give away the minimum size needed by strings, -buffers, objects, etc. They will also give you ``sizeof(duk_heap)`` which -is a large allocation that you should handle explicitly in pool tuning. +You can also get a dump of Duktape's internal struct sizes by enabling debug +prints; Duktape will debug print struct sizes when a heap is created. The +struct sizes will give away the minimum size needed by strings, buffers, +objects, etc. They will also give you ``sizeof(duk_heap)`` which is a large +allocation that you should handle explicitly in pool tuning. Finally, you can look at existing projects and what kind of pool tuning they do. AllJoyn.js has a manually tuned pool allocator which may be a @@ -538,7 +532,7 @@ Important notes * Before optimizing pools, you should select Duktape feature options (especially low memory options) carefully. -* It may be useful to use DUK_OPT_GC_TORTURE to ensure that there is no +* It may be useful to use DUK_USE_GC_TORTURE to ensure that there is no slack in memory allocations; reference counting frees unreachable values but does not handle loops. When GC torture is enabled, Duktape will run a mark-and-sweep for every memory allocation. High-water-mark values diff --git a/doc/performance-sensitive.rst b/doc/performance-sensitive.rst index e7fce942..afb75768 100644 --- a/doc/performance-sensitive.rst +++ b/doc/performance-sensitive.rst @@ -51,7 +51,7 @@ Suggested feature options * Consider enabling "fastints": - - ``DUK_OPT_FASTINT`` (``#define DUK_USE_FASTINT``) + - ``#define DUK_USE_FASTINT`` Fastints are often useful on platforms with soft floats, but they can also speed up execution on some hard float platforms (even on x64). The benefit @@ -60,7 +60,7 @@ Suggested feature options * Enable specific fast paths: - - ``DUK_OPT_JSON_STRINGIFY_FASTPATH`` (``#define DUK_USE_JSON_STRINGIFY_FASTPATH``) + - ``#define DUK_USE_JSON_STRINGIFY_FASTPATH`` - ``#define DUK_USE_JSON_QUOTESTRING_FASTPATH`` @@ -73,9 +73,9 @@ Suggested feature options * If you don't need debugging support or execution timeout support, ensure the following are **not enabled**: - - ``DUK_OPT_INTERRUPT_COUNTER`` (``#define DUK_USE_INTERRUPT_COUNTER``) + - ``#define DUK_USE_INTERRUPT_COUNTER`` - - ``DUK_OPT_DEBUGGER_SUPPORT`` (``#define DUK_USE_DEBUGGER_SUPPORT``) + - ``#define DUK_USE_DEBUGGER_SUPPORT`` Especially interrupt counter option will have a measurable performance impact because it includes code executed for every bytecode instruction diff --git a/doc/release-checklist.rst b/doc/release-checklist.rst index ba0fc19a..d0695da5 100644 --- a/doc/release-checklist.rst +++ b/doc/release-checklist.rst @@ -110,8 +110,10 @@ Checklist for ordinary releases macros:: > cd dist - > cl /W3 /O2 /DDUK_OPT_DLL_BUILD /Isrc /LD src\duktape.c - > cl /W3 /O2 /DDUK_OPT_DLL_BUILD /Isrc /Feduk.exe examples\cmdline\duk_cmdline.c duktape.lib + > python2 tools/configure --output-directory prep --source-directory src-input \ + --config-metadata config --dll + > cl /W3 /O2 /Iprep /LD prep\duktape.c + > cl /W3 /O2 /Iprep /Feduk.exe examples\cmdline\duk_cmdline.c duktape.lib > duk.exe * Test genconfig manually using metadata from the distributable @@ -145,7 +147,7 @@ Checklist for ordinary releases - DUK_USE_REFZERO_FINALIZER_TORTURE - - DUK_USE_MARKANDSWEEP_FINALIZER_TORTURE + DUK_OPT_GC_TORTURE + - DUK_USE_MARKANDSWEEP_FINALIZER_TORTURE + DUK_USE_GC_TORTURE * Memory usage testing diff --git a/doc/release-notes-v2-0.rst b/doc/release-notes-v2-0.rst index c46923fa..99667b0a 100644 --- a/doc/release-notes-v2-0.rst +++ b/doc/release-notes-v2-0.rst @@ -65,7 +65,49 @@ Or you can detect features specifically:: DUK_OPT_xxx feature option support removed ------------------------------------------ -FIXME. +Duktape 2.x no longer supports ``DUK_OPT_xxx`` options given via the compiler +command line. Instead, all options are encoded in ``duk_config.h``. + +To use custom Duktape options, use the ``tools/configure.py`` tool to create +a customized ``duk_config.h`` and prepared Duktape sources matching the +configuration. For example to enable assertions and fastint support:: + + $ python2 tools/configure.py \ + --output-directory /tmp/output \ + --source-directory src-input \ + --config-metadata config \ + -DDUK_USE_FASTINT \ + -DDUK_USE_ASSERTIONS + + # Prepared duk_config.h header and Duktape sources (duktape.h and + # duktape.c) are in /tmp/output. Compile normally with your application. + + $ gcc -std=c99 -Wall -o/tmp/test -I/tmp/output /tmp/output/duktape.c \ + my_application.c -lm + +See http://wiki.duktape.org/Configuring.html for details and examples. + +To upgrade: + +* If you're using the Duktape default configuration (and no ``DUK_OPT_xxx``) + compiler options, no actions are needed. + +* Otherwise, remove ``DUK_OPT_xxx`` options from the compilation command and + add a ``tools/configure.py`` pre-step to your build. Add the equivalent + ``DUK_USE_xxx`` options to ``tools/configure.py`` argument list; for example + ``-DDUK_USE_FASTINT``. + +* If you're using a ``duk_custom.h`` header there are three simple approaches: + + - To embed your custom header into ``duk_config.h`` statically, use + ``--fixup-file duk_custom.h`` in ``tools/configure.py`` options. + + - To include your custom header at compilation time, similarly to + ``DUK_OPT_HAVE_CUSTOM_H``, use ``--fixup-line '#include "duk_custom.h"'`` + in ``tools/configure.py`` options. + + - Finally, you can remove your custom header and add the equivalent options + to ``tools/configure.py`` when possible. Tooling changes --------------- diff --git a/doc/sandboxing.rst b/doc/sandboxing.rst index 797c6f11..2bd64e3f 100644 --- a/doc/sandboxing.rst +++ b/doc/sandboxing.rst @@ -198,7 +198,7 @@ Prevent access to function references in the call stack: * Prevent access to ``Duktape.act()`` which provides programmatic access to the call stack and its function references. -* If ``DUK_OPT_NONSTD_FUNC_CALLER_PROPERTY`` is enabled, the ``caller`` +* If ``DUK_USE_NONSTD_FUNC_CALLER_PROPERTY`` is enabled, the ``caller`` property provides access to calling functions. Don't use this option with sandboxing, or at least carefully control the ``caller`` property values seen by the sandboxed code. diff --git a/doc/system-install.rst b/doc/system-install.rst index 63b88fb1..ef5cb07a 100644 --- a/doc/system-install.rst +++ b/doc/system-install.rst @@ -43,9 +43,3 @@ There a few limitations in this approach: struct alignment rules (among other things) may differ. In practice it's unlikely you'll run into problems, at least when using mainline compilers like gcc/clang. - -Before Duktape 1.3 the application would also need to use the same feature -options (``DUK_OPT_xxx``) used when compiling the shared Duktape library. -However, as of Duktape 1.3 all the relevant config options (``DUK_USE_xxx``) -are encapsulated in ``duk_config.h`` so they can be modified without relying -on command line feature options. diff --git a/doc/testcase-known-issues.yaml b/doc/testcase-known-issues.yaml index ce53e013..6012441a 100644 --- a/doc/testcase-known-issues.yaml +++ b/doc/testcase-known-issues.yaml @@ -101,28 +101,28 @@ specialoptions: "test case has been written for Finnish locale" - test: "test-bi-duktape-json-lightfunc.js" - specialoptions: "DUK_OPT_LIGHTFUNC_BUILTINS" + specialoptions: "DUK_USE_LIGHTFUNC_BUILTINS" - test: "test-bi-function-nonstd-caller-prop.js" - specialoptions: "DUK_OPT_NONSTD_FUNC_CALLER_PROPERTY" + specialoptions: "DUK_USE_NONSTD_FUNC_CALLER_PROPERTY" - test: "test-dev-16bit-overflows.js" specialoptions: "requires 16-bit field options" - test: "test-dev-lightfunc-accessor.js" - specialoptions: "DUK_OPT_LIGHTFUNC_BUILTINS" + specialoptions: "DUK_USE_LIGHTFUNC_BUILTINS" - test: "test-dev-lightfunc-finalizer.js" - specialoptions: "DUK_OPT_LIGHTFUNC_BUILTINS" + specialoptions: "DUK_USE_LIGHTFUNC_BUILTINS" - test: "test-dev-lightfunc.js" - specialoptions: "DUK_OPT_LIGHTFUNC_BUILTINS" + specialoptions: "DUK_USE_LIGHTFUNC_BUILTINS" - test: "test-dev-logicalnot-refcount.js" specialoptions: "requires refcounting" - test: "test-dev-nonstd-setget-key-argument.js" - specialoptions: "should work with default options, but will break with DUK_OPT_NO_NONSTD_ACCESSOR_KEY_ARGUMENT" + specialoptions: "should work with default options, but will break with DUK_USE_NONSTD_GETTER_KEY_ARGUMENT or DUK_USE_NONSTD_SETTER_KEY_ARGUMENT" - test: "test-bi-typedarray-nan-handling.js" specialoptions: "NaN sign is platform dependent" diff --git a/doc/timing-sensitive.rst b/doc/timing-sensitive.rst index 75309d7a..8fe896eb 100644 --- a/doc/timing-sensitive.rst +++ b/doc/timing-sensitive.rst @@ -19,7 +19,7 @@ Suggested feature options ========================= * Use the default memory management settings (reference counting and - mark-and-sweep) but enable ``DUK_OPT_NO_VOLUNTARY_GC`` to eliminate + mark-and-sweep) but disable ``DUK_USE_VOLUNTARY_GC`` to eliminate mark-and-sweep pauses. Use explicit GC calls (either ``duk_gc()`` from C or ``Duktape.gc()`` from Ecmascript) when possible to collect circular references.