notes/knobs

   1 0 Content
   2 =========
   3
   4 1 Introduction
   5 2 Condensed list of defines and environment variables
   6 3 Defines tweaking SVN defaults
   7 4 Defines enabling or disabling features
   8 5 Defines controlling debug support
   9 6 Defines that affect unit tests
  10 7 Environment variables
  11
  12
  13 1 Introduction
  14 ==============
  15
  16 This is a document intended for use by Subversion developers only.
  17 In particular, interface naming rules do not apply here. I.e. even
  18 SVN_* identifiers are not part of the public API unless declared
  19 as public in some public header file.
  20
  21 The SVN source code boasts a number of environment variable or C pre-
  22 processor enabled tweaks that are mainly aimed at developer support.
  23 If you introduce new ones, please document them here.
  24
  25 Macros documented in the configure-generated ../subversion/svn_private_config.h
  26 file are not repeated here.
  27
  28
  29 2 Defines and Environment Variables
  30 ===================================
  31
  32 2.1 Defaults
  33
  34 DEFAULT_FS_TYPE
  35 DEFAULT_HTTP_LIBRARY
  36 MAX_SECS_TO_LINGER
  37 SUFFIX_LINES_TO_KEEP
  38 SVN_FS_FS_DEFAULT_MAX_FILES_PER_DIR
  39 SVN_FS_FS_MAX_LINEAR_DELTIFICATION
  40 SVN_FS_FS_MAX_DELTIFICATION_WALK
  41 SVN_UNALIGNED_ACCESS_IS_OK
  42
  43 2.2 Features
  44
  45 CHECK_FOR_SAME_FILE
  46 SVN_DIFF3_HAS_DIFF_PROGRAM_ARG
  47 SVN_DISABLE_ENTRY_CACHE
  48 SVN_MERGE__ALLOW_ALL_FORWARD_MERGES_FROM_SELF
  49 SVN_USE_WIN32_CRASHHANDLER
  50 SVN_DAV_SEND_VTXN_NAME
  51 SVN_DISABLE_PREFIX_SUFFIX_SCANNING
  52 SVN_FS_FS_DELTIFY_DIRECTORIES
  53 SVN_FS_FS_DELTIFY_PROPS
  54 SVN_SQLITE_MIN_VERSION_NUMBER
  55 SVN_SQLITE_MIN_VERSION
  56 SVN_SERF_NO_LOGGING
  57 SVN_ALLOW_SHORT_INTS
  58 SVN_ALLOW_NON_8_BIT_CHARS
  59 SVNXX_USE_BOOST
  60
  61 2.3 Debugging Support
  62
  63 SVN_DBG_QUIET
  64 SVN_DEBUG
  65 SVN_CLIENT_COMMIT_DEBUG
  66 SVN_DEBUG_CACHE_DUMP_STATS
  67 SVN_DEBUG_CACHE_MEMBUFFER
  68 SVN_DEBUG_DSO
  69 SVN_DEBUG_WORK_QUEUE
  70 PACK_AFTER_EVERY_COMMIT [removed]
  71 DEBUG_DOUBLE_FREE
  72 SERF_VERBOSE
  73 SSL_VERBOSE
  74 SVN_DEPRECATED
  75 SVN_FS__TRAIL_DEBUG
  76 SVN_FS_FS__LOG_ACCESS
  77 SVN_FS_EMULATE_PATHS_CHANGED
  78 SVN_FS_EMULATE_REPORT_CHANGES
  79 SVNXX_POOL_DEBUG
  80
  81 2.4 Test-only
  82
  83 QUOPRINT_SVNDIFFS
  84 SVN_ENABLE_DEPRECATION_WARNINGS_IN_TESTS
  85 TEST16K_ADD
  86
  87 2.5 Environment Variables
  88
  89 SVNSYNC_UNSUPPORTED_STRIP_MERGEINFO
  90 SVNSYNC_UNSUPPORTED_MIGRATE_SVNMERGE
  91 SVN_CMDLINE_DISABLE_CRASH_HANDLER
  92 SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_RELOCATE_VALIDATION
  93 SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_SLEEP_FOR_TIMESTAMPS
  94 SVN_I_LOVE_PANGALACTIC_GARGLE_BLASTERS
  95 SVN_I_LIKE_LATENCY_SO_IGNORE_HTTPV2
  96
  97
  98 3 Defines tweaking SVN defaults
  99 ===============================
 100
 101 3.1 DEFAULT_FS_TYPE
 102
 103   Scope:     (global)
 104   Purpose:   selects the default FS type to be used for a new repository
 105              if no type is provided
 106   Range:     strings "fsfs", "bdb"
 107   Default:   "fsfs"
 108   Suggested: "fsfs"
 109
 110 3.2 DEFAULT_HTTP_LIBRARY
 111
 112   Scope:     (global)
 113   Purpose:   selects the default http library to be used for accessing
 114              remote repositories using http/https protocol
 115   Range:     strings "serf", "neon"
 116   Default:   "serf"
 117   Suggested: "serf"
 118
 119 3.3 MAX_SECS_TO_LINGER
 120
 121   Scope:     svn protocol
 122   Purpose:
 123   Range:
 124   Default:   30
 125   Suggested:
 126
 127 3.4 SUFFIX_LINES_TO_KEEP
 128
 129   Scope:     libsvn_diff
 130   Purpose:   control the identical prefix / identical suffix diff(blame)
 131              optimizations.
 132   Range:     natural integers
 133   Default:   50
 134   Suggested: 0, 1, 999999
 135
 136 3.5 SVN_FS_FS_DEFAULT_MAX_FILES_PER_DIR
 137
 138   Scope:     libsvn_fs_fs
 139   Purpose:   set fsfs default shard size
 140   Default:   1000
 141   Range:     natural integers
 142   Suggested: 1, 2, 3, 4, 5, 7, 11
 143
 144 3.6 SVN_FS_FS_MAX_LINEAR_DELTIFICATION
 145
 146   Scope:     libsvn_fs_fs
 147   Purpose:   Controls the space efficiency vs. reconstruction costs tradeoff
 148              of rep deltification.  Defines the max length of the linear
 149              deltification history before skip-deltification kicks in.
 150              Values < 2 result in skip-delta-only behavior.
 151   Default:   16
 152   Range:     natural integers; should be a power of 2
 153   Suggested: 1, 4, 8, 16, 32, 64
 154
 155 3.7 SVN_FS_FS_MAX_DELTIFICATION_WALK
 156
 157   Scope:     libsvn_fs_fs
 158   Purpose:   Limits the skip deltification range to provide commit runtime
 159              guarantees. Change histories longer than that will be restarted
 160              with a fulltext.  Values < 1 disable deltification.
 161   Default:   1023
 162   Range:     natural integers; should be a power of 2 minus one
 163   Suggested: 0, 63, 1023, 4095, 16383
 164
 165 3.8 SVN_UNALIGNED_ACCESS_IS_OK
 166
 167   Scope:     (global)
 168   Purpose:   enable data accesss optimizations.
 169              If your target CPU supports unaligned memory access without
 170              significant performance penalties, you should enable this
 171              optimization as it allows for processing 4 or 8 bytes at
 172              once instead of just one byte at a time.
 173   Range:     0 1
 174   Default:   platform dependant (see svn_types.h)
 175   Suggested: 0
 176
 177
 178 4 Defines enabling or disabling features
 179 ========================================
 180
 181 4.1 CHECK_FOR_SAME_FILE
 182
 183   Scope:     libsvn_subr (file copy)
 184   Purpose:   Test whether we try to do no-op file copies. If defined,
 185              svn_io_copy_file() will return an error when source and
 186              destination are the same file.
 187   Range:     definedness
 188   Default:   not defined
 189   Suggested: not defined
 190
 191 4.2 SVN_DIFF3_HAS_DIFF_PROGRAM_ARG
 192
 193   Scope:     libsvn_subr
 194   Purpose:
 195   Range:     definedness
 196   Default:   not defined
 197   Suggested: defined, not defined
 198
 199 4.3 SVN_DISABLE_ENTRY_CACHE
 200
 201   Scope:     libsvn_wc
 202   Purpose:   If defined, ADM entries will not be cached.
 203   Range:     definedness
 204   Default:   not defined
 205   Suggested: defined, not defined
 206
 207 4.4 SVN_MERGE__ALLOW_ALL_FORWARD_MERGES_FROM_SELF
 208
 209   Scope:     libsvn_client
 210   Purpose:
 211   Range:     definedness
 212   Default:   not defined
 213   Suggested: not defined
 214
 215 4.5 SVN_USE_WIN32_CRASHHANDLER
 216
 217   Scope:     libsvn_subr
 218   Purpose:   Define this in the Win32 platform if you want to enable the
 219              crash handler allowing for post-mortem analysis after fatal
 220              application failures.
 221   Range:     definedness
 222   Default:   defined (Windows only), not defined (elsewhere)
 223   Suggested: defined (Windows only), not defined
 224
 225 4.6 SVN_DAV_SEND_VTXN_NAME
 226
 227   Scope:     libsvn_ra_serf, libsvn_ra_neon
 228   Purpose:   Testing VTXN name for v2 commits.
 229              Defining this causes the client to send a VTXN name header.
 230   Range:     definedness
 231   Default:   not defined
 232   Suggested: defined, not defined
 233
 234 4.7 SVN_DISABLE_PREFIX_SUFFIX_SCANNING
 235
 236   Scope:     libsvn_diff
 237   Purpose:   Define this symbol to disable the prefix/suffix scanning
 238              of the diff processing, letting all lines be handled by the
 239              full-fledged diff algorithm (with LCS algorithm). This define
 240              can be useful for focusing on testing the LCS algorithm, or
 241              for comparing diff performance with and without prefix/suffix
 242              scanning.
 243   Range:     definedness
 244   Default:   not defined
 245   Suggested: not defined
 246
 247 4.8 SVN_FS_FS_DELTIFY_DIRECTORIES
 248
 249   Scope:     libsvn_fs_fs
 250   Purpose:   Define this symbol to enable directory deltification in FSFS.
 251              When activated, previous versions of Subversion will still be
 252              able to read from and write to this repository.
 253   Range:     definedness
 254   Default:   not defined
 255   Suggested: defined
 256
 257 4.9 SVN_FS_FS_DELTIFY_PROPS
 258
 259   Scope:     libsvn_fs_fs
 260   Purpose:   Define this symbol to enable node property deltification in
 261              FSFS.  When activated, previous versions of Subversion will
 262              still be able to read from and write to this repository.
 263   Range:     definedness
 264   Default:   not defined
 265   Suggested: not defined
 266
 267 4.10 SVN_SQLITE_MIN_VERSION_NUMBER
 268
 269   Scope:     libsvn_subr
 270   Purpose:   The minimum SQLite version to have run-time support for.
 271   Range:     SQLite version numbers, as packed integers
 272   Default:   SQLITE_VERSION_NUMBER (i.e., the compile-time-sqlite version)
 273   Suggested: not defined (to use default)
 274
 275 4.11 SVN_SQLITE_MIN_VERSION
 276
 277   Scope:     libsvn_subr
 278   Purpose:   See SVN_SQLITE_MIN_VERSION_NUMBER.  The two must be overridden
 279              (or not overridden) together; defining one but leaving the other
 280              at its default will cause undefined behaviour.
 281   Range:     SQLite versions, as string literals
 282   Default:   SQLITE_VERSION
 283   Suggested: not defined (to use default)
 284
 285 4.11 SVN_ALLOW_SHORT_INTS
 286
 287   Scope:     global
 288   Purpose:   Disables the size check for the 'int' type.  We assume ints to
 289              be large enough (32 bits) to index various container objects.
 290              16 ints will break that assumption.  Defining this option will
 291              allow SVN to be compiled even if the size check would fail for
 292              some reason.
 293   Range:     definedness
 294   Default:   not defined
 295   Suggested: not defined (to ensure correct behaviour)
 296
 297 4.12 SVN_ALLOW_NON_8_BIT_CHARS
 298
 299   Scope:     global
 300   Purpose:   Disables the size check for the 'char' type.  We assume char
 301              has exactly 8 bits.  Other values may break the code reading,
 302              interpreting and writing repository files.  Defining this option
 303              will allow SVN to be compiled even if the size check would fail
 304              for some reason.
 305   Range:     definedness
 306   Default:   not defined
 307   Suggested: not defined (to ensure correct behaviour)
 308
 309 4.13 SVNXX_USE_BOOST
 310   Scope:     SVN++ (subversion/bindings/cxx)
 311   Purpose:   Adds header-only conversions and overloads to make SVN++
 312              interoperate cleanly with selected Boost types. Defining this
 313              symbol does *not* affect the SVN++ ABI. Users may define the
 314              symbol when using SVN++ after libsvnxx has been built.
 315   Range:     definedness
 316   Default:   not defined
 317   Suggested: defined for testing SVN++, otherwise not defined
 318
 319 5 Defines controlling debug support
 320 ==================================
 321
 322 5.1 SVN_DBG_QUIET
 323
 324   Scope:     (global)
 325   Purpose:   Reduce noise created by SVN_DBG() statements.
 326              Defining this symbol in the source file, before including
 327              svn_debug.h, will switch off the debug output issued by
 328              SVN_DBG. Calls will still be made to svn_dbg__preamble()
 329              for breakpoints.
 330   Range:     definedness
 331   Default:   not defined
 332   Suggested: defined, not defined
 333
 334 5.2 SVN_DEBUG
 335
 336   Scope:     (global)
 337   Purpose:   Enables various, debug-mode-only checks and other development
 338              code. Never define this in release builds.
 339   Range:     definedness
 340   Default:   not defined
 341   Suggested: defined, not defined
 342
 343 5.3 SVN_CLIENT_COMMIT_DEBUG
 344
 345   Scope:     libsvn_client
 346   Purpose:   Enables detailed client-side SVN_DBG output during commits.
 347   Range:     definedness
 348              (if defined, SVN_DEBUG must be defined as well)
 349   Default:   not defined
 350   Suggested: defined, not defined
 351
 352 5.4 SVN_DEBUG_CACHE_DUMP_STATS
 353
 354   Scope:     FSFS
 355   Purpose:   Monitor FSFS object cache effectiveness.
 356              If defined, FSFS sessions will dump caching statistics
 357              to stdout just before the end of that session.
 358   Range:     definedness
 359   Default:   not defined
 360   Suggested: defined, not defined
 361
 362 5.5 SVN_DEBUG_CACHE_MEMBUFFER
 363
 364   Scope:     membuffer_cache
 365   Purpose:   Detecting logic issues like key collisions etc. within
 366              the membuffer_cache.
 367              If you define this macro, the getter functions of the
 368              membuffer_cache will performed expensive checks on the
 369              cached items, requested keys and entry types. If any
 370              mismatch is detected, therespective getter will return
 371              an error.
 372   Range:     definedness
 373   Default:   not defined
 374   Suggested: defined, not defined
 375
 376 5.6 SVN_DEBUG_DSO
 377
 378   Scope:     libsvn_subr (dso)
 379   Purpose:   detection of failures of dynamic loading of libraries
 380   Range:     definedness
 381   Default:   not defined
 382   Suggested: defined, not defined
 383
 384 5.7 SVN_DEBUG_WORK_QUEUE
 385
 386   Scope:     libsvn_wc (workqueue)
 387   Purpose:   protocol workqueue operations via SVN_DBG
 388   Range:     definedness
 389   Default:   not defined
 390   Suggested: defined, not defined
 391
 392 5.8 PACK_AFTER_EVERY_COMMIT [removed]
 393
 394   *** REMOVED in r1602871 (1.9-dev) ***
 395
 396   Scope:     libsvn_fs (only affects libsvn_fs_fs)
 397   Purpose:   stress test
 398   Range:     definedness
 399   Default:   not defined
 400   Suggested: defined, not defined
 401
 402 5.9 DEBUG_DOUBLE_FREE
 403
 404   Scope:     serf
 405   Purpose:   detect double-free calls to serf_bucket_mem_free()
 406   Range:     definedness
 407   Default:   defined
 408   Suggested: defined, not defined
 409
 410 5.10 SERF_VERBOSE
 411
 412   Scope:     serf
 413   Purpose:   write protocol handling debug information to stdout
 414   Range:     definedness
 415   Default:   not defined
 416   Suggested: defined, not defined
 417
 418 5.11 SSL_VERBOSE
 419
 420   Scope:     serf
 421   Purpose:   write SSL bucket handling debug information to stdout
 422   Range:     definedness
 423   Default:   not defined
 424   Suggested: defined, not defined
 425
 426 5.12 SVN_DEPRECATED
 427
 428   Scope:     (everywhere)
 429   Purpose:   disable "deprecated function calls" warnings
 430   Range:     function declaration decorator
 431   Default:   (compiler dependant)
 432   Suggested: "" (disable deprecation warnings), or compiler-specific decorators
 433
 434 5.13 SVN_FS__TRAIL_DEBUG
 435
 436   Scope:     libsvn_fs_base
 437   Purpose:
 438   Range:     definedness
 439   Default:   not defined
 440   Suggested: defined, not defined
 441
 442 5.14 SVN_FS_FS__LOG_ACCESS
 443
 444   Scope:     libsvn_fs_fs/cached_data.c
 445   Purpose:   logs type and location info for any fsfs data access above the
 446              cache layer to console (i.e. what data gets requested from FSFS
 447              rather than disk)
 448   Range:     definedness
 449   Default:   not defined
 450   Suggested: defined, not defined
 451
 452 5.15 SVN_FS_EMULATE_PATHS_CHANGED
 453
 454   Scope:     libsvn_fs/fs-loader.c
 455   Purpose:   Force svn_fs_paths_changed2 to be emulated through
 456              svn_fs_paths_changed3 even if the FS provides an implementation
 457              of the former.
 458   Range:     TRUE, FALSE
 459   Default:   TRUE (local default if macro has not been defined)
 460   Suggested: FALSE
 461
 462 5.16 SVN_FS_EMULATE_REPORT_CHANGES
 463
 464   Scope:     libsvn_fs/fs-loader.c
 465   Purpose:   Force svn_fs_paths_changed3 to be emulated through
 466              svn_fs_paths_changed2 even if the FS provides an implementation
 467              of the former.
 468   Range:     TRUE, FALSE
 469   Default:   TRUE (local default if macro has not been defined)
 470   Suggested: FALSE
 471
 472 5.17 SVNXX_POOL_DEBUG
 473
 474   Scope:     SVN++ (subversion/bindings/cxx)
 475   Purpose:   Logs debugging info about the lifetime of the SVN++ global pool.
 476              Depends on SVN_DEBUG being defined.
 477   Range:     definedness
 478   Default:   not defined
 479   Suggested: defined, not defined
 480
 481 6 Defines that affect unit tests
 482 ================================
 483
 484 6.1 QUOPRINT_SVNDIFFS
 485
 486   Scope:     svndiff-test
 487   Purpose:
 488   Range:     definedness
 489   Default:   not defined
 490   Suggested: defined, not defined
 491
 492 6.2 SVN_ENABLE_DEPRECATION_WARNINGS_IN_TESTS
 493
 494   Scope:     (all tests)
 495   Purpose:
 496   Range:     definedness
 497   Default:   not defined
 498   Suggested: defined, not defined
 499
 500 6.3 TEST16K_ADD
 501
 502   Scope:     client-test
 503   Purpose:   If defined, an expensive test will be activated that adds
 504              16384 files in single folder and commits that. This is used
 505              to detect performance abnormalies. Typical runtimes are 20
 506              to 200 seconds.
 507   Range:     definedness
 508   Default:   not defined
 509   Suggested: defined, not defined
 510
 511
 512 7 Environment variables:
 513 ========================
 514
 515 7.1 SVNSYNC_UNSUPPORTED_STRIP_MERGEINFO
 516
 517   Scope:
 518   Purpose:
 519
 520 7.2 SVNSYNC_UNSUPPORTED_MIGRATE_SVNMERGE
 521
 522   Scope:
 523   Purpose:
 524
 525 7.3. SVN_CMDLINE_DISABLE_CRASH_HANDLER
 526
 527   Scope:     All command line executables. Windows specific.
 528   Purpose:   Setting any value disables internal Subversion crash handler
 529              for creating minidump and stack trace information on failure on
 530              Windows.
 531
 532 7.4 SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_RELOCATE_VALIDATION
 533
 534   Scope:
 535   Purpose:
 536
 537 7.5 SVN_I_LOVE_CORRUPTED_WORKING_COPIES_SO_DISABLE_SLEEP_FOR_TIMESTAMPS
 538
 539   Scope:
 540   Purpose:
 541
 542 7.6 SVN_I_LOVE_PANGALACTIC_GARGLE_BLASTERS
 543
 544   Scope:
 545   Purpose:
 546
 547 7.7 SVN_I_LIKE_LATENCY_SO_IGNORE_HTTPV2
 548
 549   Scope:     libsvn_ra_neon and libsvn_ra_serf, if SVN_DEBUG
 550   Purpose:   A "yes" value causes the RA modules to ignore the server's
 551              advertisement of HTTPv2 protocol support (if any), effectively
 552              causing them to only speak our original HTTP protocol.
 553
 554 7.8 SVN_SVNMUCC_IS_SVNSYITF
 555
 556   Scope:     'make install-tools'
 557   Purpose:   Symlinks $prefix/bin/svnsyitf to $prefix/bin/svnmucc
 558
 559 7.9 SVN_X_DOES_NOT_MARK_THE_SPOT
 560
 561   Scope:     svn_cache__t subsystem (used by FSFS, svnserve, etc)
 562   Purpose:   Disable the subsystem.  Requires -D SVN_DEBUG.
 563
 564 * (TODO: others)
 565