Properly document and explain opt-levels s and z

[LukasKalbertodt]

These opt-levels have been stabilized in #50265. If I'm not mistaken, rustc -C help still outputs this:

    -C            opt-level=val -- optimize with possible levels 0-3, s, or z

So not very helpful at all. I think there should be a better explanation for rustc -C help (also for levels 0 -- 3). The rustc guide has some information, but it's rather hidden.

I'd also suggest to change the current one-line-per-option layout of -Z help and -C help. Currently it discourages people to add more useful information if they have to crank it into one line. Why not something like:

-C debuginfo=val 
    Debug info emission level, 0 = no debug info, 1 = line tables only, 2 = full debug  
    info with variable and type information. And more information here. Lorem ipsum 
    dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt 
    ut labore et dolore magna aliquyam erat, sed diam voluatua. At vero eos et accusam 
    et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata 
    sanctus est Lorem ipsum dolor sit amet.
    
-C opt-level=val 
    Optimize with possible levels 0-3, s, or z. And more information here. Lorem ipsum 
    dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt 
    ut labore et dolore magna aliquyam erat, sed diam voluatua. At vero eos et accusam 
    et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata 
    sanctus est Lorem ipsum dolor sit amet.

Or something like that.

[kennytm]

This would make -C help very long if all options are explained in detail like a manpage. I wouldn't mind if the long description is available through -C help -v or -C help=opt-level though.

[ehuss]

I wonder if there are any ideas on how to make the rustc book more visible.

I'm curious what information would be useful to know about the opt levels. If it told you that z changes loop rotation headers, would that be helpful? I suspect these are not really documented for a variety of reasons, in part because the set of optimizations is huge and changes in every release. There is a (somewhat old) thread on clang to clarify the levels, but I'm guessing it didn't go anywhere: http://lists.llvm.org/pipermail/cfe-dev/2013-January/027221.html.

Perhaps one thing that would be useful to add is that s and z are similar to -O2 with a few changes to reduce code size.

TLDR: What info would you like to see?

[LukasKalbertodt]

@ehuss My wishlist:

• If possible: what specific optimizations are enabled or disabled for what level? "z changes loop rotation headers" falls in this category and yes, that would be helpful IMO. Right now the "optimize for size" and "optimize for size even more" are not useful in that I cannot sensibly decide what to use. Having a crude list of what optimizations are enabled/disabled for each level would help make that decision. And well, maybe LLVM changes this stuff too often to keep up. But I guess some things don't change that often -- it would be nice to mention those.

• So Rust somehow calls LLVM, right? I guess via some C interface (or as an external executable? :/). In any way, my -C opt-level XXX leads to a specific invocation of LLVM. I'd like to know what exact invocation every Rust opt-level leads to. Preferably with links to some LLVM documentation.

• Are z and s alternatives to 0--3 or could they somehow both be specified? Sure, many optimizations have an influence on both, runtime and size. But it wouldn't be unreasonable to think that one could tweak both parameters independently, right? Example:

  • -Oz -O0: I don't care about how fast my program runs, but please make my binary very small
  • -Oz -O3: I want you to optimize runtime as much as you can while still keeping the binary size small.

[nagisa]

One of the appropriate places to put this information would be in the manual pages (rustc.1), which is currently so undermaintained that it doesn’t mention s and z at all :)

[alexchandel]

It would be nice to document and list the optimization passes for opt-level 1-3 as well. All we have currently is this:

## opt-level

This flag lets you control the optimization level.

* `0`: no optimizations
* `1`: basic optimizations
* `2`: some optimizations
* `3`: all optimizations
* `s`: optimize for binary size
* `z`: optimize for binary size, but also turn off loop vectorization.

In LLVM 3.8, -O1 added -globalopt -demanded-bits -branch-prob -inferattrs -ipsccp -dse -loop-simplify -scoped-noalias -barrier -adce -deadargelim -memdep -licm -globals-aa -rpo-functionattrs -basiccg -loop-idiom -forceattrs -mem2reg -simplifycfg -early-cse -instcombine -sccp -loop-unswitch -loop-vectorize -tailcallelim -functionattrs -loop-accesses -memcpyopt -loop-deletion -reassociate -strip-dead-prototypes -loops -basicaa -correlated-propagation -lcssa -domtree -always-inline -aa -block-freq -float2int -lower-expect -sroa -loop-unroll -alignment-from-assumptions -lazy-value-info -prune-eh -jump-threading -loop-rotate -indvars -bdce -scalar-evolution -tbaa -assumption-cache-tracker, -O2 added -elim-avail-extern -mldst-motion -slp-vectorizer -gvn -inline -globaldce -constmerge and dropped -always-inline, -O3 added -argpromotion, -Os was the same as -O2, and -Oz just dropped -slp-vectorizer, but LLVM has probably changed since 3.8, and I have no idea what rustc adds to that anyway.

Even if it wasn't exhaustive, src/doc/rustc/src/codegen-options/index.md ought to at least examples of what's added.