dmd
dmd copied to clipboard
dlang
document undocumented --[bcfrxy] switches
These switches are surprisingly useful in understanding how the dmd backend generates code. They used to be available only in debug builds of dmd, but they are so useful I put them in release builds, too.
Amazingly, nobody knows about them. Apparently I neglected to document them. Hence this PR.
Thanks for your pull request, @WalterBright!
Bugzilla references
Your PR doesn't reference any Bugzilla issue.
If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.
Testing this PR locally
If you don't have a local development environment setup, you can use Digger to test this PR:
dub run digger -- build "master + dmd#14356"
If it becomes a problem in the future, we can always change it. But currently they've been in dmd for many, many years, and the shortness contributes to their easy utility.
This isn't good, I had to check but LDC doesn't offer debugging of the backend as cli options (at least via --help).
Most people should never need to know that these switches exist (and hence they haven't).
They should not be mixed in together with the rest. It will only confuse people.
There is -vv which turns on the logging messages, which in combination with LLVM with assertions enabled will catch most LDC misuse of LLVM, though might no do much about LLVM bugs.
There is
-vvwhich turns on the logging messages, which in combination with LLVM with assertions enabled will catch most LDC misuse of LLVM, though might no do much about LLVM bugs.
I thought about mentioning -vv but it didn't seem like it was quite in the same category as having a register allocator tell you what it is doing.
Having used those switches constantly for 35 years, switching to long names like that would make them fairly unusable. It's be like changing vim's delete word dw command to delete word. Nor would I care for line wrap from the adding/subtracting them from the command line.
You are the only person using them though. Most people do not care for them, nor should they.
You are the only person using them though.
Being undocumented has that effect :-)
Most people do not care for them, nor should they.
That's right, and this is typical for -- switches. What prompted this, though, is some people have expressed interest in how the backend works, and these switches help a lot with that.
can they be printed only in a debug build?
That's the way it was for years, but given the increasingly diverse executable builds of dmd, that turned out to be a nuisance.
I'm concerned that someone will reach for these switches when they don't need to debug the backend and these old names don't signal that they shouldn't touch them. It could be a real problem for us who deal with newer people to D on a daily basis.
The alternatives I can think of that won't break your workflow would be to keep these undocumented but introduce new ones that are documented or introduce a heading with a warning about who these are for.
On Mon, Aug 8, 2022, 08:45 Walter Bright @.***> wrote:
You are the only person using them though.
Being undocumented has that effect :-)
Most people do not care for them, nor should they.
That's right, and this is typical for -- switches. What prompted this, though, is some people have expressed interest in how the backend works, and these switches help a lot with that.
can they be printed only in a debug build?
That's the way it was for years, but given the increasingly diverse executable builds of dmd, that turned out to be a nuisance.
— Reply to this email directly, view it on GitHub https://github.com/dlang/dmd/pull/14356#issuecomment-1207482562, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHSL46Q7YDW4SUZMJ3HOGTVYAN6XANCNFSM552IQEWA . You are receiving this because you commented.Message ID: @.***>
The -- prefix is a signal that they are for advanced users. Besides, the switches do not alter the behavior of the compiler in any way, they just provide information about what it is doing. I don't know how that could be a real problem - just tell them that's for compiler spelunking.
BTW, gcc has many options to dump out intermediate knowledge of how the compiler is doing.
We don't see many beginners using gdc it's usually dmd and occasionally ldc.
The people I'm concerned about are those who don't know what a linker is which is the majority. It is bad enough that doing a series of articles on the d blog about linkers has been a bit of a goal for Mike.
On Mon, Aug 8, 2022, 13:21 Walter Bright @.***> wrote:
BTW, gcc has many options to dump out intermediate knowledge of how the compiler is doing.
— Reply to this email directly, view it on GitHub https://github.com/dlang/dmd/pull/14356#issuecomment-1207546088, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHSL47RPMUJ4GNQR7AKEUDVYBOLBANCNFSM552IQEWA . You are receiving this because you commented.Message ID: @.***>
I meant gcc, which beginners do use, and the compiler internals have nothing to do with how linkers work.
****** FAIL release32 std.logger.core
core.exception.AssertError@std/logger/core.d(1900): unittest failure
Flaky std.logger.core strikes again. https://issues.dlang.org/show_bug.cgi?id=23286
These switches are surprisingly useful in understanding how the dmd backend generates code. They used to be available only in debug builds of dmd, but they are so useful I put them in release builds, too.
Amazingly, nobody knows about them. Apparently I neglected to document them. Hence this PR.
I did know about them.
They're documented on the wiki page for dmd development.
This isn't good, I had to check but LDC doesn't offer debugging of the backend as cli options (at least via --help).
Most people should never need to know that these switches exist (and hence they haven't).
They should not be mixed in together with the rest. It will only confuse people.
They're in -help-hidden
The
--prefix is a signal that they are for advanced users.
What makes you think that ? That's not the convention.
What makes you think that ?
When I use them for git, it usually means I'm doing something outside the normal things. Like --no-edit.
What makes you think that ?
When I use them for git, it usually means I'm doing something outside the normal things. Like
--no-edit.
That's actually not the intended meaning at all. Long options are documented in getopt_long and are simply a mean to provide more than 26 options. While it's more likely that a less used option will only get a long name, many commonly used options also have a long version, e.g. man git-commit first 4 documented opttons:
OPTIONS
-a, --all
Tell the command to automatically stage files that have been modified and deleted, but new files you have not told Git about are not affected.
-p, --patch
Use the interactive patch selection interface to choose which changes to commit. See git-add(1) for details.
-C <commit>, --reuse-message=<commit>
Take an existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit.
-c <commit>, --reedit-message=<commit>
Like -C, but with -c the editor is invoked, so that the user can further edit the commit message.
You can see that --patch, --all, etc... are not obscure at all.
It's also probably worth noting that git is not really a model for UI or UX
There is already -vcg-ast, what about using -vcg as prefix?
I suppose cg means code generation and these switches fall under that category.
-vcg- prefix
Because I use these switches all the time, adding and removing them, and it's annoying to have to type out long switches.
@Geod24 I agree that we should not give these switches such prominent names, however, they have existed since forever and nobody complained about them (probably because nobody knew they existed). As such, I don't see the harm in documenting them as is and then change them if any reasonable complaints appear. Staying in this stale mate does not help anyone, in my opinion.
I don't see the harm in documenting them as is
I disagree. Walter has stated that the best user experience is just dmd sourcefile.d, that compiler switches are 'bugs', hence dmd has way to many switches, and we need to say 'no' more often to new switches.
This PR essentially adds 6 switches, and because of the double dash prefix, they appear last alphabetically. Consequently, when a user types dmd --help or just dmd, the first things they see are the most niche compiler switches.
dmd | tail
-wi warnings as messages (compilation will continue)
-X generate JSON file
-Xf=<filename> write JSON file to filename
-Xcc=<driverflag> pass driverflag to linker driver (cc)
--b print backend IR using infix notation
--c print data flow optimizations performed, show generated code
--f use with -b to print backend IR using prefix binary tree notation
--r show the register allocator at work, see which variables go in which registers
--x show the common subexpression eliminator at work in non-optimized builds
--y track changes to the backend symbol table
I'd rather keep them undocumented than pollute the compiler's ever growing top-level help text.
The way forward as I see it, is to keep the undocumented --[bcfrxy] switches for Walter to use, and optionally expose them to users, but with better names and grouped together.
two things:
- This thing about the number switches isn't quite right. Switches that change behaviour should be minimised, aggressively (e.g. I think betterC being a flag rather than a target was a mistake, in hindsight) for obvious combinatorial reasons however these types of switches don't change behaviour and are exclusively for power users or the curious so I don't think the same reasoning applies.
Anecdotally fiddling around with these switches (or lack thereof in some builds of the compiler) is what led to me ever building the compiler if I recall correctly.
- A bloated help text is a real concern, however LLVM has probably 5k options tucked away in -help-hidden with not much harm to navigability or user experience i.e. we should have them but hide them. Transparency and documentation is good.
-help=debug (a la how gcc does it for specific language options) would be better for this.
On Mon, 5 Sept 2022, 11:38 Dennis, @.***> wrote:
I don't see the harm in documenting them as is
I disagree. Walter has stated that the best user experience is just dmd sourcefile.d, that compiler switches are 'bugs', hence dmd has way to many switches, and we need to say 'no' more often to new switches.
This PR essentially adds 6 switches, and because of the double dash prefix, they appear last alphabetically. Consequently, when a user types dmd --help or just dmd, the first things they see are the most niche compiler switches.
dmd | tail -wi warnings as messages (compilation will continue) -X generate JSON file -Xf=
write JSON file to filename -Xcc= pass driverflag to linker driver (cc) --b print backend IR using infix notation --c print data flow optimizations performed, show generated code --f use with -b to print backend IR using prefix binary tree notation --r show the register allocator at work, see which variables go in which registers --x show the common subexpression eliminator at work in non-optimized builds --y track changes to the backend symbol table I'd rather keep them undocumented than pollute the compiler's ever growing top-level help text.
The way forward as I see it, is to keep the undocumented --[bcfrxy] switches for Walter to use, and optionally expose them to users, but with better names and grouped together.
— Reply to this email directly, view it on GitHub https://github.com/dlang/dmd/pull/14356#issuecomment-1236769835, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABLI75ETAUXQWYMATHDRAPTV4W5SRANCNFSM552IQEWA . You are receiving this because you commented.Message ID: @.***>