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