Document the default value of `target-cpu`

[FedericoStra]

What is the default value of target-cpu if no -C target-cpu= is passed to rustc? Is it native, generic, something else?

It should probably be documented around here:

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

Lines 572 to 580 in 1151ea6

	## target-cpu
	This instructs `rustc` to generate code specifically for a particular processor.
	You can run `rustc --print target-cpus` to see the valid options to pass
	here. Each target has a default base CPU. Special values include:
	* `native` can be passed to use the processor of the host machine.
	* `generic` refers to an LLVM target with minimal features but modern tuning.

[ehuss]

I believe it is documented there where it says "Each target has a default base CPU.". Every target has a different default target-cpu. I do not believe there is an option to explicitly use the default.

rustc --print target-cpus could perhaps indicate which one is the default. I don't think the rustc book is the appropriate place to document the specs for every target.

[mj10021]

The default rustc target is host and therefor the default target-cpu is native right? rustc --print target-cpus currently displays the host processor, e.g.

Available CPUs for this target:
    native         - Select the CPU of the current host (currently skylake).

[ehuss]

No, native is different from the default. For example, the default CPU for x86_64-unknown-linux-gnu is x86-64, which is compatible with the very first generation of x86-64 CPUs. The "native" CPU on my machine is znver1. The default is hard-coded into rustc for each target, typically picking the oldest CPU that is possible for that target.

[mj10021]

O, gotcha. Would it make more sense for --print target-cpus to display the default target cpu for the default target or for --print target list to show the default target cpu for each target? I guess showing the cpu for each target might be too much information, but I'm wondering how one could look up the cpu for any taget...

@rustbot claim

[ehuss]

It might be reasonable to add a note next to the default CPU in the target-cpus list in a fashion similar to the native entry. But I am not on the compiler team, so it is not my call. Maybe something like:

    cannonlake
    cascadelake
    cooperlake
    core-avx-i
    core-avx2
    core2         - Default for the x86_64-apple-darwin target
    corei7
    corei7-avx
    emeraldrapids

You can get the default cpu today on nightly by running rustc --print=target-spec-json.

[workingjubilee]

Addressed in #110876.