1This file describes some special Python build types enabled via compile-time 2preprocessor directives. 3 4IMPORTANT: if you want to build a debug-enabled Python, it is recommended that 5you use ``./configure --with-pydebug``, rather than the options listed here. 6 7However, if you wish to define some of these options individually, it is best 8to define them in the EXTRA_CFLAGS make variable; 9``make EXTRA_CFLAGS="-DPy_REF_DEBUG"``. 10 11 12Py_REF_DEBUG 13------------ 14 15Turn on aggregate reference counting. This arranges that extern _Py_RefTotal 16hold a count of all references, the sum of ob_refcnt across all objects. 17Passing ``-X showrefcount`` on the command line causes the interactive 18interpreter to print the reference count total as well the number of memory 19blocks allocated after each statement: 20 21 >>> 23 22 23 23 [8288 refs, 14332 blocks] 24 >>> 25 26Note that if this count increases when you're not storing away new objects, 27there's probably a leak. Remember, though, that in interactive mode the special 28name "_" holds a reference to the last result displayed! 29 30Py_REF_DEBUG also checks after every decref to verify that the refcount hasn't 31gone negative, and causes an immediate fatal error if it has. 32 33Py_DEBUG implies Py_REF_DEBUG. 34 35Special gimmicks: 36 37sys.gettotalrefcount() 38 Return current total of all refcounts. 39 40 41Py_TRACE_REFS 42------------- 43 44Build option: ``./configure --with-trace-refs``. 45 46Turn on heavy reference debugging. This is major surgery. All live 47heap-allocated objects are traced in a hash table. Most built-in type objects 48are not in this list, as they're statically allocated. 49 50Special gimmicks: 51 52sys.getobjects(max[, type]) 53 Return list of the (no more than) max most-recently allocated objects, most 54 recently allocated first in the list, least-recently allocated last in the 55 list. max=0 means no limit on list length. If an optional type object is 56 passed, the list is also restricted to objects of that type. The return 57 list itself, and some temp objects created just to call sys.getobjects(), 58 are excluded from the return list. Note that the list returned is just 59 another object, though, so may appear in the return list the next time you 60 call getobjects(); note that every object in the list is kept alive too, 61 simply by virtue of being in the list. 62 63envvar PYTHONDUMPREFS 64 If this envvar exists, Py_FinalizeEx() arranges to print a list of all 65 still-live heap objects. This is printed twice, in different formats, 66 before and after Py_FinalizeEx has cleaned up everything it can clean up. The 67 first output block produces the repr() of each object so is more 68 informative; however, a lot of stuff destined to die is still alive then. 69 The second output block is much harder to work with (repr() can't be invoked 70 anymore -- the interpreter has been torn down too far), but doesn't list any 71 objects that will die. The tool script combinerefs.py can be run over this 72 to combine the info from both output blocks. The second output block, and 73 combinerefs.py, were new in Python 2.3b1. 74 75 76Py_DEBUG 77-------- 78 79This is what is generally meant by "a debug build" of Python. 80 81Py_DEBUG implies LLTRACE and Py_REF_DEBUG. In addition, C assert()s are enabled 82(via the C way: by not defining NDEBUG), and some routines do additional sanity 83checks inside "#ifdef Py_DEBUG" blocks. 84 85 86LLTRACE 87------- 88 89Compile in support for Low Level TRACE-ing of the main interpreter loop. 90 91When this preprocessor symbol is defined, before PyEval_EvalFrame executes a 92frame's code it checks the frame's global namespace for a variable 93"__lltrace__". If such a variable is found, mounds of information about what 94the interpreter is doing are sprayed to stdout, such as every opcode and opcode 95argument and values pushed onto and popped off the value stack. 96 97Not useful very often, but very useful when needed. 98 99Py_DEBUG implies LLTRACE. 100