doc: make environment variable setting more explicit.

[rzhb]

$env:RUSTFMT_LOG=rustfmt=DEBUG didn't work in PowerShell, $env:RUSTFMT_LOG="rustfmt=DEBUG" worked.

[ytmimi]

@rzhb Thanks for reaching out. Can you confirm what version of rustfmt you're using? If you're using rustfmt 1.6.0 we had an issue when migrating to tracing for logging (#5800), but that was resolved in source already (#5818)

@calebcartwright do you think we can do a subtree-sync soon to resolve this?

[rzhb]

@ytmimi Maybe we have some misunderstand. This is not about rustfmt, just about environment variable setting in PowerShell and Windows.
In Linux, export RUSTFMT_LOG=rustfmt=DEBUG is same with export RUSTFMT_LOG="rustfmt=DEBUG".

But in Windows and PowerShell, $env:RUSTFMT_LOG=rustfmt=DEBUG gives error rustfmt=DEBUG: The term 'rustfmt=DEBUG' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
I am using rustfmt 1.6.0-nightly (cb80ff13 2023-07-07)

[ytmimi]

@rzhb Yeah, I think there was some misunderstanding. I think I just had the logging issue top of mind so I assumed you had run into an issue. As mentioned above, logging is broken in rustfmt 1.6.0 so I wouldn't expect you to see any log output even when setting the env variable correctly. You might want to test logging on a previous version of rustfmt.

[ytmimi]

Right now I'm wondering if it would be better to mention RUSTFMT_LOG=rustfmt=DEBUG on linux and add a new sentence to make a distinction for RUSTFMT_LOG="rustfmt=DEBUG" when using powershell on windows.

[rzhb]

The value is a String, it needs the quote. "RUSTFMT_LOG=rustfmt=DEBUG" is just lazy and not formal.

[ytmimi]

@rzhb first I want to highlight that I appreciate you helping to improve the docs, but I don't find the criticism to be constructive.

I wouldn't characterize this as lazy since the quotes are unnecessary when working on linux / mac. Given that the current docs are valid for some systems, I suggest making an amendment to the docs that informs powershell users that they need to wrap rustfmt=DEBUG in quotes. Are the quotes also necessary when running in the windows command prompt?

[rzhb]

On Linux, without quotes works only because there has no whitespace or special characters.
It's better to always quote string for safety.

powershell
$env:RUSTFMT_LOG="rustfmt=DEBUG" work.
$RUSTFMT_LOG="rustfmt=DEBUG" didn't.

cmd
set RUSTFMT_LOG="rustfmt=DEBUG" didn't work. rustfmt has warning warning: invalid logging spec 'DEBUG"', ignoring it
set RUSTFMT_LOG=rustfmt=DEBUG work.

[ytmimi]

Thank you for looking into this. From my understanding of your last comment the quotes are only required in powershell, and it seems like the quotes actually break things on cmd. Assuming that's the case I now feel more strongly about leaving the existing language as is and adding a note for powershell users.

[calebcartwright]

Thanks for the PR! I am fully in agreement with Yacin though, and don't want to move forward with the changes as proposed.

That being said, I'd also agree there's opportunities to improve things. First and foremost, the debug logging should be able to be enabled via the more simple RUSTFMT_LOG=debug.

The advanced filtering options are powerful, and certainly useful in more complex scenarios like the rustc codebase where you basically never want to build/test/troubleshoot with debugging enabled across the entire compiler, but instead want to only enable it for a subset, like a module.

I'd be completely open to simplifying the text to reflect this, which fwiw could obviate the topic of quotes. Then if necessary, we can mention the filtering feature, with or without examples

I went ahead and changed the docs to read RUSTFMT_LOG=debug as Caleb suggested