Skip to main content

How to use the xPack LLVM clang

This page is intended for those who plan to use the xPack LLVM clang binaries in their workflows.

Versioning​

The version string used by the upstream LLVM clang project is a three number string like 18.1.8-2; to this string the xPack distribution adds a fourth number, but since SemVer allows only three numbers, all additional ones can be added only as pre-release strings, separated by a dash, like 18.1.8-2. When published as a npm package, the version gets a fifth number, like 18.1.8-2.1.

Since adherence of third party packages to SemVer is not guaranteed, it is recommended to avoid referring to the xPack LLVM clang dependency via a SemVer expressions like ^18.1.8-2 or ~18.1.8-2, and prefer exact matches, like 18.1.8-2.1.

Shared libraries​

On all platforms the binary xPack packages are standalone, and expect only the standard runtime to be present on the host.

All dependencies that are built as shared libraries are copied locally in the libexec folder (or in the same folder as the executable for Windows).

DT_RPATH and LD_LIBRARY_PATH​

On GNU/Linux the binaries are adjusted to use a relative path:

$ readelf -d library.so | grep rpath
 0x000000000000001d (RPATH)            Library rpath: [$ORIGIN]

In the GNU ld.so search strategy, the DT_RPATH has the highest priority, higher than LD_LIBRARY_PATH, so if this latter one is set in the environment, it should not interfere with the xPack binaries.

Please note that previous versions, up to mid-2020, used DT_RUNPATH, which has a priority lower than LD_LIBRARY_PATH; setting LD_LIBRARY_PATH in the environment overrode DT_RUNPATH, resulting in failures to load the libraries.

@rpath and @loader_path​

Similarly, on macOS, the binaries are adjusted with install_name_tool (part of CLT) to use a relative path.

Miscellaneous​

LLVM libraries​

On macOS and Windows the compiler defaults are set to the LLVM libraries (libc++ and compiler-rt).

For historical reasons, on GNU/Linux, the defaults are set to the host system (libstdc++ and glibc).

To use the LLVM libraries, add the following options:

-stdlib=libc++ -rtlib=compiler-rt -lunwind

For LTO builds, also use LLD:

-flto -fuse-ld=lld

-m32 / -m64​

For Intel Linux and Windows, multilib libraries are provided and can be selected using the -m32 / -m64 options.

-print-search-dirs​

Since the toolchain can be installed in any location, and the binaries compiled with it need to access the libraries, it is necessary to get the actual path and pass it via LD_LIBRARY_PATH and/or set the -rpath.

This can be achieved by querying the compiler for -print-search-dirs and processing the output.

For example, for the 32-bit libraries:

${CXX} -m32 -print-search-dirs | grep 'libraries: =' | sed -e 's|libraries: =||'

On Windows the DLLs are usually in bin, but for consistency within GCC, they are also copied to lib; it is recommended to ask the compiler for the actual path.

For example, for the 32-bit libraries:

${CXX} -m32 -print-file-name=libc++.dll

Using clang in testing​

TODO