Upstream work · rust-lang/rust
Changing what goes inside a Rust rlib
Building a Rust program has two different jobs: understand the code, then join the compiled pieces into a program. A Rust library stores information for both. I worked on five merged compiler changes that put link-time details in their own part of the library, replace a guess based on file names, and fix a reader that handled AIX differently.
By Mehdi Akiki. Pull request status checked October 31, 2026.
First, what is an rlib?
An rlib is a Rust library file. Think of it as a box containing smaller files. The compiler needs some of those files to understand a library's types and functions. Later, it needs others to build the final executable.
The second step is called linking: joining compiled code and its dependencies into the result you run. The linker does not need every fact that helped the compiler check your Rust code. The compiler does not need every link-time detail while checking the next crate.
My changes make that boundary clearer. They do not change how you write a function or add a new Rust language feature.
A crate is one unit of Rust code being compiled, such as a library. Metadata describes that code, including its types and functions. An archive member is one file inside the archive.
| Part of the archive | What it tells the compiler | When it is needed |
|---|---|---|
lib.rmeta | Information about the crate's Rust code | While compiling code that uses the crate |
lib.rmeta-link | Which objects came from Rust, and link-only library filenames | While linking |
| Object files and bundled native libraries | The compiled code that will be joined together | While linking |
How I came to this
I came to this work by reading the current compiler code: how rustc writes an rlib, reads it back, and links it. That is how I found the problem and started working on it.
For me, understanding Rust was more than learning Rust. It was a way to become a much better software engineer, interested in hard and practical problems.
The problem
An rlib is an ar archive. It contains the crate metadata that other crates compile against, the object files produced by code generation, and sometimes native libraries bundled into it.
When rustc needed to know which members are Rust object files, for example to read them for LTO, it looked at the member name: a Rust object file ends in .rcgu.o. But a bundled native library can put a member with any name into the archive, including one that ends in .rcgu.o. And facts that only the linker needs, like the filenames of bundled native libraries, were computed and decoded with the early metadata.
The tracking issue, opened by Vadim Petrochenkov, proposed one more metadata member for rlibs: link-time facts, read only when rustc links the rlib into something.
Why a filename was not enough
A filename is a label, not proof of where the code came from. Rust-generated object files used a particular ending, .rcgu.o. A bundled native library could also contain a file with that ending.
The first change records the Rust object members explicitly in lib.rmeta-link. Code doing link-time optimization can read that list instead of guessing. Link-time optimization, or LTO, lets the compiler optimize across compiled pieces before it finishes the program.
In plain terms, the archive now carries a list written by the component that knows which objects it produced. The reader uses that list. The old filename check was removed in the merged change.
Moving the information also meant moving its reader
A later change moved the filenames of bundled native libraries out of the ordinary crate metadata. A native library here is compiled code from outside Rust, such as a C library. Rust still needs to know about these libraries. The change moves the filenames needed for linking; it does not remove all native-library information from crate metadata.
Putting the field in a new file would not help much if the early metadata loader immediately read it back. Review asked for the field to leave that loader entirely. The linking code reads it when needed. The filename list follows the order of the native-library list, because a library name alone is not a reliable key.
Those decisions are visible in the reviews of when to read the data and how to identify each library.
A cache with a small lifetime
The same library can be inspected more than once during linking. Reading and decoding its link-time metadata each time repeats work. RmetaLinkCache keeps the decoded result, keyed by the rlib path, for that link operation.
It is not a persistent build cache shared by future builds. That short lifetime matters: a later build must read its own inputs. The cache became a separate pull request while the filename move was under review.
How far down it went
The work sits in the compiler backend and the archive format, not in language features: the archive writer and reader in rustc_codegen_ssa, the LTO readers of the LLVM and GCC backends, native library handling in rustc_metadata, and how the member is found in different object file formats.
The changes
#154861 · Add rlib digest to identify Rust object files
Merged May 5, 2026Adds the lib.rmeta-link archive member, which lists the members that are Rust object files. The LTO readers of the LLVM and GCC backends read it instead of looking at file names, and the filename heuristic is deleted. The member sits right after lib.rmeta.
#156735 · Move NativeLib::filename to the rmeta-link archive member
Merged July 11, 2026The filename of a bundled native library is only needed at link time, so it left the crate metadata. The member stores the filenames as a list aligned by position with the crate's native libraries, and only the linking code reads them.
#158194 · RmetaLinkCache
Merged June 28, 2026A cache for one link, keyed by rlib path, so each lib.rmeta-link member is decoded at most once. It was split out of the review of the previous change after a performance run regressed.
#159571 · Remove unused bundled library lookup for the local crate
Merged July 20, 2026After the move, one branch computed bundled library filenames for the local crate that nothing read. Cleanup only, no change in behavior.
#161698 · Fix rmeta-link metadata not being read on AIX
Merged October 17, 2026Passes the existing AIX target flag to the shared reader, so it uses the XCOFF metadata reader on the paths that need it. The change merged, but I did not run it on AIX hardware and the PR reported no AIX CI runner.
What review changed
The pull request descriptions describe the first versions. The merged code is different, and the differences are the interesting part.
- No fallback for old rlibs. The first version kept the filename check for rlibs without the new member. The reviewers pointed out that an rlib only works with the compiler version that wrote it, so every rlib a new compiler reads has the member. The heuristic was deleted.
- Right after the crate metadata, not at the end. The issue proposed writing the member last. In review it moved next to
lib.rmeta. - Read only by the linking code. My first version of the native library change decoded the filenames through the metadata loader and patched them back. Review asked for the opposite: remove the field and read the member only during linking.
- Position, not name, as the key. A library name is not a reliable key, so the filenames are stored in the same order as the crate's native libraries.
- No metadata format version bump. I proposed one, and review showed the change did not need it.
- A performance regression. A benchmark run regressed on a large workspace. The read is now skipped for crates without bundled libraries, and the cache became its own pull request.
Where the change went next
Once the member existed, other work started to use it. bjorn3 added global assembly objects to the list (#157051). Vadim Petrochenkov gave archive entries an explicit kind (#157263), which later work on hiding internal symbols in static libraries relies on, and moved native library search out of rustc_metadata (#160272), noting that the tracking issue was now partially implemented.
The AIX follow-up merged on October 17, 2026. AIX uses the XCOFF object format. An archive member is a file inside the archive; a section is a region inside that file. Finding the right archive member is only the first step. The reader also has to find the metadata inside it in the way that format expects.
The merged fix passes the existing is_like_aix target flag through the shared reader and the LTO paths. This reuses information the compiler already knows. It also removes a separate AIX path that had duplicated part of the reading logic. The review and merged diff show that choice.
I did not test the change on AIX hardware. The pull request reported that its CI had no AIX runner. A merged change and a successful run on that target are different pieces of information, so I keep that limit explicit.
Review
The first change went through several review cycles with Vadim Petrochenkov and bjorn3 before it merged. The later changes were reviewed by Vadim Petrochenkov. The evidence for everything on this page is in the pull requests and their review threads.
What this work establishes
Five changes merged: an explicit object list, link-only filenames, a per-link cache, a cleanup of unused work, and the AIX reader follow-up. The tracking issue covers a wider design; these changes do not complete every item in it.
I do not claim a general build-time speedup from moving a field. Review included performance regressions and changes to avoid repeated work. Any performance claim needs its benchmark, compiler revisions, workload, and measurement conditions beside it.
The useful design lesson is concrete: record a fact where it is known, read it where it is needed, and check every reader when the format changes. That applies to an rlib, a generated file, or an application cache.