How to use the xPack QEMU RISC-V

This page is intended for those who plan to use the xPack QEMU RISC-V binaries in their workflows.

Versioning

The version string used by the upstream QEMU RISC-V project is a three number string like 8.2.6-1; 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 8.2.6-1. When published as a npm package, the version gets a fifth number, like 8.2.6-1.1.

Since adherence of third party packages to SemVer is not guaranteed, it is recommended to avoid referring to the xPack QEMU RISC-V dependency via a SemVer expressions like ^8.2.6-1 or ~8.2.6-1, and prefer exact matches, like 8.2.6-1.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.

Using qemu-riscv in testing

TODO