Project:LLVM/Ebuild Guide

This document provides a complete guide on how to write ebuilds on LLVM reverse dependencies, how to depend on LLVM and how to use llvm.eclass. It aims to cover all the facts on a single page, in a clear, explanatory way. Examples included.

Basic dependency notes

The sys-devel/llvm and sys-devel/clang packages provide both sets of shared libraries for program use, and an executable toolchain. The slot/subslot is used to indicate the library ABI version (which needs to match between LLVM and clang), and the multilib ABI flags are used to indicate which multilib libraries are installed. The toolchain unconditionally supports all ABIs for the target.

Simply put:

if you link to LLVM (clang) libraries, you need to use the := slot operator in the LLVM (clang) dependency. If your package is multilib, you also need to use [${MULTILIB_USEDEP}];
if you just use the tooling, you need to use the :* slot operator, and no multilib deps.

LLVM versions below 4 used to integrate the clang compiler under USE=clang. This is no longer the case, and all past versions were accustomed with sys-devel/clang metapackage. If you need clang, you need to depend on that package instead.

If your tool requires specific LLVM targets other than the native one, it should list those targets in USE dependency using the LLVM_TARGETS flags. Those flags are supported since LLVM 3.9. If your package requires older version of LLVM, you can depend on USE=multitarget instead. However, please do not depend on this flag in new packages since it was removed in version 4.

Depending on slotted LLVM versions

LLVM is slotted per ABI since version 4, and this means there a few pitfalls regarding dependencies on LLVM. Most notably, you can not combine lower- and upper-bound version operators without specifying a specific slot (otherwise, the PM might install two slots instead of one).

The following examples provide for the most common cases:

CODE Example LLVM dependencies

# supports any LLVM version starting with 3.8 including the current git (9999), links to libraries
>=sys-devel/llvm-3.8:=

# supports any LLVM version starting with 3.8 including the current git (9999), uses tools only
>=sys-devel/llvm-3.8:*

# supports LLVM 3.8 through 4, links to libraries
|| (
  sys-devel/llvm:4  # each supported slot must be listed explicitly
  >=sys-devel/llvm-3.8:0
)
<sys-devel/llvm-5:=  # note: this '''must''' upper-bound newest supported version

# supports LLVM 3.8 through 4, uses tools only
|| (
  sys-devel/llvm:4  # each supported slot must be listed explicitly
  >=sys-devel/llvm-3.8:0
)

# supports only LLVM 4
sys-devel/llvm:4

# == Cases for obsolete versions ==
# supports LLVM 3.7 through 3.9 [last :0], links to libraries
>=sys-devel/llvm-3.7:0=

# supports LLVM 3.7 and 3.8, links to libraries
<sys-devel/llvm-3.9:0=
>=sys-devel/llvm-3.7:0

# supports only LLVM 3.8
=sys-devel/llvm-3.8*

Which boils down to the following rules:

If a plain >=/< dependency spans multiple LLVM slots, it can be only either upper- or lower-bound, not both.
If both upper/lower bound is needed that spans multiple slots, all matching slots need to specified in ||, in order.
- The := slot operator must not be used inside ||, so it needs to be repeated below the block, with upper bound of it. In this case, the slots need to be consecutive. The || dependency will ensure that at least one LLVM version in the range is installed, while the := dependency following it will bind to the highest version in that range.
Versions preceding 4 are all in slot :0, so >=/< operators can be used normally as long as you ensure to specify slot :0 explicitly.

Using llvm.eclass

The llvm.eclass provides routines to enforce upper bound version of LLVM on the reverse dependency. It therefore needs to be used only if your package does not support the newest (9999) LLVM version. However, you can also use it if that is not the case.

The eclass expects a single control variable LLVM_MAX_SLOT, and provides a simple pkg_setup() phase. LLVM_MAX_SLOT needs to be set to the highest supported LLVM slot (or unset if there is no limit, i.e. 9999 is supported). According to that, the pkg_setup phase will prepend the appropriate LLVM installation prefix to the PATH. This will ensure that most of the build systems will either find the correct llvm-config executable, or CMake modules (CMake searches for them relative to PATH directories).

The eclass does not set dependencies. You need to specify them yourself.

CODE Example use of llvm.eclass

inherit llvm

# ...

# We support LLVM 3.8 through 4.
RDEPEND="
  || (
    sys-devel/llvm:4
    >=sys-devel/llvm-3.8:0
  )
  <sys-devel/llvm:5="
DEPEND=${RDEPEND}

LLVM_MAX_SLOT=4

# if you need to redefine it...
pkg_setup() {
  do_foo
  llvm_pkg_setup
}

Using get_llvm_prefix()

Should you want to use the function get_llvm_prefix() directly, e.g. to install a LLVM-slot-specific package, keep in mind that this function does NOT honour the value of LLVM_MAX_SLOT so you might receive the prefix to a newer version of LLVM than you expected. In order to prevent this from happening explicitly pass the maximum slot as the first argument of get_llvm_prefix(), e.g.

CODE Limiting LLVM slots considered by get_llvm_prefix()

inherit llvm

LLVM_MAX_SLOT=4

# ...

  local llvm_prefix="$(get_llvm_prefix ${LLVM_MAX_SLOT})"