Update codegen option documentation. #65136

ehuss · 2019-10-05T17:00:45Z

Some documentation updates:

Add more detail to codegen options.
Add missing options:
- force-frame-pointers
- default-linker-libraries
- linker-plugin-lto
Add fragment anchors for all command-line-arguments.
Add some cross links between options.

rust-highfive · 2019-10-05T17:00:56Z

r? @GuillaumeGomez

(rust_highfive has picked a reviewer for you, use r? to override)

JohnCSimon · 2019-10-12T05:19:09Z

Ping from triage
@GuillaumeGomez can you please review this?
Thanks

bors · 2019-10-18T14:03:37Z

☔ The latest upstream changes (presumably #64925) made this pull request unmergeable. Please resolve the merge conflicts.

Dylan-DPC-zz · 2019-10-22T12:35:58Z

r? @Dylan-DPC

bors · 2019-10-23T13:35:32Z

☔ The latest upstream changes (presumably #65716) made this pull request unmergeable. Please resolve the merge conflicts.

JohnCSimon · 2019-10-26T03:26:50Z

Hello from triage
@Dylan-DPC can you please review this PR?
cc: @ehuss ehuss
Thanks

kinnison

@Dylan-DPC I've left my comments in-line.

src/doc/rustc/src/codegen-options/index.md

kinnison · 2019-10-26T08:58:48Z

src/doc/rustc/src/codegen-options/index.md


-The default is 225.
+The default depends on the [opt-level](#opt-level). Current values are between
+25 to 275.


Given this, should we indicate the scores on the optimisation level table above, or is this too subject to change?

I'm often reluctant to go into details on how optimizations work. The correct settings usually require experimentation, and heavily depend on the project. They also are very LLVM specific, and are complex. However, I can see how this is annoyingly vague. I added a table, it can be updated or removed in the future if it ever changes.

Sounds good, this can be resolved then.

Co-Authored-By: Daniel Silverstone <dsilvers@digital-scurf.org>

ehuss

Thanks so much for taking a look!

ehuss · 2019-10-26T16:09:25Z

src/doc/rustc/src/codegen-options/index.md


-The default is 225.
+The default depends on the [opt-level](#opt-level). Current values are between
+25 to 275.


I'm often reluctant to go into details on how optimizations work. The correct settings usually require experimentation, and heavily depend on the project. They also are very LLVM specific, and are complex. However, I can see how this is annoyingly vague. I added a table, it can be updated or removed in the future if it ever changes.

kinnison

IMO this looks good.

JohnCSimon · 2019-11-02T03:33:55Z

Ping from triage -
@Dylan-DPC Seems @ehuss has addressed the issues
That can you please review this PR?

Thanks

Dylan-DPC-zz · 2019-11-02T11:39:01Z

@bors r+ rollup

bors · 2019-11-02T11:39:02Z

📌 Commit c6bfe28 has been approved by Dylan-DPC

tesuji · 2019-11-02T14:49:05Z

src/doc/rustc/src/codegen-options/index.md

+units](#codegen-units). In this case, LTO is disabled if codegen units is 1 or
+optimizations are disabled ([`-C opt-level=0`](#opt-level)).


Is this true?
I tried to set exclusive lto and codegen-units option and the binary size is
increased than when I set both lto=true and codegen-units=1.

By "exclusive LTO", do you mean not including the flag? Can you clarify which commands you ran?

I would expect it to be larger, since lto=true is "fat", and without the flag it is only "thin local", which does less optimization.

Here is the logic this is referring to.

By "exclusive" I mean I either set lto or codegen-units.

Also, I set these options in Cargo.toml, not via rustc arguments

I'm still not sure I understand the confusion here. lto=true + codegen-units=1 should be the smallest. It does fat LTO, and with 1 CGU per crate, so it has more optimization potential (but is very slow to compile). That is:

codegen-units=1: Disables LTO, so won't have cross-crate optimizations.

lto=true: 16 cgus, performs fat LTO across crates.

codegen-units=1 + lto=true: 1 cgu, fat LTO across crates.

IMO adding that to the documentation seems really helpful.

Sure, I'll try to make it a little clearer.

ehuss · 2019-11-02T16:21:23Z

@bors r-

ehuss · 2019-11-02T16:48:00Z

@lzutao @Dylan-DPC can you take a look at the last commit and see if it helps? Not sure if that really clarifies it not.

tesuji · 2019-11-03T03:59:18Z

src/doc/rustc/src/codegen-options/index.md

+If `-C lto` is not specified, then the compiler will attempt to perform "thin
+local LTO" which performs "thin" LTO on the local crate only across its
+[codegen units](#codegen-units). When `-C lto` is not specified, LTO is
+disabled if codegen units is 1 or optimizations are disabled ([`-C
+opt-level=0`](#opt-level)). That is:


How about this?

[codegen-units] and [opt-level] also affects on how compiler perform LTO: * When `-C lto` is not specified: - `codegen-units=1`: Disables LTO. - `opt-level=0`: Disables LTO. * When `-C lto=true`: - `codegen-units=1`: perform fat LTO across crates with 1 codegen unit. Some people prefers to do it in cargo release profile.

Thanks, updated.

Thanks. That's clearer.

Dylan-DPC-zz · 2019-11-03T14:17:00Z

@lzutao ping me when you think this is ready to be merged

tesuji · 2019-11-03T15:00:38Z

@Dylan-DPC My pleasure. I think this PR is ready to merge.

Dylan-DPC-zz · 2019-11-04T18:50:59Z

@bors: r+ rollup

bors · 2019-11-04T18:51:01Z

📌 Commit 9b9d651 has been approved by Dylan-DPC

…an-DPC Update codegen option documentation. Some documentation updates: - Add more detail to codegen options. - Add missing options: - `force-frame-pointers` - `default-linker-libraries` - `linker-plugin-lto` - Add fragment anchors for all command-line-arguments. - Add some cross links between options.

@ghost

Rollup of 10 pull requests Successful merges: - #65136 (Update codegen option documentation.) - #65574 (docs: improve disclaimer regarding LinkedList) - #65720 (Add FFI bindings for LLVM's Module::getInstructionCount()) - #65905 ([doc] fixes for unix/vxworks `OpenOptionsExt::mode`) - #65962 (Fix logic in example.) - #66019 (Improved std::iter::Chain documentation) - #66038 (doc(str): show example of chars().count() under len()) - #66042 (Suggest correct code when encountering an incorrect trait bound referencing the current trait) - #66073 (Do not needlessly write-lock) - #66096 (Add a failing UI test for multiple loops of all kinds in a `const`) Failed merges: r? @ghost

rust-highfive assigned GuillaumeGomez Oct 5, 2019

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 5, 2019

ehuss mentioned this pull request Oct 7, 2019

Should lto = false be treated as LTO "off"? rust-lang/cargo#7491

Open

ehuss force-pushed the update-codegen-options branch from 5544008 to e0559aa Compare October 18, 2019 17:45

rust-highfive assigned Dylan-DPC-zz and unassigned GuillaumeGomez Oct 22, 2019

ehuss force-pushed the update-codegen-options branch from e0559aa to 4b04440 Compare October 23, 2019 14:16

kinnison reviewed Oct 26, 2019

View reviewed changes

ehuss and others added 3 commits October 26, 2019 09:06

Update codegen option documentation.

f3e8c2e

Apply suggestions from kinnison

bd70c03

Co-Authored-By: Daniel Silverstone <dsilvers@digital-scurf.org>

Be more specific with -C inline-threshold.

c6bfe28

ehuss force-pushed the update-codegen-options branch from e5dbff4 to c6bfe28 Compare October 26, 2019 16:06

ehuss commented Oct 26, 2019

View reviewed changes

kinnison approved these changes Oct 26, 2019

View reviewed changes

Dylan-DPC-zz approved these changes Nov 2, 2019

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 2, 2019

tesuji reviewed Nov 2, 2019

View reviewed changes

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Nov 2, 2019

ehuss mentioned this pull request Nov 2, 2019

codegen-units=1 not honored #65996

Closed

tesuji reviewed Nov 3, 2019

View reviewed changes

Attempt to clarify LTO and codegen-units.

9b9d651

ehuss force-pushed the update-codegen-options branch from 3538ffb to 9b9d651 Compare November 3, 2019 14:01

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Nov 4, 2019

pietroalbini mentioned this pull request Nov 5, 2019

Rollup of 10 pull requests #66109

Merged

bors merged commit 9b9d651 into rust-lang:master Nov 5, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update codegen option documentation. #65136

Update codegen option documentation. #65136

ehuss commented Oct 5, 2019

rust-highfive commented Oct 5, 2019

JohnCSimon commented Oct 12, 2019

bors commented Oct 18, 2019

Dylan-DPC-zz commented Oct 22, 2019

bors commented Oct 23, 2019

JohnCSimon commented Oct 26, 2019

kinnison left a comment

kinnison Oct 26, 2019

ehuss Oct 26, 2019

kinnison Oct 26, 2019

ehuss left a comment

ehuss Oct 26, 2019

kinnison left a comment

JohnCSimon commented Nov 2, 2019

Dylan-DPC-zz commented Nov 2, 2019

bors commented Nov 2, 2019

tesuji Nov 2, 2019

ehuss Nov 2, 2019

tesuji Nov 2, 2019

tesuji Nov 2, 2019

ehuss Nov 2, 2019

tesuji Nov 2, 2019

ehuss Nov 2, 2019

ehuss commented Nov 2, 2019

ehuss commented Nov 2, 2019

tesuji Nov 3, 2019 •

edited

Loading

ehuss Nov 3, 2019

tesuji Nov 3, 2019

Dylan-DPC-zz commented Nov 3, 2019

tesuji commented Nov 3, 2019

Dylan-DPC-zz commented Nov 4, 2019

bors commented Nov 4, 2019

		units](#codegen-units). In this case, LTO is disabled if codegen units is 1 or
		optimizations are disabled ([`-C opt-level=0`](#opt-level)).

Update codegen option documentation. #65136

Update codegen option documentation. #65136

Conversation

ehuss commented Oct 5, 2019

rust-highfive commented Oct 5, 2019

JohnCSimon commented Oct 12, 2019

bors commented Oct 18, 2019

Dylan-DPC-zz commented Oct 22, 2019

bors commented Oct 23, 2019

JohnCSimon commented Oct 26, 2019

kinnison left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kinnison left a comment

Choose a reason for hiding this comment

JohnCSimon commented Nov 2, 2019

Dylan-DPC-zz commented Nov 2, 2019

bors commented Nov 2, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss commented Nov 2, 2019

ehuss commented Nov 2, 2019

tesuji Nov 3, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dylan-DPC-zz commented Nov 3, 2019

tesuji commented Nov 3, 2019

Dylan-DPC-zz commented Nov 4, 2019

bors commented Nov 4, 2019

tesuji Nov 3, 2019 •

edited

Loading