Incorrect description of environment variables in rustc man pages

[mulkieran]

Here it is:

ENVIRONMENT
       Some of these affect the output of the compiler,  while  others  affect
       programs which link to the standard library.

       RUST_TEST_THREADS
              The  test  framework  Rust  provides executes tests in parallel.
              This variable sets the maximum number of threads used  for  this
              purpose.  This  setting  is  overridden  by  the  --test-threads
              option.

       RUST_TEST_NOCAPTURE
              If set to a value other than "0", a synonym for the  --nocapture
              flag.

       RUST_MIN_STACK
              Sets the minimum stack size for new threads.

       RUST_BACKTRACE
              If  set  to  a value different than "0", produces a backtrace in
              the output of a program which panics.

I believe that the line here is incorrect

"Some of these affect the output of the compiler, while others affect
programs which link to the standard library."

since I believe none of these variables affect the output of the compiler.

Why is this a problem? Well, the logical reader might say to themselves:
" "Some" means at least 1. It makes very little sense for the top three to affect the output of the compiler. Therefore it must be the bottom one, RUST_BACKTRACE, which affects the output of the compiler."

[jonas-schievink]

I think "the output" should just be removed here - RUST_BACKTRACE applies to both rustc and binaries produced by it, for example.

[pnkfelix]

First, I do agree the phrase "the output of the compiler" is suboptimal, since it can be taken to mean the diagnostics emitted to stdout or other files it generates, while the original intent here (I think) is for the word "output" to denote the behavior of the binary generated by the compiler.

Second, while saying "Some of these affect the compiler, ..." would be technically correct, I think it would be misleading.

In particular, I personally would read the phase "RUST_BACKTRACE affects the compiler", at least initially, as meaning that the environment variable only matters during execution of the compiler itself, which is the opposite of what we want to convey.

How about:

Some of these affect only test harness programs (generated via rustc --test); others affect
all programs which link to the Rust standard library.
Note that rustc itself is an example of a program linked to the Rust standard library.

(I'm actually not particularly wedded to that second sentence. I would not mind if it were omitted.)

[mulkieran]

Thanks, @pnkfelix. Now that you point it out I realize that the problem with the problematic statement is not that it is wrong, so much as that it is entirely ambiguous and that when reading it it is easy to choose the wrong, that is unintended, meaning.

Your suggested wording works for me.

[DevQps]

First, I do agree the phrase "the output of the compiler" is suboptimal, since it can be taken to mean the diagnostics emitted to stdout or other files it generates, while the original intent here (I think) is for the word "output" to denote the behavior of the binary generated by the compiler.

Second, while saying "Some of these affect the compiler, ..." would be technically correct, I think it would be misleading.

In particular, I personally would read the phase "RUST_BACKTRACE affects the compiler", at least initially, as meaning that the environment variable only matters during execution of the compiler itself, which is the opposite of what we want to convey.

How about:

Some of these affect only test harness programs (generated via rustc --test); others affect
all programs which link to the Rust standard library.
Note that rustc itself is an example of a program linked to the Rust standard library.

(I'm actually not particularly wedded to that second sentence. I would not mind if it were omitted.)

I think the extra note on the end is likely to make things more confusing. So keeping it to only the first part of your suggestion is the best I think!:

Some of these affect only test harness programs (generated via rustc --test); others affect
all programs which link to the Rust standard library.

If you want I could create a PR for this?

[mulkieran]

@DevQps I'ld be fine w/ that wording as well.

[DevQps]

@mulkieran I created a PR for you here!