.. comment:: SPDX-License-Identifier: Apache-2.0 comment:: Copyright (C) 2019-2022 Xilinx, Inc. All rights reserved. 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 ~~~~~~~~~~~~ Make sure you build XRT on a Centos7.4+ or Ubuntu16.04 or Ubuntu18.04 host. 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`` :: /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`` :: /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()