How to Run a Vivado FPGA Build

Goal: Run synthesis, implementation, and bitstream generation for an existing ruckus-based Vivado project.

Prerequisites

Before running a build, ensure you have:

Linux operating system
Licensed Vivado installation (version ≥ 2018.3 recommended)
A ruckus-based project with a Makefile, ruckus.tcl, and images/ directory
PRJ_PART set in the project Makefile (FPGA part number, e.g., xcku15p-ffva1760-2-e)
Build directory at $(TOP_DIR)/build/ (see Step 1)

Steps

Step 1: Create the build directory (one-time setup)

The Vivado build pipeline writes all intermediate files to $(TOP_DIR)/build/. Create this directory before running any build target. A symlink to a fast scratch location works equally well:

mkdir $(TOP_DIR)/build
# or symlink a fast scratch location:
ln -s /scratch/build $(TOP_DIR)/build

Note

TOP_DIR defaults to $(abspath $(PROJ_DIR)/../..), which is two directories above your project directory. This is the root of your firmware repository.

Step 2: Set the FPGA part number

If PRJ_PART is not already defined in your project Makefile, add it before the include line:

ifndef PRJ_PART
export PRJ_PART = xcku15p-ffva1760-2-e
endif

include $(TOP_DIR)/submodules/ruckus/system_vivado.mk

Note

PROJECT is auto-detected from the directory name ($(notdir $(PWD))). You do not need to set it unless you want a different project name.

Step 3: Run the full build

make bit

make bit, make mcs, and make pdi all invoke the same build rule. Use whichever matches your desired output format. The generated artifacts are placed in images/ with the naming pattern:

PROJECT-VERSION-TIME-USER-GITHASH.bit
PROJECT-VERSION-TIME-USER-GITHASH.mcs
PROJECT-VERSION-TIME-USER-GITHASH.pdi   (Versal only)

Step 4: Open the project in the Vivado GUI (optional)

After a build completes, open the project to inspect timing, utilization, and log reports:

make gui

Available Targets

Target	Action
`make bit`	Full synthesis + implementation + `.bit` bitstream
`make mcs`	Full synthesis + implementation + `.mcs` flash image
`make pdi`	Full synthesis + implementation + `.pdi` (Versal devices)
`make syn`	Synthesis only (sets `SYNTH_ONLY=1`)
`make dcp`	Synthesis to DCP checkpoint (sets `SYNTH_DCP=1`)
`make gui`	Open existing project in Vivado GUI
`make sources`	Source setup only (creates `.xpr`); no build
`make interactive`	Open Vivado in TCL interactive mode
`make xsim`	Vivado XSIM simulation
`make vcs`	Generate VCS simulation scripts
`make msim`	ModelSim/Questa simulation
`make batch`	Vivado batch mode within existing project
`make release`	Tag and push firmware release to GitHub
`make release_files`	Generate release files without GitHub push
`make clean`	Delete `build/$(PROJECT)` directory

Key Variables

Variable	Default	Description
`PRJ_PART`	(none)	FPGA part number. Must be set by user.
`PROJECT`	`$(notdir $(PWD))`	Project name; auto-detected from directory.
`TOP_DIR`	`$(abspath $(PROJ_DIR)/../..)`	Firmware repository root.
`GEN_BIT_IMAGE`	`1`	Generate `.bit` file (set to `0` to skip).
`GEN_MCS_IMAGE`	`1`	Generate `.mcs` flash image (set to `0` to skip).
`GEN_PDI_IMAGE`	`1`	Generate `.pdi` file for Versal (set to `0` to skip).

See the Makefile Reference for the complete variable reference including timing override and git bypass variables.

Troubleshooting

“Build directory missing!” error

Create $(TOP_DIR)/build/ or symlink it to a scratch location:

mkdir $(TOP_DIR)/build

“PRJ_PART is not set” error

Add export PRJ_PART = <your-part> to your project Makefile before the include line (see Step 2).

Timing violations fail the build

See the timing override variables (TIG, TIG_SETUP, TIG_HOLD) in the Makefile Reference.

Vivado not found

Ensure Vivado is on your PATH. Source the settings script if needed:

source /path/to/Vivado/2023.1/settings64.sh