Building from Source
Note
This guide is for developers contributing to or extending TAPA, or advanced users building TAPA from source for custom OS support. For FPGA accelerator development with TAPA, refer to the User Documentation.
Tip
If your OS isn’t officially supported and you’re not a developer, consider using a virtual machine or file a feature request on GitHub.
System Prerequisites
To build TAPA from source, you need:
Bazel 7.3.2 or later
Binutils 2.30 or later
Libstdc++ matching the most recent GCC version installed on your system
Python 3.6 or later
Install these tools using your OS package manager. For Ubuntu:
# Install bazel
sudo apt-get install apt-transport-https ca-certificates gnupg
curl -fsSL https://bazel.build/bazel-release.pub.gpg \
| gpg --dearmor | sudo tee /usr/share/keyrings/bazel-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/bazel-archive-keyring.gpg] \
https://storage.googleapis.com/bazel-apt stable jdk1.8" \
| sudo tee /etc/apt/sources.list.d/bazel.list
sudo apt-get install bazel
# Install other tools
sudo apt-get install binutils git python3
Tip
For Bazel installation on other OS, see the Bazel documentation.
Note
The Dockerfile in the TAPA repository provides a complete build environment. Use it for containerized builds or run the Ubuntu commands to install required tools.
Clone the Repository
To get started with building TAPA from source, you’ll need to clone the repository from GitHub:
git clone https://github.com/rapidstream-org/rapidstream-tapa.git
If you are contributing to TAPA, fork the repository and clone your fork instead. When you’re ready to contribute, create a new branch for your changes, commit your work, and open a pull request to contribute your changes back to the main repository.
Build TAPA from Source
To build TAPA, navigate to the root directory of the cloned repository and execute the following command:
bazel build //...
This command compiles all TAPA targets, including the compiler, runtime library, and tests.
For building a specific target, replace //...
with the desired target
name. For instance, to build only the TAPA compiler:
bazel build //tapa
Note
To view all available targets, run bazel query //...
.
To skip building for the tests, you could use:
bazel build //... -- -//tests/...
After the build process completes, you can find the compiled binaries in the
bazel-bin
directory. For example, the TAPA compiler binary is located at
bazel-bin/tapa/tapa
.
Note
The build process duration may vary depending on your system’s performance. LLVM, a significant dependency used by TAPA for code generation, requires considerable time to build. Bazel will cache it after the initial build.
Use the Built TAPA
Important
Remember to source the Vivado settings script before running the TAPA compiler.
Once TAPA is built, you can use the compiled TAPA compiler to compile your designs. For example:
bazel-bin/tapa/tapa compile \
-f tests/apps/bandwidth/bandwidth.cpp \
--cflags -Itests/apps/bandwidth/ \
-t Bandwidth \
--clock-period 3 \
--part-num xcu250-figd2104-2L-e
Remember to rerun the bazel build
command whenever you make changes to the
TAPA compiler or runtime library to ensure you’re using the latest version.
Run TAPA Tests
To run all TAPA tests, including unit tests and integration tests, use the following command in the repository’s root directory:
bazel test //...
For running a specific test, replace //...
with the test name. For example,
to test only a specific app:
bazel test //tests/apps/vadd:vadd-xosim
Build Binary Distribution
To create a binary distribution of TAPA, navigate to the root directory of the cloned repository and execute the following command:
bazel build --config=release //:tapa-pkg-tar
Find the generated binary distribution in the bazel-bin
directory,
as a tarball named tapa-pkg-tar.tar
.
Install the Binary Distribution
To install the binary distribution, extract the tarball to a directory of your choice:
tar -xvf bazel-bin/tapa-pkg-tar.tar -C /path/to/install
Access the TAPA compiler binary at /path/to/install/usr/bin/tapa
.
Containerized Build (Advanced)
For those who prefer a containerized build environment, TAPA offers a GitHub
Actions workflow that can be run locally using act
. This approach ensures
a consistent build environment across different systems.
Prerequisites
Install
act
by following the instructions in the act repository.Ensure Docker is installed on your system, as
act
requires it to run the workflow.
Note
RapidStream organization developers using RapidStream servers can skip the configuration steps below, as the necessary setup is already in place.
Configuration
Before running act
, set up the following configuration files:
Create a
.secrets
file in the repository root with the following content:UBUNTU_PRO_TOKEN=[YOUR_UBUNTU_PRO_TOKEN] MAC_ADDRESS=de:ed:be:ef:ca:fe
Replace
[YOUR_UBUNTU_PRO_TOKEN]
with your Ubuntu Pro token (available free for personal use) andde:ed:be:ef:ca:fe
with your Vivado license MAC address.Update the
.actrc
file in the repository root:--secret-file .secrets
If your Vivado license and installation locations differ from the defaults (
/share/software/licenses/xilinx-ci.lic
and/share/software/tools
respectively), update.github/actions/run-docker/action.yml
accordingly.
Note
Developers from the RapidStream organization can start from here.
Running Containerized Tests
To test TAPA in the containerized environment:
act -j test
This method often provides more consistent results than local testing due to the isolated environment. It also benefits from a shared Bazel cache between runs, potentially speeding up the build process.
Note
Build artifacts are not saved to the local bazel-bin
directory in
containerized builds. For debugging, you may need to build TAPA in your
local environment. However, you can still add test cases and use act
for testing your changes.
Creating a Binary Distribution
To create a binary distribution of TAPA:
act -j build
The resulting binary distribution is saved in the artifacts.out
directory
in the repository root (e.g., artifacts.out/1/tapa/tapa.tar.gz
for the
first build).
Installing the Binary Distribution
To install the binary distribution:
Extract the tarball to your preferred directory, or
Use the provided
install.sh
script to install TAPA to the default location:RAPIDSTREAM_LOCAL_PACKAGE=./artifacts.out/1/tapa/tapa.tar.gz ./install.sh