RFC: New environment variable for controlling crash-diagnostics-dir

Hello everyone,

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 have an implementation at: ⚙ D133082 [clang] Implement setting crash_diagnostics_dir through env variable
And it includes the integration with the libcxx CI.

An environment variable seems like the least intrusive way to accomplish this, and no workarounds are needed, even for -fcrash-diagnostics-dir driver tests.

We do have a lot of environment variable usage in clang, but we lack documentation for them, and most aren’t a fallback to an existing flag, so this might be a bit novel.

We lack a Clang equivalent of this GCC documentation: Environment Variables (Using the GNU Compiler Collection (GCC))
So we need to think how best to document this, if we take this approach.

I would really appreciate feedback and other ideas here!

Thanks everyone.

PS: Sorry if this seems the wrong category, as the crash reproducer machinery is part of the Driver, not the Frontend, but no such category exists.

1 Like

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.

1 Like

I think you can use the existing CCC_OVERRIDE_OPTIONS environment variable to accomplish this. Try this:

$ mkdir crash
$ touch t.c
$ CCC_OVERRIDE_OPTIONS="+-fcrash-diagnostics-dir=`pwd`/crash" \
  clang -c t.c

I think you can use the existing CCC_OVERRIDE_OPTIONS environment variable to accomplish this.

Yep, I was going to mention that, and that is my general response to any proposal to add a new environment variable to the compiler.

However, the separate environment variable is easier to use, and I think it’s probably worth having it be its own variable, so I think it’s worth doing.

1 Like

Thanks for pointing that out and giving an example of why we need that documentation :slight_smile:

From my own tests it seems that this variable overrides what is in the command line, ie it takes precedence over the flag passed via argv.

I think this has the downside that it could break tests.

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.


I’d also vote for a separate environment variable which is both easier to use and more composable.

I would prefer to first document the consumed environment variables before adding the next one.

TIL, thanks for sharing that tip!

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. :slight_smile:

I took a badly aimed stab at this documentation here: ⚙ D133209 [clang] Document environment variables used by the driver

Now, where should that documentation go instead?

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.

To me, there’s (at least) three kinds of implementation-defined documentation:

  • How to use the compiler (command line reference, environment variables that control the compiler, how the compiler sets up the include search paths, etc)
  • Language extensions where we’ve extended C or C++ in some way (blocks, vendor attributes, GNU statement expressions, etc).
  • Standards-required documentation of implementation-defined behavior (implementation limits, integer widths, extended alignments, etc).

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++).