Reword and correct the preprocessor cache mode documentation #2362
Conversation
ahartmetz
force-pushed
the
improve_direct_mode_docs
branch
from
1fb6e20 to
fae1c11
Compare
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2362 +/- ##
==========================================
- Coverage 71.41% 71.41% -0.01%
==========================================
Files 65 65
Lines 36349 36349
==========================================
- Hits 25960 25959 -1
- Misses 10389 10390 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
ahartmetz
force-pushed
the
improve_direct_mode_docs
branch
2 times, most recently
from
0c44acb to
ba85488
Compare
|
Draft because: The second commit needs review from someone who understands preprocessor cache mode! I think this explanation is much clearer, but I don't know if it is actually true. The previous text mentioned "caching the preprocessor result", but that doesn't seem to make any sense. If the preprocessor result is the same, compilation can be trivially skipped as well (except if only the compiler ID changed, seems to be a bit of a long shot). So I think what is actually happening is skipping from input files to output files directly if there is a cached result, not skipping anything if there is a cache miss. |
docs/Local.md
Outdated
|
|
||
| [preprocessor cache] mode is controlled by a configuration option which is true by default, as well as additional conditions described below. | ||
|
|
||
| In preprocessor cache mode, sccache caches the preprocessor step for C/C++ whenever possible. This can make the compilation much faster, since the preprocessor step takes a non-negligible amount of the entire compile time. | ||
| In non-preprocessor cache mode, sccache's compilation pipeline for one C/C++ source file is inputs → preprocessing → cache lookup → (return outputs if cached / compilation otherwise). In preprocessor cache mode, the compilation pipeline is inputs → cache lookup → (return outputs if cached / preprocessing → compilation otherwise). This can make it much faster to return compilation outputs from cache. |
There was a problem hiding this comment.
This line would need some wrapping, as well as using backticks for the processing pipeline description if not a a triple-back-tick code block I find it hard to read inline as it is, harming the intent of the PR. It also requires a precise definition of "outputs" - is that the pre-processor generated C/C++ code or the compiled object file?
docs/Local.md
Outdated
|
|
||
| In order to cache the preprocessor step, [sccache] needs to remember, among other things, all files included by a given input file. To quote ccache's documentation: | ||
| To ensure that the cached outputs for a source file correspond to the un-preprocessed inputs, [sccache] needs to remember, among other things, all files included by that source file (i.e. the complete set of inputs). To quote ccache's documentation: |
There was a problem hiding this comment.
I'd be explicit about the issue with __TIME__ and __DATE__ macros and the config flag that allows one to handle the trade-off.
|
If you take a look into the code (older ref) Line 335 in cbe79c9 Box<dyn Compilation> type utilizing the preprocessor output as input for the C compiler.
|
The correction is that there is a *long* list of compiler options that disable preprocessor cache mode.
Most importantly, group similar things together. Also improve some of the wording and (TODO) Also TODO: "provisional fix for [nothing]"
ahartmetz
force-pushed
the
improve_direct_mode_docs
branch
from
f8f6125 to
56dbedb
Compare
The correction is that there is a long list of compiler options that disable preprocessor cache mode.