I have a proposal for implementing a new environment variable, CLANG_CRASH_DIAGNOSTICS_DIR,
which controls the directory where crash reproducers will be stored. This is equivalent to passing the driver flag -fcrash-diagnostics-dir, and the flag still takes precedence.
The main motivation is to make the job of exporting those crash reproducers through pipeline artifacts much easier.
I think this is a reasonable idea, thank you for raising an RFC for it!
I’d love to see us introduce a similar page for Clang; environment variables that control the behavior of the compiler but are not documented are not going to get much use in practice but run a risk of really surprising users in the worst case.
I think this is the right category – it’s the general “I want to talk about clang” category as opposed to clang static analyzer, clang-tidy, etc. I don’t think we break it down into individual component categories.
Whether it overrides depends on how the environment variable is defined. My example used + to append the command line option to the end of the command line. Replacing that with ^ would prepend it such that a later option could override it.
Regardless, a separate environment variable for the crash directory seems reasonable.
Personally, I think it’s reasonable to add this new environment variable to get the documentation started, and then fill out the missing bits later. That’s how we’ve handled attribute documentation in the past, for example. It’s not ideal (someone still has to feel the desire to go write those docs), but it is still incremental progress towards where we want to be without putting an undue burden on the patch author. That said, if @mizvekov wants to write those docs up front, I’ll be delighted.
I am thinking clang/docs/UsersManual.rst. It seems to make sense in scope, but there is also a lot of work involved because a lot of the options that relate to the variables, and which it would make sense to document together, are not in there at all.
and all of these documents are likely to be split up/link back and forth to one another as appropriate. So I agree the docs for this environment variable should probably live in the User’s Manual (and some other parts of the user’s manual should probably be split out, like extensions to C and C++).