Introduce -Zsplit-metadata option by bjorn3 · Pull Request #120855 · rust-lang/rust

bjorn3 · 2024-02-09T18:48:03Z

This will split the crate metadata out of library files. Instead only the svh and a bit of extra metadata is preserved to allow for loading the right rmeta file. This significantly reduces library size. In addition it allows for cheaper checks if different library files are the same crate.

A fair amount of the complexity in this PR is to work around the fact that cargo doesn't directly support this option yet.

Fixes #23366
Closes #29511
Fixes #57076

Revives #93945

rustbot · 2024-02-09T18:48:11Z

r? @cjgillot

rustbot has assigned @cjgillot.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

bjorn3 · 2024-02-09T18:49:19Z

                } else if loc.file_name().unwrap().to_str().unwrap().ends_with(".rmeta") {
                    rmetas.insert(loc_canon, PathKind::ExternFlag);
                } else {
+                    rmetas.insert(loc_canon.with_extension("rmeta"), PathKind::ExternFlag);


This is a hack. It should probably be replaced with proper lookup in the library search path, or with cargo passing --extern twice for both the rlib/dylib and the rmeta file.

bjorn3 · 2024-02-09T18:51:31Z

+            if extension == "so" || extension == "dylib" {
+                // FIXME workaround for the fact that cargo doesn't understand `-Zsplit-metadata`
+                toplevel.push((file_stem.clone(), "rmeta".to_owned(), None));
+            }


This together with the rustc wrapper passing --emit metadata is a big hack working around the fact that cargo doesn't support -Zsplit-metadata and as such doesn't cause a .rmeta file to be emitted and also doesn't track it in the compiler-artifact json message. This also causes issues with recompilations as the loop below may copy outdated rmeta files into the sysroot, which would then result in compiler errors.

bjorn3 · 2024-02-09T18:52:18Z

@@ -1,4 +1,4 @@
-// normalize-stderr-test "loaded from .*libstd-.*.rlib" -> "loaded from SYSROOT/libstd-*.rlib"
+// normalize-stderr-test "loaded from .*libstd-.*.rmeta" -> "loaded from SYSROOT/libstd-*.rmeta"


The .rmeta file is now considered the canonical one as the .rlib doesn't contain any crate metadata beyond the header.

bjorn3 · 2024-02-09T18:52:35Z

@bors try @rust-timer queue

bors · 2024-02-09T18:53:44Z

⌛ Trying commit 7770002 with merge 8fb65ac...

Introduce -Zsplit-metadata option This will split the crate metadata out of library files. Instead only the svh and a bit of extra metadata is preserved to allow for loading the right rmeta file. This significantly reduces library size. In addition it allows for cheaper checks if different library files are the same crate. A fair amount of the complexity in this PR is to work around the fact that cargo doesn't directly support this option yet. Fixes rust-lang#23366 Fixes rust-lang#57076 Revives rust-lang#93945

bjorn3 · 2024-02-09T18:54:55Z

What would be the best way to handle the necessary cargo changes? We can't use them until the bootstrap compiler includes the cargo changes, but cargo would depend on -Zsplit-metadata which doesn't exist yet. Would unconditionally creating a .rmeta file for dylibs like we do for rlibs be fine? Or should I add a -Zsplit-metadata option to cargo without it getting tested and then once the bootstrap bump happens, change this PR to use this option? Or land -Zsplit-metadata first without actually making any use of it, then update cargo and finally make use of it in the standard library?

bors · 2024-02-09T20:22:41Z

☀️ Try build successful - checks-actions
Build commit: 8fb65ac (8fb65acf1a11f547302c62c93bf83cca3ff4cd9d)

rust-timer · 2024-02-09T23:49:26Z

Finished benchmarking commit (8fb65ac): comparison URL.

Overall result: ❌✅ regressions and improvements - ACTION NEEDED

Benchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf.

Next Steps: If you can justify the regressions found in this try perf run, please indicate this with @rustbot label: +perf-regression-triaged along with sufficient written justification. If you cannot justify the regressions please fix the regressions and do another perf run. If the next run shows neutral or positive results, the label will be automatically removed.

@bors rollup=never
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	1.4%	[0.3%, 2.7%]	7
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-0.4%	[-0.5%, -0.4%]	3
All ❌✅ (primary)	-	-	0

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	7.1%	[5.4%, 8.4%]	4
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-5.2%	[-5.2%, -5.2%]	1
All ❌✅ (primary)	-	-	0

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 666.509s -> 669.311s (0.42%)
Artifact size: 307.99 MiB -> 301.34 MiB (-2.16%)

bjorn3 · 2024-02-10T14:17:08Z

This should save about 4MB on the download size of a toolchain without any extra targets other than the host:

component	`e28fae5` (no split metadata)	`8fb65ac` (split metadata)	diff
rustc	70.54MB	68.39MB	-2.15MB
rust-std	27.63MB	25.61MB	-2MB
rustc-dev	110.84MB	110.90MB	+0.06MB

For Bevy the size of the target dir shrinks a lot:

mode	normal build	`--emit metadata -Zsplit-metadata`	diff	relative diff
debug mode	4.6GiB	4.3GiB	-300MiB	-6.5%
debug mode (no incr comp)	2.8GiB	2.6GiB	-200MiB	-7%
release mode	843.6MiB	614.3MiB	-230MiB	-27%

bors · 2024-02-16T09:54:33Z

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

petrochenkov · 2024-03-07T15:10:42Z

@bjorn3
Could you

Split 2eb24d9 into a separate PR in case it causes regressions
Split all preparatory refactorings like 1065559 into a separate PR
Rebase the remaining changes, make CI green, cleanup history, and add FIXME comments to logic that only exists due to lacking cargo support

(I'll be able to review the first two PRs quickly.)
@rustbot author

bors · 2024-12-27T15:58:48Z

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

This will split the crate metadata out of library files. Instead only the svh is preserved to allow for loading the right rmeta file. This significicantly reduces library size. In addition it allows for cheaper checks if different library files are the same crate.

petrochenkov · 2025-02-19T15:39:53Z

Status is not very clear, still waiting on author.
@bjorn3 Do you plan to work on completing it this year?

bjorn3 · 2025-02-19T15:43:32Z

I do still plan on working on this.

petrochenkov · 2025-03-13T13:23:56Z

Closing in favor of #137535.

Introduce `-Zembed-metadata` to allow omitting full metadata from rlibs and dylibs This is a continuation of rust-lang#120855 (I was mentored by `@bjorn3` to move it forward). Most of the original code was written by bjorn3, I tried to clean it up a bit and add some documentation and tests. This PR introduces a new unstable compiler flag called `-Zembed-metadata=[no|yes]`, with the default being `yes` (see rust-lang#57076 for context). When set to `no`, rustc will only store a small metadata stub inside rlibs/dylibs instead of the full metadata, to keep their size smaller. It should be used in combination with `--emit=metadata`, so that the users of such a compiled library can still read the metadata from the corresponding `.rmeta` file. [This comment](rust-lang#120855 (comment)) shows an example of binary/artifact size wins that can be achieved using this approach. Contrary to rust-lang#120855, this PR only introduces the new flag, along with a couple of run-make tests and documentation, but does not yet use it in bootstrap to actually compile rustc. I plan to do that as a follow-up step (along with integration in Cargo, which should ideally just always pass this flag to reduce the size of target directories). Fixes rust-lang#23366 Closes rust-lang#29511 Fixes rust-lang#57076 Another attempt of rust-lang#93945 and rust-lang#120855. r? `@petrochenkov`

Introduce `-Zembed-metadata` to allow omitting full metadata from rlibs and dylibs This is a continuation of rust-lang/rust#120855 (I was mentored by `@bjorn3` to move it forward). Most of the original code was written by bjorn3, I tried to clean it up a bit and add some documentation and tests. This PR introduces a new unstable compiler flag called `-Zembed-metadata=[no|yes]`, with the default being `yes` (see rust-lang/rust#57076 for context). When set to `no`, rustc will only store a small metadata stub inside rlibs/dylibs instead of the full metadata, to keep their size smaller. It should be used in combination with `--emit=metadata`, so that the users of such a compiled library can still read the metadata from the corresponding `.rmeta` file. [This comment](rust-lang/rust#120855 (comment)) shows an example of binary/artifact size wins that can be achieved using this approach. Contrary to rust-lang/rust#120855, this PR only introduces the new flag, along with a couple of run-make tests and documentation, but does not yet use it in bootstrap to actually compile rustc. I plan to do that as a follow-up step (along with integration in Cargo, which should ideally just always pass this flag to reduce the size of target directories). Fixes rust-lang/rust#23366 Closes rust-lang/rust#29511 Fixes rust-lang/rust#57076 Another attempt of rust-lang/rust#93945 and rust-lang/rust#120855. r? `@petrochenkov`

@bjorn3

### What does this PR try to resolve? This PR adds Cargo integration for the new unstable `-Zembed-metadata` rustc flag, which was implemented in rust-lang/rust#137535 ([tracking issue](rust-lang/rust#139165)). The new behavior has to be enabled explicitly using a new unstable CLI flag `-Zno-embed-metadata`. The `-Zembed-metadata=no` rustc flag can reduce disk usage of compiled artifacts, and also the size of Rust dynamic library artifacts shipped to users. However, it is not enough to just pass this flag through `RUSTFLAGS`; it needs to be integrated within Cargo, because it interacts with how the `--emit` flag is passed to rustc, and also how `--extern` args are passed to the final linked artifact build by Cargo. Furthermore, using the flag for all crates in a crate graph compiled by Cargo would be suboptimal (this will all be described below). When you pass `-Zembed-metadata=no` to rustc, it will not store Rust metadata into the compiled artifact. This is important when compiling libs/rlibs/dylibs, since it reduces their size on disk. However, this also means that everytime we use this flag, we have to make sure that we also: - Include `metadata` in the `--emit` flag to generate a `.rmeta` file, otherwise no metadata would be generated whatsoever, which would mean that the artifact wouldn't be usable as a dependency. - Pass also `--extern <dep>=<path>.rmeta` when compiling the final linkable artifact. Before, Cargo would only pass `--extern <dep>=<path>.[rlib|so|dll]`. Since with `-Zembed-metadata=no`, the metadata is only in the `.rmeta` file and not in the rlib/dylib, this is needed to help rustc find out where the metadata lies. - Note: this essentially doubles the cmdline length when compiling the final linked artifact. Not sure if that is a concern. The two points above is what this PR implements, and why this rustc flag needs Cargo integration. The `-Zembed-metadata` flag is only passed to libs, rlibs and dylibs. It does not seem to make sense for other crate types. The one situation where it might make sense are proc macros, but according to @bjorn3 (who initially came up with the idea for `-Zembed-metadata`, it isn't really worth it). Here is a table that summarizes the changes in passed flags and generated files on disk for rlibs and dylibs: | **Crate type** | **Flags** | **Generated files** | **Disk usage** | |--|--|--|--| | Rlib/Lib (before) | `--emit=dep-info,metadata,link` | `.rlib` (with metadata), `.rmeta` (for pipelining) | - | | Rlib/Lib (after) | `--emit=dep-info,metadata,link -Zembed-metadata=no` | `.rlib` (without metadata), `.rmeta` (for metadata/pipelining) | Reduced (metadata no longer duplicated) | | Dylib (before) | `--emit=dep-info,link` | `[.so\|.dll]` (with metadata) | - | | Dylib (after) | `--emit=dep-info,metadata,link -Zembed-metadata=no` | `[.so\|.dll]` (without metadata), `.rmeta` | Unchanged, but split between two files | Behavior for other target kinds/crate types should be unchanged. From the table above, we can see two benefits of using `-Zembed-metadata=no`: - For rlibs/dylibs, we no longer store their metadata twice in the target directory, thus reducing target directory size. - For dylibs, we store esssentially the same amount of data on disk, but the benefit is that the metadata is now in a separate .rmeta file. This means that you can ship the dylib (`.so`/`.dll`) to users without also shipping the metadata. This would slightly reduce e.g. the [size](rust-lang/rust#120855 (comment)) of the shipped rustc toolchains (note that the size reduction here is after the toolchain has been already heavily compressed). Note that if this behavior ever becomes the default, it should be possible to simplify the code quite a bit, and essentially merge the `requires_upstream_objects` and `benefits_from_split_metadata` functions. I did a very simple initial benchmark to evaluate the space savings on cargo itself and [hyperqueue](https://github.com/It4innovations/hyperqueue) (a mid-size crate from my work) using `cargo build` and `cargo build --release` with and without `-Zembed-metadata=no`: ![image](https://github.com/user-attachments/assets/a26994a2-156f-4863-a823-1042ebe03bf0) For debug/incremental builds, the effect is smaller, as the artifact disk usage is dwarfed by incremental artifacts and debuginfo. But for (non-incremental) release builds, the disk savings (and also performed I/O operations) are significantly reduced. ### How should we test and review this PR? I wrote two basic tests. The second one tests a situation where a crate depends on a dylib dependency, which is quite rare, but the behavior of this has actually changed in this PR (see comparison table above). Testing this on various real-world projects (or even trying to enable it by default across the whole Cargo suite?) might be beneficial. ## Unresolved questions ### Is this a breaking change? With this new behavior, dylibs and rlibs will no longer contain metadata. If they are compiled with Cargo, that shouldn't matter, but other build systems might have to adapt. ### Should this become the default? I think that in terms of disk size usage and performed I/O operations, it is a pure win. It should either generate less disk data (for rlibs) or the ~same amount of data for dylibs (the data will be a bit larger, because the dylib will still contain a metadata stub header, but that's like 50 bytes and doesn't scale with the size of the dylib, so it's negligible). So I think that eventually, we should just do this by default in Cargo, unless some concerns are found. I suppose that before stabilizing we should also benchmark the effect on compilation performance.

@bjorn3

…=petrochenkov Stabilize `-Zembed-metadata` Tracking issue: rust-lang#139165 This PR proposes to stabilize the `-Zembed-metadata` compiler flag, so that Cargo can start using `-Cembed-metadata=no` by default on the stable channel. The flag can be used to avoid duplicating the metadata of Rust crates within `.rlib` and `.rmeta` files. This can reduce the size of the `target` directory anywhere from 5% to 35% on real-world projects, depending on the chosen compilation profile ([1][kobzol-blog], [2][cargo-blog]). Additionally, `-Cembed-metadata=no` also removes the metadata out of Rust `dylib`s, and thus reduces their size. The plan is to stabilize this compiler flag so that Cargo can start using it on the stable channel. The stabilization plan thus has two parts: - Stabilize the `-Cembed-metadata` flag in `rustc` - Change Cargo to use `-Cembed-metadata=no` by default The Cargo team has prepared their side of the [stabilization report](rust-lang/cargo#17533). You can examine it to see the whole picture. ## What is being stabilized The `-Zembed-metadata` compiler flag. Note that `rustc` will still default to `-Cembed-metadata=yes`, as that is its original behavior since [Rust 1.16.0](https://blog.rust-lang.org/2017/03/16/Rust-1.16/#other-improvements). But it will now be possible to pass `-Cembed-metadata=no` on stable. ## Motivation When compiling Rust crates as libraries, Cargo uses pipelined compilation, which tells `rustc` (using `--emit=metadata`) to output an `.rmeta` file as soon as possible, so that Cargo can start follow-up `rustc` instances sooner and speed up the compilation process. This file contains the Rust-specific metadata of the compiled crate. However, after the compilation of the Rust crate finishes, the compiler will also write an `.rlib` file to disk, which contains both the compiled object code, but also the same metadata that is already contained in the `.rmeta` file. This means that after the compilation finishes, the metadata of each (non-leaf) compiled crate will be duplicated on disk. The metadata can be quite large, and it is not uncommon that it takes hundreds of megabytes for real-world projects. This duplication thus contributes to increasing the size of the `target` directory, which large size is one of the top 3 most pressing [challenges](https://blog.rust-lang.org/2026/03/02/2025-State-Of-Rust-Survey-results/#challenges-and-wishes-about-rust) that Rust users struggle with. The `-Cembed-metadata=no` flag removes this duplication (see [below](#What-does-the-flag-do) on how it works). Some size benchmark results can be found in ([1][kobzol-blog], [2][cargo-blog]). It can reach up to 35% size reduction on real-world projects in `release` mode, with the effect being smaller for `dev` builds (because incremental artifacts and debuginfo start to dominate the `target` directory size). A slight bonus is that we only write the metadata to disk once, thus resulting in less I/O. I haven't noticed any measurable effect (either positive or negative) on compile times though, at least on Linux. The main motivation is disk size, not compilation speed. ## What does the flag do When you pass `-Cembed-metadata=no`, `rustc` will not write the full metadata of the compiled crate into the emitted `.rlib` file. Instead, it will only write a ["metadata stub"](https://github.com/rust-lang/rust/blob/79ee8dc08073a0abf93d2b494ac5c1be11d4342e/compiler/rustc_metadata/src/rmeta/encoder.rs#L2552), which only contains the most basic information (name, target tuple, SVH). Note that this flag should usually be combined with `--emit=metadata` to write the metadata to a `.rmeta` file, otherwise no metadata would be generated at all. When loading crate dependencies passed via `--extern`, `rustc` will read the metadata of the passed `.rlib`. If it only contains a stub, it expects that you will also pass another `--extern` flag with a path to a `.rmeta` file with the full metadata. If you don't, you will be met with the following error: ``` error: only metadata stub found for `rlib` dependency `foo`. Please provide path to the corresponding .rmeta file with full metadata ``` Note that `rustc` will still default to the original behavior of embedding metadata, so build systems that wrap `rustc` will have to explicitly opt into using `-Cembed-metadata=no`, and at that point they will also have to start passing `--extern=<...>.rmeta` flags to `rustc`. That is what Cargo currently does if you use `nightly` or if you use the unstable `-Zembed-metadata=no` *Cargo* flag. In theory, we could relax the requirement to pass both paths to the `.rlib` and the `.rmeta` file for each direct dependency in the future, and let `rustc --extern=foo/bar.rlib` automatically attempt to load `--extern=foo/bar.rmeta` when the `.rmeta` file path is not passed explicitly. `.rlib` and `.rmeta` files produced using `-Cembed-metadata=no` and `-Cembed-metadata=yes` can be freely combined, and a downstream `rustc` invocation that consumes artifacts produced by `=no` does not need to itself receive the `=no` flag. ## Ecosystem impact The `-Zembed-metadata` flag has been used for the standard library that we ship since January 2026 (rust-lang#145343) and for the compiler itself and codegen backends (cg_clif and cg_gcc) since August 2026 (rust-lang#151061). The flag has also been used by Cargo by default on the `nightly` channel since the second half of August 2026. A blog post with a call for testing can be found [here](https://blog.rust-lang.org/inside-rust/2026/08/18/reducing-target-dir-size-on-nightly/). I'm not aware of any regressions or issues reported in relation to this, not is the Cargo team (AFAIK). There are some unresolved questions about backwards compability if Cargo starts passing `-Cembed-metadata=no` by default, but those are related strictly to Cargo, and not the compiler flag itself (because the compiler flag will remain opt-in). ## History The issue of duplicated metadata was originally noted back in 2015 (rust-lang#23366, rust-lang#29511), back then because of the metadata being duplicated in Rust `dylib`s. Since Cargo started using pipelined compilation by default, it became more acute, because the metadata of all compiled `.rlib` crate dependencies started being duplicated in the `target` directory. @bjorn3 proposed to add a compiler flag to split out the metadata into a separate file in rust-lang#57076. The implementation was attempted in rust-lang#93945 and later in rust-lang#120855, but there was non-trivial complexity due to Cargo integration. In 2025, I opened an [MCP](rust-lang/compiler-team#851) with the plan to implement this flag in two stages (first in rustc, and only then in Cargo), to reduce the implementation complexity, which was accepted. The implementation in `rustc` then happened in rust-lang#137535. Implementation history: - rust-lang#137535 (April 2025): Introduction of `-Zembed-metadata`, reviewed by @petrochenkov - rust-lang/cargo#15378 (May 2025): Initial integration in Cargo, reviewed by @epage - rust-lang#145343 (January 2026): Dogfood the flag for stdlib, reviewed by @bjorn3 - rust-lang#151061 (August 2026): Dogfood the flag for rustc and codegen backends, authored by @bjorn3 - rust-lang/cargo#17267 (August 2026): Enabled the `-Cembed-metadata=no` flag by default by Cargo on the `nightly` channel ## Unresolved questions/concerns ### Command-line length limit This is more related to the Cargo side of things, but I also wanted to mention it here, because there is a possible improvement we could do on the compiler side in the future. As noted [above](#What-does-the-flag-do), usage of `-Cembed-metadata=no` requires the build system/user to pass two `--extern` flags for each direct dependency of a given `rustc` invocation. This can increase the size of the executed command-line arguments, which can in edge cases start running into operating system limits. Recently, we saw something similar in action with the Cargo's new build dir layout stabilization, where Cargo suddenly started passing a lot more `-L` flags to `rustc`, which caused issues around CLI length limits and `PATH` env. var. length limits. Cargo can work around the CLI length limit by using response files (`rustc @args`), but not all downstream tools (such as `sccache`) support those fully (yet). Based on the experience with the new build dir layout, some work was done to improve this support in the ecosystem though, and to optimize the number of flags that Cargo passes to `rustc`. If this became a problem in practice, we could teach `rustc` to start implicitly assuming `--extern=foo.rmeta` when `--extern=foo.rlib` was passed. This would reduce the number of required `--extern` flags passed to the same count as with `-Cembed-metadata=yes` (or without using that flag at all). I think that we can always do this retroactively if needed without breaking backwards compatibility, so it does not have to block this stabilization. ### Landing this change Given that this compiler flag is expected to have tight integration with Cargo, and Cargo already uses it on the nightly channel by default, we have to be a bit careful about how we actually land the `-Zembed-metadata` => `-Cembed-metadata` change. Problem A: if we simply switched it from `-Z` to `-C` in `rust-lang/rust`, then nightly would break from the following day, because Cargo would be still attempting to pass the `-Z` flag, while `rustc` would already be expecting the `-C` variant of the flag. Problem B: furthermore, bootstrap currently unconditionally passes `-Zembed-metadata=no`, both to in-tree Cargo and to beta Cargo, so that also requires some attention. There are several options of how we could resolve this: 1. Conclude the nightly Cargo experiment, so that it will not pass `-Zembed-metadata=no` to `rustc` by default anymore. Then sync Cargo to `rust-lang/rust`, and only then merge this PR. This solves A. 2. Move Cargo from a git submodule to a (Josh) subtree, so that we can atomically change both Cargo and `rustc` to use `-C` instead of `-Z` (inside this PR), to avoid breaking nightly users. This solves A. - Even though I would like to do this migration anyway, I don't think that we need to tie it to this stabilization, as it can take some time before we resolve all concerns about the migration. 3. Do what 2. proposes, but without a subtree. That means that we have to: - Change to `-C` in Cargo - Change to `-C` in `rust-lang/rust` - Sync the Cargo change back to `rust-lang/rust` in the same day that we land the `rustc` change While this solves A, it might run into some staging issues in bootstrap, and it looks very complicated to pull off. 4. Teach `rustc` to accept both the `-Z` and the `-C` variant of the flag for some time. This solves both A and B, and also gives people who use `-Zembed-metadata` manually on `nightly` some breathing room to upgrade to the `-C` variant of the flag (but GitHub code search didn't find many usages of this flag, and this is normally an expected breakage for users of unstable compiler flags). I decided to go with 4, because the integration with Cargo is tight, and modifying bootstrap back and forth to support `-Z`/no flag /`-C` would be busy work. This solves both A and B and requires little implementation effort. ## Acknowledgments - @bjorn3 for coming up with the idea, providing a reference implementation and mentoring me to finish up the implementation - @petrochenkov for reviewing the compiler side of things - @epage and @weihanglo for reviewing the Cargo side of things [kobzol-blog]: https://kobzol.github.io/rust/rustc/2025/06/02/reduce-cargo-target-dir-size-with-z-no-embed-metadata.html#cargo-integration [cargo-blog]: https://blog.rust-lang.org/inside-rust/2026/08/18/reducing-target-dir-size-on-nightly/#how-much-does-it-help CC @bjorn3 @petrochenkov @weihanglo @epage r? petrochenkov @rustbot label +needs-fcp +T-compiler

@bjorn3

Rollup merge of #163436 - Kobzol:stabilize-embed-metadata, r=petrochenkov Stabilize `-Zembed-metadata` Tracking issue: #139165 This PR proposes to stabilize the `-Zembed-metadata` compiler flag, so that Cargo can start using `-Cembed-metadata=no` by default on the stable channel. The flag can be used to avoid duplicating the metadata of Rust crates within `.rlib` and `.rmeta` files. This can reduce the size of the `target` directory anywhere from 5% to 35% on real-world projects, depending on the chosen compilation profile ([1][kobzol-blog], [2][cargo-blog]). Additionally, `-Cembed-metadata=no` also removes the metadata out of Rust `dylib`s, and thus reduces their size. The plan is to stabilize this compiler flag so that Cargo can start using it on the stable channel. The stabilization plan thus has two parts: - Stabilize the `-Cembed-metadata` flag in `rustc` - Change Cargo to use `-Cembed-metadata=no` by default The Cargo team has prepared their side of the [stabilization report](rust-lang/cargo#17533). You can examine it to see the whole picture. ## What is being stabilized The `-Zembed-metadata` compiler flag. Note that `rustc` will still default to `-Cembed-metadata=yes`, as that is its original behavior since [Rust 1.16.0](https://blog.rust-lang.org/2017/03/16/Rust-1.16/#other-improvements). But it will now be possible to pass `-Cembed-metadata=no` on stable. ## Motivation When compiling Rust crates as libraries, Cargo uses pipelined compilation, which tells `rustc` (using `--emit=metadata`) to output an `.rmeta` file as soon as possible, so that Cargo can start follow-up `rustc` instances sooner and speed up the compilation process. This file contains the Rust-specific metadata of the compiled crate. However, after the compilation of the Rust crate finishes, the compiler will also write an `.rlib` file to disk, which contains both the compiled object code, but also the same metadata that is already contained in the `.rmeta` file. This means that after the compilation finishes, the metadata of each (non-leaf) compiled crate will be duplicated on disk. The metadata can be quite large, and it is not uncommon that it takes hundreds of megabytes for real-world projects. This duplication thus contributes to increasing the size of the `target` directory, which large size is one of the top 3 most pressing [challenges](https://blog.rust-lang.org/2026/03/02/2025-State-Of-Rust-Survey-results/#challenges-and-wishes-about-rust) that Rust users struggle with. The `-Cembed-metadata=no` flag removes this duplication (see [below](#What-does-the-flag-do) on how it works). Some size benchmark results can be found in ([1][kobzol-blog], [2][cargo-blog]). It can reach up to 35% size reduction on real-world projects in `release` mode, with the effect being smaller for `dev` builds (because incremental artifacts and debuginfo start to dominate the `target` directory size). A slight bonus is that we only write the metadata to disk once, thus resulting in less I/O. I haven't noticed any measurable effect (either positive or negative) on compile times though, at least on Linux. The main motivation is disk size, not compilation speed. ## What does the flag do When you pass `-Cembed-metadata=no`, `rustc` will not write the full metadata of the compiled crate into the emitted `.rlib` file. Instead, it will only write a ["metadata stub"](https://github.com/rust-lang/rust/blob/79ee8dc08073a0abf93d2b494ac5c1be11d4342e/compiler/rustc_metadata/src/rmeta/encoder.rs#L2552), which only contains the most basic information (name, target tuple, SVH). Note that this flag should usually be combined with `--emit=metadata` to write the metadata to a `.rmeta` file, otherwise no metadata would be generated at all. When loading crate dependencies passed via `--extern`, `rustc` will read the metadata of the passed `.rlib`. If it only contains a stub, it expects that you will also pass another `--extern` flag with a path to a `.rmeta` file with the full metadata. If you don't, you will be met with the following error: ``` error: only metadata stub found for `rlib` dependency `foo`. Please provide path to the corresponding .rmeta file with full metadata ``` Note that `rustc` will still default to the original behavior of embedding metadata, so build systems that wrap `rustc` will have to explicitly opt into using `-Cembed-metadata=no`, and at that point they will also have to start passing `--extern=<...>.rmeta` flags to `rustc`. That is what Cargo currently does if you use `nightly` or if you use the unstable `-Zembed-metadata=no` *Cargo* flag. In theory, we could relax the requirement to pass both paths to the `.rlib` and the `.rmeta` file for each direct dependency in the future, and let `rustc --extern=foo/bar.rlib` automatically attempt to load `--extern=foo/bar.rmeta` when the `.rmeta` file path is not passed explicitly. `.rlib` and `.rmeta` files produced using `-Cembed-metadata=no` and `-Cembed-metadata=yes` can be freely combined, and a downstream `rustc` invocation that consumes artifacts produced by `=no` does not need to itself receive the `=no` flag. ## Ecosystem impact The `-Zembed-metadata` flag has been used for the standard library that we ship since January 2026 (#145343) and for the compiler itself and codegen backends (cg_clif and cg_gcc) since August 2026 (#151061). The flag has also been used by Cargo by default on the `nightly` channel since the second half of August 2026. A blog post with a call for testing can be found [here](https://blog.rust-lang.org/inside-rust/2026/08/18/reducing-target-dir-size-on-nightly/). I'm not aware of any regressions or issues reported in relation to this, not is the Cargo team (AFAIK). There are some unresolved questions about backwards compability if Cargo starts passing `-Cembed-metadata=no` by default, but those are related strictly to Cargo, and not the compiler flag itself (because the compiler flag will remain opt-in). ## History The issue of duplicated metadata was originally noted back in 2015 (#23366, #29511), back then because of the metadata being duplicated in Rust `dylib`s. Since Cargo started using pipelined compilation by default, it became more acute, because the metadata of all compiled `.rlib` crate dependencies started being duplicated in the `target` directory. @bjorn3 proposed to add a compiler flag to split out the metadata into a separate file in #57076. The implementation was attempted in #93945 and later in #120855, but there was non-trivial complexity due to Cargo integration. In 2025, I opened an [MCP](rust-lang/compiler-team#851) with the plan to implement this flag in two stages (first in rustc, and only then in Cargo), to reduce the implementation complexity, which was accepted. The implementation in `rustc` then happened in #137535. Implementation history: - #137535 (April 2025): Introduction of `-Zembed-metadata`, reviewed by @petrochenkov - rust-lang/cargo#15378 (May 2025): Initial integration in Cargo, reviewed by @epage - #145343 (January 2026): Dogfood the flag for stdlib, reviewed by @bjorn3 - #151061 (August 2026): Dogfood the flag for rustc and codegen backends, authored by @bjorn3 - rust-lang/cargo#17267 (August 2026): Enabled the `-Cembed-metadata=no` flag by default by Cargo on the `nightly` channel ## Unresolved questions/concerns ### Command-line length limit This is more related to the Cargo side of things, but I also wanted to mention it here, because there is a possible improvement we could do on the compiler side in the future. As noted [above](#What-does-the-flag-do), usage of `-Cembed-metadata=no` requires the build system/user to pass two `--extern` flags for each direct dependency of a given `rustc` invocation. This can increase the size of the executed command-line arguments, which can in edge cases start running into operating system limits. Recently, we saw something similar in action with the Cargo's new build dir layout stabilization, where Cargo suddenly started passing a lot more `-L` flags to `rustc`, which caused issues around CLI length limits and `PATH` env. var. length limits. Cargo can work around the CLI length limit by using response files (`rustc @args`), but not all downstream tools (such as `sccache`) support those fully (yet). Based on the experience with the new build dir layout, some work was done to improve this support in the ecosystem though, and to optimize the number of flags that Cargo passes to `rustc`. If this became a problem in practice, we could teach `rustc` to start implicitly assuming `--extern=foo.rmeta` when `--extern=foo.rlib` was passed. This would reduce the number of required `--extern` flags passed to the same count as with `-Cembed-metadata=yes` (or without using that flag at all). I think that we can always do this retroactively if needed without breaking backwards compatibility, so it does not have to block this stabilization. ### Landing this change Given that this compiler flag is expected to have tight integration with Cargo, and Cargo already uses it on the nightly channel by default, we have to be a bit careful about how we actually land the `-Zembed-metadata` => `-Cembed-metadata` change. Problem A: if we simply switched it from `-Z` to `-C` in `rust-lang/rust`, then nightly would break from the following day, because Cargo would be still attempting to pass the `-Z` flag, while `rustc` would already be expecting the `-C` variant of the flag. Problem B: furthermore, bootstrap currently unconditionally passes `-Zembed-metadata=no`, both to in-tree Cargo and to beta Cargo, so that also requires some attention. There are several options of how we could resolve this: 1. Conclude the nightly Cargo experiment, so that it will not pass `-Zembed-metadata=no` to `rustc` by default anymore. Then sync Cargo to `rust-lang/rust`, and only then merge this PR. This solves A. 2. Move Cargo from a git submodule to a (Josh) subtree, so that we can atomically change both Cargo and `rustc` to use `-C` instead of `-Z` (inside this PR), to avoid breaking nightly users. This solves A. - Even though I would like to do this migration anyway, I don't think that we need to tie it to this stabilization, as it can take some time before we resolve all concerns about the migration. 3. Do what 2. proposes, but without a subtree. That means that we have to: - Change to `-C` in Cargo - Change to `-C` in `rust-lang/rust` - Sync the Cargo change back to `rust-lang/rust` in the same day that we land the `rustc` change While this solves A, it might run into some staging issues in bootstrap, and it looks very complicated to pull off. 4. Teach `rustc` to accept both the `-Z` and the `-C` variant of the flag for some time. This solves both A and B, and also gives people who use `-Zembed-metadata` manually on `nightly` some breathing room to upgrade to the `-C` variant of the flag (but GitHub code search didn't find many usages of this flag, and this is normally an expected breakage for users of unstable compiler flags). I decided to go with 4, because the integration with Cargo is tight, and modifying bootstrap back and forth to support `-Z`/no flag /`-C` would be busy work. This solves both A and B and requires little implementation effort. ## Acknowledgments - @bjorn3 for coming up with the idea, providing a reference implementation and mentoring me to finish up the implementation - @petrochenkov for reviewing the compiler side of things - @epage and @weihanglo for reviewing the Cargo side of things [kobzol-blog]: https://kobzol.github.io/rust/rustc/2025/06/02/reduce-cargo-target-dir-size-with-z-no-embed-metadata.html#cargo-integration [cargo-blog]: https://blog.rust-lang.org/inside-rust/2026/08/18/reducing-target-dir-size-on-nightly/#how-much-does-it-help CC @bjorn3 @petrochenkov @weihanglo @epage r? petrochenkov @rustbot label +needs-fcp +T-compiler

rustbot assigned cjgillot Feb 9, 2024

bjorn3 commented Feb 9, 2024

View reviewed changes

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Feb 9, 2024

bjorn3 mentioned this pull request Feb 9, 2024

Introduce -Zsplit-metadata option #93945

Closed

This comment has been minimized.

Sign in to view

petrochenkov self-assigned this Feb 9, 2024

This comment has been minimized.

Sign in to view

rustbot added perf-regression Performance regression. and removed S-waiting-on-perf Status: Waiting on a perf run to be completed. labels Feb 9, 2024

cjgillot removed their assignment Feb 18, 2024

rustbot 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-review Status: Awaiting review from the assignee but also interested parties. labels Mar 7, 2024

bjorn3 mentioned this pull request Mar 8, 2024

Remove a workaround for a bug #122186

Closed

bjorn3 force-pushed the split_metadata4 branch from d093c9d to fe906a0 Compare November 27, 2024 15:25

This comment has been minimized.

Sign in to view

bjorn3 force-pushed the split_metadata4 branch from fe906a0 to d918933 Compare January 9, 2025 13:42

This comment has been minimized.

Sign in to view

bjorn3 force-pushed the split_metadata4 branch from d918933 to 3d17fbe Compare January 14, 2025 15:23

This comment has been minimized.

Sign in to view

Simplify find_commandline_library

8656e1b

bjorn3 force-pushed the split_metadata4 branch 2 times, most recently from 0e3b1b5 to 32bd529 Compare January 14, 2025 16:13

bjorn3 and others added 3 commits January 14, 2025 16:15

Fix stdlib building

50c1208

Rustbuild: enable -Zsplit-metadata for stage != 0

bedeb19

bjorn3 force-pushed the split_metadata4 branch from 32bd529 to bedeb19 Compare January 14, 2025 16:17

This comment has been minimized.

Sign in to view

Fix cg_clif tests

6720404

Kobzol mentioned this pull request Feb 24, 2025

Introduce -Zembed-metadata to allow omitting full metadata from rlibs and dylibs #137535

Merged

petrochenkov closed this Mar 13, 2025

bjorn3 deleted the split_metadata4 branch March 13, 2025 13:32

Kobzol mentioned this pull request Mar 14, 2025

Add -Zsplit-metadata flag to reduce disk usage rust-lang/compiler-team#851

Closed

1 of 3 tasks

Kobzol mentioned this pull request Apr 2, 2025

Add support for -Zembed-metadata rust-lang/cargo#15378

Merged

Kobzol mentioned this pull request Sep 28, 2026

Stabilize -Zembed-metadata #163436

Merged

		@@ -1,4 +1,4 @@
		// normalize-stderr-test "loaded from .libstd-..rlib" -> "loaded from SYSROOT/libstd-*.rlib"
		// normalize-stderr-test "loaded from .libstd-..rmeta" -> "loaded from SYSROOT/libstd-*.rmeta"

Conversation

bjorn3 commented Feb 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Feb 9, 2024

Uh oh!

bjorn3 Feb 9, 2024

Choose a reason for hiding this comment

Uh oh!

bjorn3 Feb 9, 2024

Choose a reason for hiding this comment

Uh oh!

bjorn3 Feb 9, 2024

Choose a reason for hiding this comment

Uh oh!

bjorn3 commented Feb 9, 2024

Uh oh!

This comment has been minimized.

bors commented Feb 9, 2024

Uh oh!

bjorn3 commented Feb 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

bors commented Feb 9, 2024

Uh oh!

This comment has been minimized.

This comment has been minimized.

rust-timer commented Feb 9, 2024

Overall result: ❌✅ regressions and improvements - ACTION NEEDED

Instruction count

Max RSS (memory usage)

Cycles

Binary size

Uh oh!

bjorn3 commented Feb 10, 2024

Uh oh!

bors commented Feb 16, 2024

Uh oh!

petrochenkov commented Mar 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

bors commented Dec 27, 2024

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

petrochenkov commented Feb 19, 2025

Uh oh!

bjorn3 commented Feb 19, 2025

Uh oh!

petrochenkov commented Mar 13, 2025

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

bjorn3 commented Feb 9, 2024 •

edited

Loading

bjorn3 commented Feb 9, 2024 •

edited

Loading

petrochenkov commented Mar 7, 2024 •

edited

Loading