Optimizing Rust Builds for Smaller Binaries

Oct 13, 2025 by wbrum.org 16 views

Optimizing Rust Builds for Smaller Binaries

As Rust developers, we are always on the lookout for ways to optimize our builds and reduce the size of our binaries. In this article, we will explore a feature that can help achieve this goal, specifically the -Zbuild_std flag in Cargo.

Initial Configuration

Before we dive into the optimization, let's take a look at the initial configuration used in this example. The ~/.cargo/config.toml file contains the following settings:

[build]
rustflags="-C lto=true -C embed_bitcode=yes -Zdylib-lto -Zlocation-detail=none -C opt_level=z -C panic=abort -C codegen_units=1 -C strip=symbols -C target_cpu=native"

These settings enable various optimizations, including link-time optimization (LTO), embedding of bitcode, and stripping of symbols. However, as we will see, there is still room for improvement.

The `-Zbuild_std` Flag

The -Zbuild_std flag is a Cargo-specific flag that allows us to customize the standard library features used in our builds. By default, Cargo includes all standard library features, which can result in larger binaries. The -Zbuild_std flag enables us to selectively include or exclude features, reducing the size of our binaries.

Enabling Compiler-Builtins-Mangled-Names

The interesting part of the configuration is the addition of the -Zbuild_std-features=compiler-builtins-mangled-names flag. This flag enables the mangling of compiler-builtins, which are functions that are not used by the program but are still included in the binary. By mangling these functions, we can make them "removable" by the linker, resulting in a smaller binary.

Reducing Binary Size

To demonstrate the effectiveness of this optimization, let's consider the example of the starship project. By adding the -Zbuild_std-features=compiler-builtins-mangled-names flag to the build command, we can reduce the installation size of starship from 4,638KB to 4,501KB on our system.

cargo +nighlty build -Zbuild_std=std,panic-abort \
+  -Zbuild-std-features=compiler-builtins-mangled-names

How Does it Work?

So, how does this optimization work? The answer lies in the output of cargo bloat, a tool that analyzes the binary and identifies unnecessary code. By examining the output of cargo bloat, we can see that many useless core functions are included in the binary. The -Zbuild_std-features=compiler-builtins-mangled-names flag enables the mangling of these functions, making them removable by the linker and resulting in a smaller binary.

Conclusion

In conclusion, the -Zbuild_std flag is a powerful tool for optimizing Rust builds and reducing binary size. By selectively including or excluding standard library features, we can achieve significant reductions in binary size. In this article, we explored the use of the -Zbuild_std-features=compiler-builtins-mangled-names flag to mangle compiler-builtins, resulting in a smaller binary for the starship project. By applying this optimization, we can make our Rust builds more efficient and our binaries smaller.

Future Directions

As we continue to explore the possibilities of the -Zbuild_std flag, we may discover even more ways to optimize our builds and reduce binary size. Some potential areas for future investigation include:

Selective inclusion of standard library features: By selectively including only the features required by our program, we can reduce the size of our binaries even further.
Mangling of other unnecessary code: In addition to compiler-builtins, we may be able to mangle other types of unnecessary code, such as unused functions or variables.
Integration with other optimization techniques: By combining the -Zbuild_std flag with other optimization techniques, such as LTO or dead code elimination, we may be able to achieve even greater reductions in binary size.

References

Cargo documentation
Cargo bloat documentation
Rust documentation
Frequently Asked Questions about -Zbuild_std =====================================================

Q: What is the `-Zbuild_std` flag in Cargo?

A: The -Zbuild_std flag is a Cargo-specific flag that allows you to customize the standard library features used in your builds. By default, Cargo includes all standard library features, which can result in larger binaries.

Q: What is the purpose of the `-Zbuild_std-features` flag?

A: The -Zbuild_std-features flag enables you to selectively include or exclude standard library features from your builds. This can help reduce the size of your binaries by removing unnecessary code.

Q: How does the `-Zbuild_std-features=compiler-builtins-mangled-names` flag work?

A: The -Zbuild_std-features=compiler-builtins-mangled-names flag enables the mangling of compiler-builtins, which are functions that are not used by the program but are still included in the binary. By mangling these functions, you can make them "removable" by the linker, resulting in a smaller binary.

Q: What is the benefit of using the `-Zbuild_std-features=compiler-builtins-mangled-names` flag?

A: The benefit of using this flag is that it can help reduce the size of your binaries by removing unnecessary code. In the example of the starship project, this flag reduced the installation size from 4,638KB to 4,501KB.

Q: How do I use the `-Zbuild_std-features=compiler-builtins-mangled-names` flag in my Cargo build command?

A: To use this flag, you can add it to your Cargo build command like this:

cargo +nighlty build -Zbuild_std=std,panic-abort \
+  -Zbuild-std-features=compiler-builtins-mangled-names

Q: What are some potential areas for future investigation with the `-Zbuild_std` flag?

A: Some potential areas for future investigation include:

Selective inclusion of standard library features: By selectively including only the features required by your program, you can reduce the size of your binaries even further.
Mangling of other unnecessary code: In addition to compiler-builtins, you may be able to mangle other types of unnecessary code, such as unused functions or variables.
Integration with other optimization techniques: By combining the -Zbuild_std flag with other optimization techniques, such as LTO or dead code elimination, you may be able to achieve even greater reductions in binary size.

Q: Where can I learn more about the `-Zbuild_std` flag and its usage?

A: You can learn more about the -Zbuild_std flag and its usage by consulting the following resources:

Q: What are some potential risks or limitations of using the `-Zbuild_std` flag?

A: Some potential risks or limitations of using the -Zbuild_std flag include:

Incompatibility with certain libraries or dependencies: The -Zbuild_std flag may not be compatible with certain libraries or dependencies, which can result in build errors or other issues.
Reduced functionality or performance: By removing unnecessary code, you may also be removing functionality or performance-critical code, which can result in reduced performance or functionality.
Increased complexity: The -Zbuild_std flag can add complexity to your build process, which can make it more difficult to manage and maintain your codebase.