Internal doc changes for DUK_OPT_xxx removal

svaarala · Sep 6, 2016 · 9bf2fb9 · 9bf2fb9
1 parent 66d5588
commit 9bf2fb9
Show file tree

Hide file tree

Showing 17 changed files with 133 additions and 236 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git 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.