Project:Quality Assurance/Handling Libtool Archives

From Gentoo Wiki
Jump to: navigation, search

Libtool is a GNU project to build libraries in a portable system-independent way. It closely ties into the rest of the GNU Autotools system, but can be used outside GNU Autoconf and Automake as well. Libtool's goal is to produce two types of final products:

  1. static libraries, which usually have a .a suffix on GNU/Linux
  2. dynamic libraries, which usually have a .so suffix on GNU/Linux

Static libraries were the first kind of libraries on UNIX and UNIX-like systems. They are usually just archives of compiled object files. When linking to a static library, this is just as if you were to include more .o files into the final product.

A significant disadvantage of static libraries is that they cannot, by the very nature of the archive they sit in, encode their required dependencies. GNU Libtool has devised a way of encoding all these dependencies. By writing all dependencies into a text file known as a Libtool Archive (.la extension), this information is stored and can be used when linking statically to such a library.

On the other hand, modern dynamic libraries on GNU/Linux encode their dependencies in their ELF header, thus obviating the use of Libtool archives.

Historically, Gentoo has had multiple difficulties with Libtool archives in the past. See a nice documentation of how Libtool archives lead to massive unnecessary rebuilds: https://flameeyes.blog/2011/08/library-soname-bumps-and-la-files-some-visual-clues It boils down to a number of interactions that make Libtool archives problematic on Gentoo:

  1. Libtool pulls in all direct and indirect dependencies into the .la files it creates. This leads to massive overlinking, which is toxic to the Gentoo ecosystem, as it leads to a massive number of unnecessary rebuilds.
  2. Furthermore, the previous overlinking cannot be prevented by any LDFLAGS wizardry, as useful flags such as -Wl,--as-needed become active only during invocation of ld.

Tackling .la files

The only way to avoid such problems is to delete the libtool archives. In 95% of cases, deleting the libtool archives can be done safely. In fact, there exists only one case in which .la files should not be deleted: If lib/foo installs

  1. a static library that
  2. has private dependencies (i.e. depends on other libraries) and
  3. does not use pkg-config .pc files to document these dependencies

In all other cases, .la can usually be safely deleted. See the flowchart created by Diego Elio Pettenò (aka flameeyes) documenting this in a more graphically intuitive way:

La-removal-flowchart.png

The canonical way of deleting .la files

If you're sure you can delete any generated .la files, the recommended way goes along the lines of

CODE Snippet for removing .la files
src_install() {
	default
	find "${D}" -name '*.la' -delete || die
}

Whether you use ${D} or ${ED} makes little difference in practice, as for instance in the case of Gentoo Prefix, the ${EPREFIX} tree will be fully contained in ${D}, and will be walked by find in the former case. The above find command is fully portable with EAPI=5 and later, as find is guaranteed to be the GNU variant.