From Gentoo Wiki
Jump to:navigation Jump to:search

Link Time Optimization or more commonly referred to as LTO is optimizations done during linking. Linker is aware of all the compilation units and can optimize more compared to what conventional compiler can do. The most important optimizations that linker does are inlining and code locality improvements. This can increase system performance at the cost of longer compile time.

This article will show the user how to enable LTO without the need for third party overlays and using recommended tested CFLAGS for the best performance and system stability using either GCC or LLVM stage3 systems.

Benefits of LTO

  • LTO can give double digit performance boosts for many programs.
  • Can lower RAM usage per program making it very useful for limited memory systems.

Downsides of LTO

  • Can increase compile time by 2 to 3 times.
  • Uses more RAM during compiling.
  • Not all programs work better with LTO
  • There is an increased chance of finding compiling issue bugs while using it.

Enabling LTO System-wide

GCC Systems

Enable LTO

To enable LTO package building on GCC systems, edit /etc/portage/make.conf then add LTO to the USE line and -flto to the COMMON_FLAGS.

FILE /etc/portage/make.confmake.conf example
COMMON_FLAGS="-O2 -pipe -march=native -flto"

With this LTO is now enabled on the system for all future emerges.

LLVM Systems

Enable LTO

All that is needed is to -flto to COMMON_FLAGS and lto to USE:

FILE /etc/portage/make.confmake.conf example
COMMON_FLAGS="-O3 -pipe -march=native -flto"

Troubleshooting, Fixing and Reporting LTO Issues

While LTO works without issue for most users thanks to the hard work of everyone in the community in Gentoo and beyond, there is still some packages that a user may run across that have been missed. This section will show how to fix the issue for the their system and also report the issue (if needed) so it can be fixed for everyone in Gentoo to help make Gentoo better for everyone in the future.

Stable Systems

As of writing (2023-05-15) LTO fixes have mostly trickled down from Testing to Stable (i.e. ~amd64 to amd64) however there may be cases where this isn't the case so before reporting the user should try the latest version of the package in the Testing branch to see if it the issue is solved there to save themselves and the developers time and effort.

In this example app-editors/emacs is used to show however be aware this may already fixed at the time of reading, so should only be viewed as an example of the troubleshooting steps LTO users should follow.
root #emerge --ask app-editors/emacs

In this example on a stable amd64 system portage would compile version 28.2-r6. On the first sign of a compiling issue a user should check to see if there is a version in Testing which the user would find that there is a version 28.3_rc1-r2 available.

In this case the next step would be to accept the keyword for that version only so portage only uses the testing version until the stable package version catches up to the fix.

To only accept the keyword for one version then an = is required before the package type and then the version number after.

FILE /etc/portage/package.accept_keywords/emacsKeywording Example

Then try to emerge the updated version.

root #emerge --ask app-editors/emacs

If the package now compiles fine then no reporting is needed by the user, if however it still fails then continue to the next step.

Latest Version Issues

Existing Reports Procedure

The user should first check to see if there is already an open bug on the issue at, using the search tool looking up "emacs lto" would show a reported bug already as bug #854360.

The next step would be checking the reported version to the version tested on the system. If the version are the same then no action is needed however, if the tested version was newer then adding a comment that the problem still exists in the version testing should be added to help save time for the person working on the bug.

New Bugs Procedure

In the case of no bug being open after searching then opening a new report is one of the most helpful things a Gentoo user can do to help highlight issues. Do remember there is no shame if a mistake is made so there is no need for a user to feel nervous as you will be guided on what extra information is needed if required. A bad bug report is always preferred over a perfect report that never gets reported.

Information Required

A good title helps, for example "app-editors/emacs-28.3_rc1-r2 Fails to compile with LTO enabled"

A short description of the issue and what has been tried so far.

Steps to reproduce, preferably from a fresh stage3 install:

  1. Install stage3 <tarball name used>
  2. Enable lto in make.conf
  3. add app-editors/emacs-28.3_rc1-r2 to package.accept_keywords
  4. emerge -va app-editors/emacs

What happens after following this if the user knows.

Attach the build.log to the bug report from the location portage gives.

Add the output of emerge --info to a section comment.

This may sound confusing the first time however its very easy after the first time and can be fun to watch a reported bug get fixed in real time.

Disable LTO per Package

After reporting its still possible to fix the issue on the system until a fix is committed by disabling LTO using package.env.

Create nolto.conf

A package env config is a Portage feature that allows a user to set CFLAGS and other options on a per package basis.

Create /etc/portage/env/nolto.conf with the following:

FILE /etc/portage/env/nolto.confnolto.conf example
# Env setup to disable LTO for problem builds
CFLAGS="${CFLAGS} -fno-lto"
FCFLAGS="${FCFLAGS} -fno-lto"
FFLAGS="${FFLAGS} -fno-lto"

This is the options that Portage will use for packages set in the next step.

Create package.env/noltobuild

Still using emacs as the example, then /etc/portage/package.env/noltobuild would look like:

FILE /etc/portage/package.env/noltobuildnoltobuild config example
app-editors/emacs nolto.conf

Now compiling app-editors/emacs on the user's system would no longer build with LTO and the compiling issue found at the start would be fixed as a workaround until a permanent fix is found in Gentoo.

See Also