Fossil SCM
Updated the temp file and dir location documentation in www/env-opts.md to match what the current code does.
Commit
1f63724e5b6fec167f1d482b0fa4f94369894a2df59e497e83cbd6c2c987cfb1
Parent
15176c8ae51a1e8…
1 file changed
+21
-45
+21
-45
| --- www/env-opts.md | ||
| +++ www/env-opts.md | ||
| @@ -184,25 +184,15 @@ | ||
| 184 | 184 | |
| 185 | 185 | `FOSSIL_TCL_PATH`: When Tcl stubs support is configured, point to a |
| 186 | 186 | specific file or folder containing the version of Tcl to load at run |
| 187 | 187 | time. |
| 188 | 188 | |
| 189 | -`FOSSIL_TEMP`: Fallback location of the temporary directories and files | |
| 190 | -created and deleted when running the test suite. The first environment | |
| 191 | -variable found in the environment from the list `FOSSIL_TEST_TEMP`, | |
| 192 | -`FOSSIL_TEMP`, `TEMP`, and `TMP` is used. | |
| 193 | - | |
| 194 | 189 | `FOSSIL_TEST_DANGEROUS_IGNORE_OPEN_CHECKOUT`: When set to the literal |
| 195 | 190 | value `YES_DO_IT`, the test suite will relax the constraint that some |
| 196 | 191 | tests may not run within an open checkout. This is subject to removal |
| 197 | 192 | in the future. |
| 198 | 193 | |
| 199 | -`FOSSIL_TEST_TEMP`: Primary location of the temporary directories | |
| 200 | -and files created and deleted when running the test suite. The | |
| 201 | -first environment variable found in the environment from the list | |
| 202 | -`FOSSIL_TEST_TEMP`, `FOSSIL_TEMP`, `TEMP`, and `TMP` is used. | |
| 203 | - | |
| 204 | 194 | `FOSSIL_VFS`: Name a VFS to load into SQLite. |
| 205 | 195 | |
| 206 | 196 | `GATEWAY_INTERFACE`: If present and the `--nocgi` option is not, assume |
| 207 | 197 | fossil is invoked from a web server as a CGI command, and act |
| 208 | 198 | accordingly. |
| @@ -268,16 +258,10 @@ | ||
| 268 | 258 | |
| 269 | 259 | |
| 270 | 260 | `SYSTEMROOT`: (Windows) Used to locate `notepad.exe` as a |
| 271 | 261 | fall back comment editor. |
| 272 | 262 | |
| 273 | -`TEMP`: On Windows, the location of temporary files. The first | |
| 274 | -environment variable found in the environment that names an existing | |
| 275 | -directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows | |
| 276 | -directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current | |
| 277 | -directory (aka `.`) is the temporary folder. | |
| 278 | - | |
| 279 | 263 | `TERM`: If the linenoise library is used (almost certainly not on |
| 280 | 264 | Windows), it will check `TERM` to verify that the interactive terminal |
| 281 | 265 | is not named on a short list on terminals known to not work with |
| 282 | 266 | linenoise. Linenoise is a library that provides command history and |
| 283 | 267 | command line editing to interactive programs, and can be used in the |
| @@ -305,16 +289,10 @@ | ||
| 305 | 289 | |
| 306 | 290 | `TH1_TEST_USER_CAPS`: Override the default user permissions used when |
| 307 | 291 | processing the `--set-user-caps` option for the `test-th-eval`, |
| 308 | 292 | `test-th-render`, and `test-th-source` test commands. |
| 309 | 293 | |
| 310 | -`TMP`: On Windows, the location of temporary files. The first | |
| 311 | -environment variable found in the environment that names an existing | |
| 312 | -directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows | |
| 313 | -directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current | |
| 314 | -directory (aka `.`) is the temporary folder. | |
| 315 | - | |
| 316 | 294 | `TMPDIR`: Names the temporary file location for SQLite. |
| 317 | 295 | |
| 318 | 296 | |
| 319 | 297 | `USER`: Name of the logged in user on many Unix-like platforms. |
| 320 | 298 | Used as the fossil user name if `FOSSIL_USER` is not specified. See |
| @@ -322,16 +300,10 @@ | ||
| 322 | 300 | |
| 323 | 301 | `USERNAME`: Name of the logged in user on Windows platforms. |
| 324 | 302 | Used as the fossil user name if `FOSSIL_USER` is not specified. See |
| 325 | 303 | the discussion of Fossil Username below for a lot more detail. |
| 326 | 304 | |
| 327 | -`USERPROFILE`: On Windows, the location of temporary files. The first | |
| 328 | -environment variable found in the environment that names an existing | |
| 329 | -directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows | |
| 330 | -directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current | |
| 331 | -directory (aka `.`) is the temporary folder. | |
| 332 | - | |
| 333 | 305 | `VISUAL`: Name the editor to use for check-in and stash comments. |
| 334 | 306 | Overrides the `EDITOR` environment variable. Overridden by the local |
| 335 | 307 | or global `editor` setting. |
| 336 | 308 | |
| 337 | 309 | |
| @@ -462,30 +434,34 @@ | ||
| 462 | 434 | precedence. |
| 463 | 435 | |
| 464 | 436 | |
| 465 | 437 | ### Temporary File Location |
| 466 | 438 | |
| 467 | -Fossil places some temporary files in the current directory, notably | |
| 439 | +Fossil places some temporary files in the checkout directory. Most notably, | |
| 468 | 440 | supporting files related to merge conflicts are placed in the same |
| 469 | 441 | folder as the merge result. |
| 470 | 442 | |
| 471 | -Other temporary files need a home. On Unix-like systems, the first | |
| 472 | -folder from the hard coded list `/var/tmp`, `/usr/tmp`, `/tmp`, | |
| 473 | -`/temp`, and `.` that is found to exist in the file system is used by | |
| 474 | -fossil. The SQLite library has its own code for finding a safe place for | |
| 475 | -temporary files. It checks the environment variables `SQLITE_TMPDIR` | |
| 476 | -and `TMPDIR` ahead of the hard coded list `/var/tmp`, `/usr/tmp`, | |
| 477 | -`/tmp`, and `.` for the first directory that exists. | |
| 478 | - | |
| 479 | -On Windows, fossil calls [`GetTempPath`][gtp], and also queries the | |
| 480 | -environment variables `TEMP`, and `TMP`. If none of those three places | |
| 481 | -exist, then it uses `.`. Notice that `GetTempPath` itself used `TMP`, | |
| 482 | -`TEMP`, `USERPROFILE`, and the Windows folder (named in the variable | |
| 483 | -`SystemRoot`). Since the Windows folder always exists, but in modern | |
| 484 | -versions of Windows is generally *not* writable by the logged in user, | |
| 485 | -not having `TEMP`, `TMP`, or `USERPROFILE` set is almost guaranteed to | |
| 486 | -cause trouble. | |
| 443 | +Other temporary files need a different home. The rules for choosing one are | |
| 444 | +complicated. | |
| 445 | + | |
| 446 | +Fossil-specific code uses `FOSSIL_TEMP`, `TEMP`, and `TMP`, in that | |
| 447 | +order. Fossil’s own test suite prepends `FOSSIL_TEST_TEMP` to that list. | |
| 448 | + | |
| 449 | +The underlying SQLite code uses several different path sets for its temp | |
| 450 | +files, depending on the platform type. | |
| 451 | + | |
| 452 | +On Unix-like platforms, excepting Cygwin, SQLite first checks the | |
| 453 | +environment variables `SQLITE_TMPDIR` and `TMPDIR`, in that order. If | |
| 454 | +neither is defined, it falls back to a hard-coded list of paths: | |
| 455 | +`/var/tmp`, `/usr/tmp`, and `/tmp`. If all of that fails, it uses the | |
| 456 | +current working directory. | |
| 457 | + | |
| 458 | +For Cygwin builds, SQLite instead uses the first defined variable in | |
| 459 | +this list: `SQLITE_TMPDIR`, `TMPDIR`, `TMP`, `TEMP`, and `USERPROFILE`. | |
| 460 | + | |
| 461 | +For native Windows builds, SQLite simply calls the OS’s [`GetTempPath()` | |
| 462 | +API][gtp]. See that reference page for details. | |
| 487 | 463 | |
| 488 | 464 | [gtp]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992%28v=vs.85%29.aspx |
| 489 | 465 | |
| 490 | 466 | |
| 491 | 467 | |
| 492 | 468 |
| --- www/env-opts.md | |
| +++ www/env-opts.md | |
| @@ -184,25 +184,15 @@ | |
| 184 | |
| 185 | `FOSSIL_TCL_PATH`: When Tcl stubs support is configured, point to a |
| 186 | specific file or folder containing the version of Tcl to load at run |
| 187 | time. |
| 188 | |
| 189 | `FOSSIL_TEMP`: Fallback location of the temporary directories and files |
| 190 | created and deleted when running the test suite. The first environment |
| 191 | variable found in the environment from the list `FOSSIL_TEST_TEMP`, |
| 192 | `FOSSIL_TEMP`, `TEMP`, and `TMP` is used. |
| 193 | |
| 194 | `FOSSIL_TEST_DANGEROUS_IGNORE_OPEN_CHECKOUT`: When set to the literal |
| 195 | value `YES_DO_IT`, the test suite will relax the constraint that some |
| 196 | tests may not run within an open checkout. This is subject to removal |
| 197 | in the future. |
| 198 | |
| 199 | `FOSSIL_TEST_TEMP`: Primary location of the temporary directories |
| 200 | and files created and deleted when running the test suite. The |
| 201 | first environment variable found in the environment from the list |
| 202 | `FOSSIL_TEST_TEMP`, `FOSSIL_TEMP`, `TEMP`, and `TMP` is used. |
| 203 | |
| 204 | `FOSSIL_VFS`: Name a VFS to load into SQLite. |
| 205 | |
| 206 | `GATEWAY_INTERFACE`: If present and the `--nocgi` option is not, assume |
| 207 | fossil is invoked from a web server as a CGI command, and act |
| 208 | accordingly. |
| @@ -268,16 +258,10 @@ | |
| 268 | |
| 269 | |
| 270 | `SYSTEMROOT`: (Windows) Used to locate `notepad.exe` as a |
| 271 | fall back comment editor. |
| 272 | |
| 273 | `TEMP`: On Windows, the location of temporary files. The first |
| 274 | environment variable found in the environment that names an existing |
| 275 | directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows |
| 276 | directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current |
| 277 | directory (aka `.`) is the temporary folder. |
| 278 | |
| 279 | `TERM`: If the linenoise library is used (almost certainly not on |
| 280 | Windows), it will check `TERM` to verify that the interactive terminal |
| 281 | is not named on a short list on terminals known to not work with |
| 282 | linenoise. Linenoise is a library that provides command history and |
| 283 | command line editing to interactive programs, and can be used in the |
| @@ -305,16 +289,10 @@ | |
| 305 | |
| 306 | `TH1_TEST_USER_CAPS`: Override the default user permissions used when |
| 307 | processing the `--set-user-caps` option for the `test-th-eval`, |
| 308 | `test-th-render`, and `test-th-source` test commands. |
| 309 | |
| 310 | `TMP`: On Windows, the location of temporary files. The first |
| 311 | environment variable found in the environment that names an existing |
| 312 | directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows |
| 313 | directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current |
| 314 | directory (aka `.`) is the temporary folder. |
| 315 | |
| 316 | `TMPDIR`: Names the temporary file location for SQLite. |
| 317 | |
| 318 | |
| 319 | `USER`: Name of the logged in user on many Unix-like platforms. |
| 320 | Used as the fossil user name if `FOSSIL_USER` is not specified. See |
| @@ -322,16 +300,10 @@ | |
| 322 | |
| 323 | `USERNAME`: Name of the logged in user on Windows platforms. |
| 324 | Used as the fossil user name if `FOSSIL_USER` is not specified. See |
| 325 | the discussion of Fossil Username below for a lot more detail. |
| 326 | |
| 327 | `USERPROFILE`: On Windows, the location of temporary files. The first |
| 328 | environment variable found in the environment that names an existing |
| 329 | directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows |
| 330 | directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current |
| 331 | directory (aka `.`) is the temporary folder. |
| 332 | |
| 333 | `VISUAL`: Name the editor to use for check-in and stash comments. |
| 334 | Overrides the `EDITOR` environment variable. Overridden by the local |
| 335 | or global `editor` setting. |
| 336 | |
| 337 | |
| @@ -462,30 +434,34 @@ | |
| 462 | precedence. |
| 463 | |
| 464 | |
| 465 | ### Temporary File Location |
| 466 | |
| 467 | Fossil places some temporary files in the current directory, notably |
| 468 | supporting files related to merge conflicts are placed in the same |
| 469 | folder as the merge result. |
| 470 | |
| 471 | Other temporary files need a home. On Unix-like systems, the first |
| 472 | folder from the hard coded list `/var/tmp`, `/usr/tmp`, `/tmp`, |
| 473 | `/temp`, and `.` that is found to exist in the file system is used by |
| 474 | fossil. The SQLite library has its own code for finding a safe place for |
| 475 | temporary files. It checks the environment variables `SQLITE_TMPDIR` |
| 476 | and `TMPDIR` ahead of the hard coded list `/var/tmp`, `/usr/tmp`, |
| 477 | `/tmp`, and `.` for the first directory that exists. |
| 478 | |
| 479 | On Windows, fossil calls [`GetTempPath`][gtp], and also queries the |
| 480 | environment variables `TEMP`, and `TMP`. If none of those three places |
| 481 | exist, then it uses `.`. Notice that `GetTempPath` itself used `TMP`, |
| 482 | `TEMP`, `USERPROFILE`, and the Windows folder (named in the variable |
| 483 | `SystemRoot`). Since the Windows folder always exists, but in modern |
| 484 | versions of Windows is generally *not* writable by the logged in user, |
| 485 | not having `TEMP`, `TMP`, or `USERPROFILE` set is almost guaranteed to |
| 486 | cause trouble. |
| 487 | |
| 488 | [gtp]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992%28v=vs.85%29.aspx |
| 489 | |
| 490 | |
| 491 | |
| 492 |
| --- www/env-opts.md | |
| +++ www/env-opts.md | |
| @@ -184,25 +184,15 @@ | |
| 184 | |
| 185 | `FOSSIL_TCL_PATH`: When Tcl stubs support is configured, point to a |
| 186 | specific file or folder containing the version of Tcl to load at run |
| 187 | time. |
| 188 | |
| 189 | `FOSSIL_TEST_DANGEROUS_IGNORE_OPEN_CHECKOUT`: When set to the literal |
| 190 | value `YES_DO_IT`, the test suite will relax the constraint that some |
| 191 | tests may not run within an open checkout. This is subject to removal |
| 192 | in the future. |
| 193 | |
| 194 | `FOSSIL_VFS`: Name a VFS to load into SQLite. |
| 195 | |
| 196 | `GATEWAY_INTERFACE`: If present and the `--nocgi` option is not, assume |
| 197 | fossil is invoked from a web server as a CGI command, and act |
| 198 | accordingly. |
| @@ -268,16 +258,10 @@ | |
| 258 | |
| 259 | |
| 260 | `SYSTEMROOT`: (Windows) Used to locate `notepad.exe` as a |
| 261 | fall back comment editor. |
| 262 | |
| 263 | `TERM`: If the linenoise library is used (almost certainly not on |
| 264 | Windows), it will check `TERM` to verify that the interactive terminal |
| 265 | is not named on a short list on terminals known to not work with |
| 266 | linenoise. Linenoise is a library that provides command history and |
| 267 | command line editing to interactive programs, and can be used in the |
| @@ -305,16 +289,10 @@ | |
| 289 | |
| 290 | `TH1_TEST_USER_CAPS`: Override the default user permissions used when |
| 291 | processing the `--set-user-caps` option for the `test-th-eval`, |
| 292 | `test-th-render`, and `test-th-source` test commands. |
| 293 | |
| 294 | `TMPDIR`: Names the temporary file location for SQLite. |
| 295 | |
| 296 | |
| 297 | `USER`: Name of the logged in user on many Unix-like platforms. |
| 298 | Used as the fossil user name if `FOSSIL_USER` is not specified. See |
| @@ -322,16 +300,10 @@ | |
| 300 | |
| 301 | `USERNAME`: Name of the logged in user on Windows platforms. |
| 302 | Used as the fossil user name if `FOSSIL_USER` is not specified. See |
| 303 | the discussion of Fossil Username below for a lot more detail. |
| 304 | |
| 305 | `VISUAL`: Name the editor to use for check-in and stash comments. |
| 306 | Overrides the `EDITOR` environment variable. Overridden by the local |
| 307 | or global `editor` setting. |
| 308 | |
| 309 | |
| @@ -462,30 +434,34 @@ | |
| 434 | precedence. |
| 435 | |
| 436 | |
| 437 | ### Temporary File Location |
| 438 | |
| 439 | Fossil places some temporary files in the checkout directory. Most notably, |
| 440 | supporting files related to merge conflicts are placed in the same |
| 441 | folder as the merge result. |
| 442 | |
| 443 | Other temporary files need a different home. The rules for choosing one are |
| 444 | complicated. |
| 445 | |
| 446 | Fossil-specific code uses `FOSSIL_TEMP`, `TEMP`, and `TMP`, in that |
| 447 | order. Fossil’s own test suite prepends `FOSSIL_TEST_TEMP` to that list. |
| 448 | |
| 449 | The underlying SQLite code uses several different path sets for its temp |
| 450 | files, depending on the platform type. |
| 451 | |
| 452 | On Unix-like platforms, excepting Cygwin, SQLite first checks the |
| 453 | environment variables `SQLITE_TMPDIR` and `TMPDIR`, in that order. If |
| 454 | neither is defined, it falls back to a hard-coded list of paths: |
| 455 | `/var/tmp`, `/usr/tmp`, and `/tmp`. If all of that fails, it uses the |
| 456 | current working directory. |
| 457 | |
| 458 | For Cygwin builds, SQLite instead uses the first defined variable in |
| 459 | this list: `SQLITE_TMPDIR`, `TMPDIR`, `TMP`, `TEMP`, and `USERPROFILE`. |
| 460 | |
| 461 | For native Windows builds, SQLite simply calls the OS’s [`GetTempPath()` |
| 462 | API][gtp]. See that reference page for details. |
| 463 | |
| 464 | [gtp]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992%28v=vs.85%29.aspx |
| 465 | |
| 466 | |
| 467 | |
| 468 |