Developing TAPA

Development Environment

TAPA enforces a consistent coding style and provides tools to ensure code quality. Follow these steps to set up your development environment.

Install Pre-Commit Hooks

pre-commit --version
pre-commit install

Install pre-commit with your OS package manager if the command is not available. Pre-commit hooks run automatically before each commit to ensure code compliance with style guidelines. To manually run the checks:

pre-commit run --all-files

Code Structure

The TAPA codebase is organized into several key directories:

• bazel/: Contains Bazel build configurations.

  It defines how the TAPA compiler is used in the Bazel build system, and provides additional utilities for building and testing TAPA.

• docs/: Includes documentation files.

  The documentation is written in Markdown and built using mdBook.

• fpga-runtime/: Provides the FPGA runtime library.

  The FPGA runtime library is used to interact with simulator or FPGA based on provided bitstream. It uses fast lightweight simulator for cosimulation with XO object file, and interacts with XRT library for Vitis simulation or on-board testing with XCLBIN file.

• tapa-lib/: Houses the TAPA runtime library.

  The TAPA runtime library provides core functionality for TAPA tasks, streams, and memory maps. It implements platform-specific features (e.g., software simulation queues, hardware FIFOs).

• tapa-llvm-project/: Contains the LLVM project with TAPA-specific patches (fetched as an external Bazel dependency, not checked in to the repository).

  TAPA uses LLVM Clang to generate system interconnect and transformed C++ code for each task. The LLVM project is customized with TAPA-specific features, such as C++ annotations.

• tapa-system-include/: Creates a custom system include directory for TAPA.

  This Bazel build target collects system include files for the tapacc compiler. It includes standard C++ headers, TAPA dependencies, and TAPA-specific headers for the compiler to run on every OS.

• tapa-core/: Contains the supported Rust TAPA compiler implementation.

  The TAPA compiler serves as the entry point for the TAPA framework. It invokes the tapacc compiler, synthesizes tasks into RTL using HLS tools, and generates system interconnect and XO object file for FPGA. For the xilinx-hls target, a .zip RTL archive is generated instead. The Bazel //tapa-core:tapa target provides the command wrapper and tapa-core/tapa-codegen/assets contains shared Verilog templates.

• tapacc/: Implements the TAPA C++ compiler to translate TAPA tasks to JSON.

  The TAPA C++ compiler is a Clang-based compiler for TAPA tasks. It parses every translation unit in one process, merges the task graph, writes the rewritten source tree that synthesis compiles, and emits the JSON representation of tasks and dataflow.

• tests/: Includes test cases for the TAPA compiler and runtime library.

  The folder includes various TAPA applications. It includes microbenchmarks under apps/ for basic functionality testing, and regression/ for performance evaluation of TAPA compiled designs.

Test Coverage

Line coverage of the Rust workspaces is measured with cargo-llvm-cov:

cd tapa-core && cargo llvm-cov --locked --workspace
cd fpga-runtime && cargo llvm-cov --locked --workspace -- --skip open_cosim_verilator

The open_cosim_verilator end-to-end tests are skipped because they need the libfrt_dpi_verilator shared library that only the Bazel runfiles tree stages; run them through bazel test //fpga-runtime:cargo_test.

Baseline (2026-08-08, report-only — informational, not a CI gate):

What is uncovered is mostly what cannot run here: the SSH/remote transport needs a remote host, and the XRT and FFI paths need a board. Treat the totals as a trend rather than a target — raising them means either hardware in the loop or seams that let those paths be driven from a test.

Update Dependencies

TAPA depends on several external libraries and tools. This section explains how to update these dependencies.

General Version Bump Process

When bumping versions, follow this general workflow:

1. Clear existing lock files.

2. Update dependency declarations.

3. Regenerate lock files.

4. Test the build.

5. Commit changes.

Bazel Dependencies

For Bazel dependencies:

1. Update the version numbers in MODULE.bazel.

2. Check the Bazel Central Registry for latest versions, and update the bazel_dep entries in MODULE.bazel accordingly.

3. Remove MODULE.bazel.lock to force regeneration.

LLVM Version Updates

To update the LLVM version:

1. Find the latest stable release of LLVM on LLVM GitHub releases.

2. Update the version numbers in MODULE.bazel:

   LLVM_VERSION_MAJOR = 20
   LLVM_VERSION_MINOR = 1
   LLVM_VERSION_PATCH = 4
   

3. Update the SHA256 checksum after downloading the new version:

   LLVM_SHA256 = "<new_sha256_checksum>"
   

Docker Images

For the Docker testing and building environments:

1. Update the base image versions in .github/docker/*.

2. Update the system dependencies trigger date to the current date, so that the Docker image is rebuilt with the latest system dependencies:

   RUN apt-get update && \
       # Update the following line to the latest date for retriggering the docker build
       echo "Installing system dependencies as of 20250505" && \
       apt-get upgrade -y
   

Pre-commit Hooks

Update pre-commit hooks to the latest versions:

pre-commit autoupdate

Verifying Updates

After updating dependencies:

1. Remove the lock file: rm MODULE.bazel.lock

2. Run a full build: bazel build //...

3. Run the pre-commit checks: pre-commit run --all-files

4. Commit the changes: git commit -a -m "build(deps): bump versions"