Developer Build and Test Instructions

Switching XRT development work from P4 to Git can be done without much downtime provided you use a few scripts we have created:

  • build.sh build script that builds XRT for both Debug and Release profiles.

  • run.sh loader script that sets up environment assuming XRT was built with build.sh.

Building XRT

Building XRT is tested on Ubuntu 20.04/22.04, CentOs 7.9+ and RHEL9 host OS.

It is probably safest if you keep your Git clone of XRT on a network mounted drive that can be accessed from different hosts. One advantage is that you can have your editor run on a host that is not used for board testing, since you don’t really want host/driver crashes to leave your unsaved edits in limbo.

git clone https://github.com/Xilinx/XRT.git
cd XRT/build
./build.sh

build.sh script builds for both Debug and Release profiles. It is necessary to use the build script if you intend to use the loader script run.sh and the board testing script board.sh.

For the normal development flow, it is not necessary to build RPM or DEB packages. The loader and test scripts both work by setting the environment to point at the binaries created by the build script.

Running XRT

To run your locally built XRT with a sample host.exe and kernel.xclbin, simply prepend your command line invocation with XRT/build/run.sh

<path>/XRT/build/run.sh ./host.exe kernel.xclbin

By default the run.sh script uses the binaries from the Release profile. In order run with the binaries from Debug profile use -dbg flag; this way you can even start your favorite debugger by prefixing its invocation with run.sh -dbg

<path>/XRT/build/run.sh -dbg emacs

Testing XRT

After making changes to XRT in your Git clone, rebuild with build.sh as explained above, then run a full set of pre-harvested board tests using the board.sh script.

The script is not supported, and the havesting part of the script no longer works. Assuming tests are harvested manually, then a bit of reverse engineering is needed to figure out how to organize these tests such that they can be run with board.sh.

Assuming all is well, the the board script will run all tests that organized under current directory.

While tests run, a file named results.all will list the test with PASS/FAIL keyword. This file is appended (not removed between runs). A complete run should take 5-10 mins for approximately 70 tests.

Unit Testing XRT

We use GTest to do unit testing. The GTest package is installed by running XRT/src/runtime_src/tools/scripts/xrtdeps.sh.

The GTest package on CentOS/RHEL 7.5 provides the GTest libraries here:

  • /usr/lib64/libgtest.so

  • /usr/lib64/libgtest_main.so

In recent versions of Ubuntu, the GTest libgtest-dev package provides the compiled libraries in

  • /usr/lib/x86_64-linux-gnu/libgtest.a

  • /usr/lib/x86_64-linux-gnu/libgtest_main.a

However, the GTest package on Ubuntu up to 18.04 provides source only! So, to use GTest on older Ubuntu versions, use:

cd /usr/src/gtest
sudo cmake CMakeLists.txt
sudo make
cd /usr/lib
sudo ln -s /usr/src/gtest/libgtest.a
sudo ln -s /usr/src/gtest/libgtest_main.a
# Validate:
ls *gtest*

This will add GTest static library symbolic links here:

  • /usr/lib/libgtest.a

  • /usr/lib/libgtest_main.a

CMake will handle linking, finding etc. for you.

To add GTest support to a CMakeLists.txt use the following, and this is using an example executable called xclbintest:

find_package(GTest)
if (GTEST_FOUND)
  enable_testing()
  message (STATUS "GTest include dirs: '${GTEST_INCLUDE_DIRS}'")
  include_directories(${GTEST_INCLUDE_DIRS})
  add_executable(xclbintest unittests/main.cpp unittests/test.cpp)
  message (STATUS "GTest libraries: '${GTEST_BOTH_LIBRARIES}'")
  target_link_libraries(xclbintest ${GTEST_BOTH_LIBRARIES} pthread)
else()
  message (STATUS "GTest was not found, skipping generation of test executables")
endif()