Skip to content

Commit

Permalink
Stabilize profile-overrides.
Browse files Browse the repository at this point in the history
  • Loading branch information
ehuss committed Nov 16, 2019
1 parent e55600b commit dda81d3
Show file tree
Hide file tree
Showing 29 changed files with 430 additions and 281 deletions.
2 changes: 1 addition & 1 deletion src/cargo/core/features.rs
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ features! {
[unstable] publish_lockfile: bool,

// Overriding profiles for dependencies.
[unstable] profile_overrides: bool,
[stable] profile_overrides: bool,

// Separating the namespaces for features and dependencies
[unstable] namespaced_features: bool,
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/cargo-bench.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ include::options-jobs.adoc[]

Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
linkcargo:reference/manifest.html#the-profile-sections[the reference]
linkcargo:reference/profiles.html[the reference]
for more details.

Benchmarks are always built with the `bench` profile. Binary and lib targets
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-bench.html
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,7 @@ <h2 id="cargo_bench_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-build.html
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,7 @@ <h2 id="cargo_build_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-check.html
Original file line number Diff line number Diff line change
Expand Up @@ -363,7 +363,7 @@ <h2 id="cargo_check_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-doc.html
Original file line number Diff line number Diff line change
Expand Up @@ -333,7 +333,7 @@ <h2 id="cargo_doc_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-fix.html
Original file line number Diff line number Diff line change
Expand Up @@ -434,7 +434,7 @@ <h2 id="cargo_fix_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-run.html
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@ <h2 id="cargo_run_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-rustc.html
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ <h2 id="cargo_rustc_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-rustdoc.html
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,7 @@ <h2 id="cargo_rustdoc_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/generated/cargo-test.html
Original file line number Diff line number Diff line change
Expand Up @@ -462,7 +462,7 @@ <h2 id="cargo_test_profiles">PROFILES</h2>
<div class="paragraph">
<p>Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
<a href="../reference/profiles.html">the reference</a>
for more details.</p>
</div>
<div class="paragraph">
Expand Down
2 changes: 1 addition & 1 deletion src/doc/man/section-profiles.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
linkcargo:reference/manifest.html#the-profile-sections[the reference]
linkcargo:reference/profiles.html[the reference]
for more details.

Profile selection depends on the target and crate being built. By default the
Expand Down
1 change: 1 addition & 0 deletions src/doc/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
* [Cargo Reference](reference/index.md)
* [Specifying Dependencies](reference/specifying-dependencies.md)
* [The Manifest Format](reference/manifest.md)
* [Profiles](reference/profiles.md)
* [Configuration](reference/config.md)
* [Environment Variables](reference/environment-variables.md)
* [Build Scripts](reference/build-scripts.md)
Expand Down
4 changes: 2 additions & 2 deletions src/doc/src/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,9 @@ packages using Cargo.

### Does Cargo support environments, like `production` or `test`?

We support environments through the use of [profiles][profile] to support:
We support environments through the use of [profiles] to support:

[profile]: reference/manifest.md#the-profile-sections
[profiles]: reference/profiles.md

* environment-specific flags (like `-g --opt-level=0` for development
and `--opt-level=3` for production).
Expand Down
80 changes: 3 additions & 77 deletions src/doc/src/reference/manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -391,83 +391,9 @@ information on the `[dependencies]`, `[dev-dependencies]`,

### The `[profile.*]` sections

Cargo supports custom configuration of how rustc is invoked through profiles at
the top level. Any manifest may declare a profile, but only the top level
package’s profiles are actually read. All dependencies’ profiles will be
overridden. This is done so the top-level package has control over how its
dependencies are compiled.

There are four currently supported profile names, all of which have the same
configuration available to them. Listed below is the configuration available,
along with the defaults for each profile.

```toml
# The development profile, used for `cargo build`.
[profile.dev]
opt-level = 0 # controls the `--opt-level` the compiler builds with.
# 0-1 is good for debugging. 2 is well-optimized. Max is 3.
# 's' attempts to reduce size, 'z' reduces size even more.
debug = true # (u32 or bool) Include debug information (debug symbols).
# Equivalent to `-C debuginfo=2` compiler flag.
rpath = false # controls whether compiler should set loader paths.
# If true, passes `-C rpath` flag to the compiler.
lto = false # Link Time Optimization usually reduces size of binaries
# and static libraries. Increases compilation time.
# If true, passes `-C lto` flag to the compiler, and if a
# string is specified like 'thin' then `-C lto=thin` will
# be passed.
debug-assertions = true # controls whether debug assertions are enabled
# (e.g., debug_assert!() and arithmetic overflow checks)
codegen-units = 16 # if > 1 enables parallel code generation which improves
# compile times, but prevents some optimizations.
# Passes `-C codegen-units`.
panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort'
incremental = true # whether or not incremental compilation is enabled
# This can be overridden globally with the CARGO_INCREMENTAL
# environment variable or `build.incremental` config
# variable. Incremental is only used for path sources.
overflow-checks = true # use overflow checks for integer arithmetic.
# Passes the `-C overflow-checks=...` flag to the compiler.

# The release profile, used for `cargo build --release` (and the dependencies
# for `cargo test --release`, including the local library or binary).
[profile.release]
opt-level = 3
debug = false
rpath = false
lto = false
debug-assertions = false
codegen-units = 16
panic = 'unwind'
incremental = false
overflow-checks = false

# The testing profile, used for `cargo test` (for `cargo test --release` see
# the `release` and `bench` profiles).
[profile.test]
opt-level = 0
debug = 2
rpath = false
lto = false
debug-assertions = true
codegen-units = 16
panic = 'unwind'
incremental = true
overflow-checks = true

# The benchmarking profile, used for `cargo bench` (and the test targets and
# unit tests for `cargo test --release`).
[profile.bench]
opt-level = 3
debug = false
rpath = false
lto = false
debug-assertions = false
codegen-units = 16
panic = 'unwind'
incremental = false
overflow-checks = false
```
The `[profile]` tables provide a way to customize compiler settings such as
optimizations and debug settings. See [the Profiles chapter](profiles.md) for
more detail.

### The `[features]` section

Expand Down
Loading

0 comments on commit dda81d3

Please sign in to comment.