Author: stefan2
Date: Mon May 9 20:54:37 2011
New Revision: 1101219
URL: http://svn.apache.org/viewvc?rev=1101219&view=rev
Log:
* notes/knobs: reformat; add all SVN-specific defines used by #ifdef or #ifndef
Modified:
subversion/trunk/notes/knobs
Modified: subversion/trunk/notes/knobs
URL:
http://svn.apache.org/viewvc/subversion/trunk/notes/knobs?rev=1101219&r1=1101218&r2=1101219&view=diff
==============================================================================
--- subversion/trunk/notes/knobs (original)
+++ subversion/trunk/notes/knobs Mon May 9 20:54:37 2011
@@ -1,62 +1,339 @@
+0 Content
+=========
-This files documents various debugging knobs in Subversion.
-
-The usual namespace rules apply: only names that begin with "SVN_" and don't
-contain double underscores are considered part of the public API. Everything
-else is not officially supported.
-
-Compile-time:
-=============
-
-* SUFFIX_LINES_TO_KEEP
- Scope: libsvn_diff
- Purpose: control the identical prefix / identical suffix diff(blame)
optimizations.
- Range: natural integers
- Default: 50
+1 Introduction
+2 Condensed list of defines and environment variables
+3 Defines tweaking SVN defaults
+4 Defines enabling or disabling features
+5 Defines controling debug support
+6 Defines that affect unit tests
+7 Environment variables
+
+
+1 Introduction
+==============
+
+The SVN source code boasts a number of enviroment variable or C pre-
+processor enabled tweaks that are mainly aimed at developer support.
+If you introduce new ones, please document them here.
+
+The usual namespace rules apply: only names that begin with "SVN_"
+and don't contain double underscores are considered part of the public
+API. Everything else is not officially supported.
+
+
+2 Defines and Environment Variables
+===================================
+
+2.1 Defaults
+
+DEFAULT_FS_TYPE
+MAX_SECS_TO_LINGER
+SUFFIX_LINES_TO_KEEP
+SVN_FS_FS_DEFAULT_MAX_FILES_PER_DIR
+SVN_UNALIGNED_ACCESS_IS_OK
+
+2.2 Features
+
+CHECK_FOR_SAME_FILE
+SVN_DIFF3_HAS_DIFF_PROGRAM_ARG
+SVN_DISABLE_ENTRY_CACHE
+SVN_MERGE__ALLOW_ALL_FORWARD_MERGES_FROM_SELF
+SVN_USE_WIN32_CRASHHANDLER
+SVN_SERF_SEND_VTXN_NAME
+
+2.3 Debugging Support
+
+SVN_DBG_QUIET
+SVN_DEBUG
+SVN_CLIENT_COMMIT_DEBUG
+DEBUG_CACHE_DUMP_STATS
+DEBUG_CACHE_MEMBUFFER
+DEBUG_WORK_QUEUE
+PACK_AFTER_EVERY_COMMIT
+DEBUG_DOUBLE_FREE
+SERF_VERBOSE
+SSL_VERBOSE
+
+2.4 Test-only
+
+QUOPRINT_SVNDIFFS
+SVN_ENABLE_DEPRECATION_WARNINGS_IN_TESTS
+TEST16K_ADD
+
+2.5 Environment Variables
+
+SVNSYNC_UNSUPPORTED_STRIP_MERGEINFO
+SVNSYNC_UNSUPPORTED_MIGRATE_SVNMERGE
+SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_RELOCATE_VALIDATION
+SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_SLEEP_FOR_TIMESTAMPS
+SVN_I_LOVE_PANGALACTIC_GARGLE_BLASTERS
+SVN_I_LIKE_LATENCY_SO_IGNORE_HTTPV2
+
+
+3 Defines tweaking SVN defaults
+===============================
+
+3.1 DEFAULT_FS_TYPE
+
+ Scope: (global)
+ Purpose: selects the default FS type to be used for a new repository
+ if no type is provided
+ Range: strings "fsfs", "bdb"
+ Default: "fsfs"
+ Suggested: "fsfs"
+
+3.2 MAX_SECS_TO_LINGER
+
+ Scope: svn protocol
+ Purpose:
+ Range:
+ Default: 30
+ Suggested:
+
+3.3 SUFFIX_LINES_TO_KEEP
+
+ Scope: libsvn_diff
+ Purpose: control the identical prefix / identical suffix diff(blame)
+ optimizations.
+ Range: natural integers
+ Default: 50
Suggested: 0, 1, 999999
-* PACK_AFTER_EVERY_COMMIT
- Scope: libsvn_fs (only affects libsvn_fs_fs)
- Purpose: stress test
- Range: boolean
-
-* SVN_DEPRECATED
- Scope: (everywhere)
- Purpose: disable "deprecated function calls" warnings
- Range: function declaration decorator
- Default: (compiler dependant)
- Suggested: "" (disable those warnings)
-
-* SVN_FS_FS_DEFAULT_MAX_FILES_PER_DIR
- Scope: libsvn_fs_fs
- Purpose: set fsfs default shard size
- Default: 1000
- Range: natural integers
+3.4 SVN_FS_FS_DEFAULT_MAX_FILES_PER_DIR
+
+ Scope: libsvn_fs_fs
+ Purpose: set fsfs default shard size
+ Default: 1000
+ Range: natural integers
Suggested: 1, 2, 3, 4, 5, 7, 11
-* SVN_UNALIGNED_ACCESS_IS_OK
- Scope: ?
- Purpose: enable memory operations optimizations
- Range: boolean values (must be defined)
- Default: platform dependant
+3.5 SVN_UNALIGNED_ACCESS_IS_OK
+
+ Scope: (global)
+ Purpose: enable data accesss optimizations.
+ If your target CPU supports unaligned memory access without
+ significant performance penalties, you should enable this
+ optimization as it allows for processing 4 or 8 bytes at
+ once instead of just one byte at a time.
+ Range: 0 1
+ Default: platform dependant (see svn_types.h)
Suggested: 0
-* (TODO: others)
-Environment variables:
-======================
+4 Defines enabling or disabling features
+========================================
+
+4.1 CHECK_FOR_SAME_FILE
+
+ Scope: libsvn_subr (file copy)
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: not defined
+
+4.2 SVN_DIFF3_HAS_DIFF_PROGRAM_ARG
+
+ Scope: libsvn_subr
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+4.3 SVN_DISABLE_ENTRY_CACHE
+
+ Scope: libsvn_wc
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+4.4 SVN_MERGE__ALLOW_ALL_FORWARD_MERGES_FROM_SELF
+
+ Scope: libsvn_client
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: not defined
+
+4.5 SVN_USE_WIN32_CRASHHANDLER
+
+ Scope: libsvn_subr
+ Purpose:
+ Range: definedness
+ Default: defined (Windows only), not defined (elsewhere)
+ Suggested: defined (Windows only), not defined
+
+4.6 SVN_SERF_SEND_VTXN_NAME
+
+ Scope: serf
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+
+5 Defines controling debug support
+==================================
+
+5.1 SVN_DBG_QUIET
+
+ Scope: (global)
+ Purpose: Reduce noise created by SVN_DBG() statements.
+ Defining this symbol in the source file, before including
+ svn_debug.h, will switch off the debug output issued by
+ SVN_DBG. Calls will still be made to svn_dbg__preamble()
+ for breakpoints.
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.2 SVN_DEBUG
+
+ Scope: (global)
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.3 SVN_CLIENT_COMMIT_DEBUG
+
+ Scope: libsvn_client
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.4 DEBUG_CACHE_DUMP_STATS
+
+ Scope: FSFS
+ Purpose: Monitor FSFS object cache effectiveness.
+ If defined, FSFS sessions will dump caching statistics
+ to stdout just before the end of that session.
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.5 DEBUG_CACHE_MEMBUFFER
+
+ Scope: membuffer_cache
+ Purpose: Detecting logic issues like key collisions etc. within
+ the membuffer_cache.
+ If you define this macro, the getter functions of the
+ membuffer_cache will performed expensive checks on the
+ cached items, requested keys and entry types. If any
+ mismatch is detected, therespective getter will return
+ an error.
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.7 DEBUG_WORK_QUEUE
+
+ Scope: libsvn_wc (workqueue)
+ Purpose: protocol workqueue operations via SVN_DBG
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.8 PACK_AFTER_EVERY_COMMIT
+
+ Scope: libsvn_fs (only affects libsvn_fs_fs)
+ Purpose: stress test
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.6 DEBUG_DOUBLE_FREE
+
+ Scope: serf
+ Purpose: detect double-free calls to serf_bucket_mem_free()
+ Range: definedness
+ Default: defined
+ Suggested: defined, not defined
+
+5.9 SERF_VERBOSE
+
+ Scope: serf
+ Purpose: write protocol handling debug information to stdout
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+5.10 SSL_VERBOSE
+
+ Scope: serf
+ Purpose: write SSL bucket handling debug information to stdout
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+
+6 Defines that affect unit tests
+================================
+
+6.1 QUOPRINT_SVNDIFFS
+
+ Scope: svndiff-test
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+6.2 SVN_ENABLE_DEPRECATION_WARNINGS_IN_TESTS
+
+ Scope: (all tests)
+ Purpose:
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+6.3 TEST16K_ADD
+
+ Scope: client-test
+ Purpose: If defined, an expensive test will be activated that adds
+ 16384 files in single folder and commits that. This is used
+ to detect performance abnormalies. Typical runtimes are 20
+ to 200 seconds.
+ Range: definedness
+ Default: not defined
+ Suggested: defined, not defined
+
+
+7 Environment variables:
+========================
+
+7.1 SVNSYNC_UNSUPPORTED_STRIP_MERGEINFO
+
+ Scope:
+ Purpose:
+
+7.2 SVNSYNC_UNSUPPORTED_MIGRATE_SVNMERGE
+
+ Scope:
+ Purpose:
+
+7.3 SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_RELOCATE_VALIDATION
+
+ Scope:
+ Purpose:
+
+7.4 SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_SLEEP_FOR_TIMESTAMPS
+
+ Scope:
+ Purpose:
+
+7.5 SVN_I_LOVE_PANGALACTIC_GARGLE_BLASTERS
+
+ Scope:
+ Purpose:
+
+7.6 SVN_I_LIKE_LATENCY_SO_IGNORE_HTTPV2
-* SVNSYNC_UNSUPPORTED_STRIP_MERGEINFO
-* SVNSYNC_UNSUPPORTED_MIGRATE_SVNMERGE
-* SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_RELOCATE_VALIDATION
-* SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_SLEEP_FOR_TIMESTAMPS
-* SVN_I_LOVE_PANGALACTIC_GARGLE_BLASTERS
-
-* SVN_I_LIKE_LATENCY_SO_IGNORE_HTTPV2
- Scope: libsvn_ra_neon and libsvn_ra_serf, if SVN_DEBUG
- Purpose: A "yes" value causes the RA modules to ignore the server's
- advertisement of HTTPv2 protocol support (if any), effectively
- causing them to only speak our original HTTP protocol.
+ Scope: libsvn_ra_neon and libsvn_ra_serf, if SVN_DEBUG
+ Purpose: A "yes" value causes the RA modules to ignore the server's
+ advertisement of HTTPv2 protocol support (if any), effectively
+ causing them to only speak our original HTTP protocol.
* (TODO: others)
