Skip to content

docs(guide): Clarify where to set config #16107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 15, 2025
+9 −1
Merged

docs(guide): Clarify where to set config #16107

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion src/doc/src/guide/build-performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,15 @@ Example workflows to consider include:

Cargo uses configuration defaults that try to balance several aspects, including debuggability, runtime performance, build performance, binary size and others. This section describes several approaches for changing these defaults that should be designed to maximize build performance.

You can set the described options either in the [`Cargo.toml` manifest](../reference/profiles.md), which will make them available for all developers who work on the given crate/project, or in the [`config.toml` configuration file](../reference/config.md), where you can apply them only for you or even globally for all your local projects.
Common locations to override defaults are:
- [`Cargo.toml` manifest](../reference/profiles.md)
- Available to all developers contributing to your project
- Limited in what configuration is supported (see [#12738](https://github.com/rust-lang/cargo/issues/12738) for expanding this)
- [`$WORKSPACE_ROOT/.cargo/config.toml` configuration file](../reference/config.md)
- Available to all developers contributing to your project
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd maybe add something like "(if checked into version control)", as it's less common for config.toml to be committed than Cargo.toml which is pretty much always under version control.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I worry that this would become too much of a distraction to mention

  1. We are not trying to cover every use case here (e.g. I left off having a config above the repo root for the next item)
  2. cargo new does not ignore it by default
  3. I regularly see it committed in repos
  4. If someone contributes to random projects, they can't build a workflow around not committing it because repos do commit it

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If someone contributes to random projects, they can't build a workflow around not committing it because repos do commit it

Yeah, that annoys me quite a lot, as I then have to keep a git-modified file on disk and ignore it in commits :)

Fair enough.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or keep your config in the parent directory, requiring extra nesting if its project specific.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or we have -Zconfig-include and project can explicitly set up a location that is git-ignored but optionally included.

- Unlike `Cargo.toml`, this is sensitive to what directory you invoke `cargo` from (see [#2930](https://github.com/rust-lang/cargo/issues/2930))
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why linked to an issue not the official doc?

If the official doc is not clear enough maybe we should update then.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The relevant text us buried such that linking to it will make people think we're linking for other reasons and it doesn't get into much of the surrounding context of that issue's discussion.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. That makes sense.

- [`$CARGO_HOME/.cargo/config.toml` configuration file](../reference/config.md)
- For a developer to control the defaults for their development

### Reduce amount of generated debug information

Expand Down