Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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. This is also the recommended way to install TAPA for all users.

Tip

If your OS isn't officially supported, 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
  • Git
  • Libstdc++ matching the most recent GCC version installed on your system
  • Python 3.13 or later (Bazel fetches its own managed toolchain; this version applies to the Bazel-managed Python, not necessarily the host system Python)
  • Other TAPA dependencies

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/tuna/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.

Modify the Build Configuration

You may need to modify the VARS.bzl file in the repository's root directory to specify the correct Vivado installation paths and versions. The build script currently assumes default installation paths at /opt/tools/xilinx/Vivado/2024.2 and /opt/tools/xilinx/Vivado/2022.2 for Vivado, and /opt/tools/xilinx/Vitis/2024.2 for Vitis.

If your Xilinx tools are installed in non-standard locations, please modify the XILINX_TOOL_PATH variable to reference the correct base installation directory for your Vivado and Vitis installations. You should also update XILINX_TOOL_VERSION to specify the version of the latest Xilinx tools you have installed. With these settings properly configured, the system will expect your Vivado installation to be located at {XILINX_TOOL_PATH}/Vivado/{XILINX_TOOL_VERSION}.

Furthermore, you should configure XILINX_TOOL_LEGACY_VERSION to indicate the earliest version of Xilinx tools installed on your system, along with XILINX_TOOL_LEGACY_PATH to point to the corresponding installation directory.

If your system does not have the Xilinx Runtime (XRT) installed, you can modify the HAS_XRT variable in the VARS.bzl file to False. This will prevent the tests to fail due to the absence of XRT.

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.

Build the Documentation

The documentation is written in Markdown and built with mdBook. The Bazel build rules fetch the correct mdBook and mdbook-admonish binaries automatically — no separate install is needed.

Build a static HTML site:

bazel build //docs:build

The output is a tarball at bazel-bin/docs/book.tar.gz. Extract it to browse the HTML locally.

Serve with live reload during editing:

bazel run //docs:serve

This starts a local server (default: http://localhost:3000) that reloads automatically when source files change. Supported on Linux x86_64, macOS x86_64, and macOS arm64.

Note

The documentation source lives under docs/src/. The Bazel targets handle mdbook-admonish preprocessing automatically; do not run mdbook-admonish install manually in the source tree.

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

  1. Install act by following the instructions in the act repository.

  2. Ensure Docker is installed on your system, as act requires it to run the workflow.

Configuration

Before running act, set up the following configuration files:

  1. 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) and de:ed:be:ef:ca:fe with your Vivado license MAC address.

  2. Update the .actrc file in the repository root:

    --secret-file .secrets

  3. 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.

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:

  1. Extract the tarball to your preferred directory, or

  2. Use the provided install.sh script to install TAPA to the default location:

    TAPA_LOCAL_PACKAGE=./artifacts.out/1/tapa/tapa.tar.gz ./install.sh