Project Manager

The Project Manager provides a centralized way to define FPGA build configurations using a single YAML file. This replaces the need to manually set Makefile flags or edit vendor-specific environment scripts.

Features

Centralized Configuration: All parameters (part number, project name, tool version, implementation directives) in one project.yml.
Make/TCL Integration: Automatically generates bridge files (build_env.mk and build_env.tcl) to propagate settings across tools.
Vendor Overrides: Supports vendor-specific implementation strategies (e.g., Vivado directives).
Block Design Support: Integrates with custom TCL scripts for generating block designs or Platform Designer systems.

Usage

Create a Project YAML: See project.yml.example in the root directory for a template.

Run Build with YAML:


make PROJECT_YML=my_project.yml project

Supported Targets: The PROJECT_YML variable is supported by all main build targets: project, synthesis, implementation, bitstream.

Architecture

The project_manager.py script parses the YAML and generates:

build_env.mk: Included by the root Makefile to set variables like PROJECT_NAME, VENDOR, and FPGA_PART.
build_env.tcl: Sourced by tcl/<vendor>/environment.tcl to set global TCL variables (g_project_name, g_fpga_part, etc.).

Schema Reference

Project Section

Field	Description	Type	Allowed Values / Options
`project.name`	Internal project name	string	variable
`project.top_module`	RTL Top module name	string	variable
`project.top_sim`	Simulation top name	string	variable

Hardware Section

Field	Description	Type	Allowed Values / Options
`hardware.vendor`	Target FPGA Vendor	string	`xilinx`, `altera`, `lattice`
`hardware.family`	FPGA Family	string	variable
`hardware.part`	FPGA Part Number	string	variable (e.g., `xc7z020clg400-1`)
`hardware.platform`	Logical board platform	string	`default`, `xem7305`, `veripro` (used for system config)

Build Options Section

Field	Description	Type	Allowed Values / Options
`build_options.tool_version`	Default tool version	string	variable (e.g., `2024.1`)
`build_options.vivado_version`	Vivado-specific version	string	variable
`build_options.radiant_version`	Radiant-specific version	string	variable
`build_options.quartus_version`	Quartus-specific version	string	variable
`build_options.quick_impl`	Enable fast implementation flow	boolean	`true`, `false`

Makefile Overrides

Arbitrary Makefile variables can be placed under makefile_overrides. These will be generated as KEY := VALUE in build_env.mk.

Example:


makefile_overrides:
  JOBS: 8
  USE_DOCKER: true

Sources and Includes

You can centralize your file lists and include other YAML files to share configurations.

Field	Description	Type	Mapping
`includes`	List of YAML files to include	list	recursively merged
`sources.syn`	Synthesis source files	list	`SYN_FILES`
`sources.sim`	Simulation source files	list	`SIM_FILES`
`sources.lin`	Linting source files	list	`LIN_FILES` / `UNIT_FILES`
`sources.xdc`	Constraint files	list	`XDC_FILES`
`sources.ip`	IP core files	list	`XCI_FILES`

Example:


includes:
  - common_sources.yml

project:
  name: my_project

sources:
  syn:
    - src/rtl/top.vhd

Features Section

Field	Description	Type	Allowed Values / Options
`features.regbank`	Enable automated register bank generation	boolean	`true`, `false`

Simulation Section

Field	Description	Type	Allowed Values / Options
`simulation.test_dir`	Directory where cocotb tests are located	string	variable (default: `sim/cocotb/tests`)

Automatic Dependency Resolution

You can enable automatic dependency discovery by setting auto_sources: true. The tool will parse your src/ directory starting from project.top_module and resolve dependencies automatically. Results are cached in .rapidrtl_cache/dependencies.json to speed up subsequent runs.


project:
  name: my_project
  top_module: top_complex_entity

auto_sources: true
# You can still manually add sources, they will be merged.
sources:
  xdc:
    - constraints.xdc

Hierarchy Visualization

You can inspect the VHDL entity dependency tree using the hierarchy target:


make hierarchy TOP=edge_detector

This will print a tree showing all entities recursively instantiated by the specified top entity:


Dependency Tree for entity 'edge_detector':
========================================
edge_detector [edge_detector.vhd]
  └─ sub_module [sub_module.vhd]
      └─ package functions [functions_pkg.vhd]

[!TIP] For a DOT graph export (suitable for Graphviz visualization), use cocotb-testgen:
python3 tools/cocotb-testgen/gen_cocotb_structure.py --graph hierarchy.dot --root my_entity --src src
dot -Tpng hierarchy.dot -o hierarchy.png

project manager