New file to try to document the "special build" preprocessor symbols.

Incomplete.  Add to it!  Once it settles down, it would make a nice
appendix in the real docs.

1 files changed, 76 insertions, 0 deletions

diff --git a/Misc/SpecialBuilds.txt b/Misc/SpecialBuilds.txt
new file mode 100644
index 0000000000..456c462bad
--- /dev/null
+++ b/Misc/SpecialBuilds.txt
@@ -0,0 +1,76 @@
+This file describes some special Python build types enabled via
+compile-time preprocessor defines.
+
+---------------------------------------------------------------------------
+Py_REF_DEBUG
+
+Turn on aggregate reference counting.  This arranges that extern
+_Py_RefTotal hold a count of all references, the sum of ob_refcnt across
+all objects.  In a debug-mode build, this is where the "8288" comes from
+in
+
+    >>> 23
+    23
+    [8288 refs]
+    >>>
+
+Note that if this count increases when you're not storing away new objects,
+there's probably a leak.  Remember, though, that in interactive mode the
+special name "_" holds a reference to the last result displayed!
+
+Py_REF_DEBUG also checks after every decref to verify that the refcount
+hasn't gone negative, and causes an immediate fatal error if it has.
+
+Special gimmicks:
+
+sys.gettotalrefcount()
+    Return current total of all refcounts.
+    Available under Py_REF_DEBUG in Python 2.3.
+    Before 2.3, Py_TRACE_REFS was required to enable this function.
+---------------------------------------------------------------------------
+Py_TRACE_REFS
+
+Turn on heavy reference debugging.  This is major surgery.  Every PyObject
+grows two more pointers, to maintain a doubly-linked list of all live
+heap-allocated objects (note that, e.g., most builtin type objects are not
+in this list, as they're statically allocated).  Note that because the
+fundamental PyObject layout changes, Python modules compiled with
+Py_TRACE_REFS are incompatible with modules compiled without it.
+
+Py_TRACE_REFS implies Py_REF_DEBUG.
+
+Special gimmicks:
+
+sys.getobjects(max[, type])
+    Return list of the most-recently allocated max objects, most recently
+    allocated first in the list, least-recently allocated last in the
+    list.  max=0 means no limit on list length.  If an optional type
+    object is passed, the list is also restricted to objects of that
+    type.
+
+envar PYTHONDUMPREFS
+    If this envar exists, Py_Finalize() arranges to print a list of
+    all still-live heap objects.
+---------------------------------------------------------------------------
+COUNT_ALLOCS
+
+Special gimmicks:
+
+sys.getcounts()
+---------------------------------------------------------------------------
+PYMALLOC_DEBUG
+
+Special gimmicks:
+
+envar PYTHONMALLOCSTATS
+    If this envar exists, a report of pymalloc summary statistics is
+    printed to stderr whenever a new arena is allocated, and also
+    by Py_Finalize().
+---------------------------------------------------------------------------
+Py_DEBUG
+
+This is what is generally meant by "a debug build" of Python.
+
+Py_DEBUG implies Py_REF_DEBUG, Py_TRACE_REFS, and PYMALLOC_DEBUG (if
+WITH_PYMALLOC is enabled).
+---------------------------------------------------------------------------