Allow to use parallel codegen through `build` command

[vhbit]

It's very unfortunate that while parallel codegen landed, it's still impossible to use it directly from cargo build

[alexcrichton]

This is actually possible with the profiles.*.codegen-units key in Cargo.toml (you can set it to something other than 1), but it's not documented that well, so I'm going to classify this as a documentation bug.

[vhbit]

Wonderful! Thanks!

[JustAPerson]

When not specified, cargo lets rustc decide, and rustc will default to 1. How should this be reflected in the docs?

# The development profile, used for `cargo build`
[profile.dev]
opt-level = 0  # Controls the --opt-level the compiler builds with
debug = true   # Controls whether the compiler passes `-g`
rpath = false  # Controls whether the compiler passes `-C rpath`
lto = false    # Controls `-C lto` for binaries and staticlibs
debug-assertions = true  # Controls whether debug assertions are enabled
codegen-units = 1 # Controls whether the compiler passes `-C codegen-units`

The above is slightly incorrect because the actual default is None, which in effect defaults to 1.

[alexcrichton]

Ah it's fine to just have some placeholder like ... and explain the default in a comment

[huonw]

This is actually possible with the profiles.*.codegen-units key in Cargo.toml (you can set it to something other than 1), but it's not documented that well, so I'm going to classify this as a documentation bug.

Hm, it's extremely non-obvious to me why this makes sense in a per-project Cargo.toml: it seems to me that usually people will want codegen-units = num_cpus() for dev builds and = 1 for others (i.e. global constants specific to a single machine, not to a published project), and most other values would also be set globally on a machine e.g. maybe someone using a 32-core machine wants to "rate limit" rustc to only 4 cores.

[alexcrichton]

@huonw hm that's true, I initially thought that it was closely related to the optimization level of a crate (which seems appropriate in a profile), but it may be more of a .cargo/config option instead of a Cargo.toml option.

That being said, I think that most crates won't bother with this key and will instead on the compiler choosing a nice set of defaults.