How to use xPack Ninja Build
This page is intended for those who plan to integrate xPack Ninja Build into their workflows.
Versioning
The version string utilised by the
upstream Ninja Build project
is a three-number string
such as 1.13.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,
such as 1.13.1-1
. When
published as an npm package, the version receives
a fifth number,
such as 1.13.1-1.1
.
Since adherence of third-party packages to SemVer is not guaranteed,
it is recommended to avoid referencing the xPack Ninja Build dependency via
SemVer expressions
such as ^1.13.1-1
or ~1.13.1-1
, and
prefer exact matches,
such as 1.13.1-1.1
.
Shared libraries
On all platforms the binary xpm packages are standalone, and require only the standard runtime to be present on the host.
All dependencies that are built as shared libraries are copied locally
to the libexec
folder (or to the same folder as the executable for Windows).
DT_RPATH
and LD_LIBRARY_PATH
On GNU/Linux the binaries are adjusted to utilise 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 the latter
is set in the environment, it should not interfere with the xPack binaries.
Please note that previous versions, up to mid-2020, utilised 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 utilise a relative path.
Using ninja-build in testing
TODO