In Sigasi, a project is the fundamental unit used to define how your HDL code is analyzed and understood. While you can open individual files in VS Code, Sigasi works best when your files are part of a project.
Why do you need a project?
Projects are essential for effective design and collaboration:
- Global Analysis: Sigasi analyzes how all your source files connect, enabling powerful features like project-wide reference tracking, navigation to declarations, and accurate type checking across your entire design.
- SystemVerilog Preprocessing: SystemVerilog files often rely on macros and include files defined elsewhere. A project provides the necessary preprocessor environment (include paths and initial defines) for accurate analysis.
- Scope Definition: A project defines exactly which files are relevant to your design and which should be ignored, preventing unnecessary analysis of unrelated files.
- Shared Configuration: A project serves as a central location to store settings such as language versions, library mappings, and linting rules. Because these configuration files are stored on disk, they can be checked into your source control system (like Git) to ensure the entire team uses the exact same setup.
Project types: Modular Projects vs. Classic Projects
Sigasi supports two project formats. Modular Projects are the default and recommended format for new work; Classic Projects remain supported for existing setups.
Modular Projects
Modular projects store their configuration in a project.sigasi (or .sigasi/project.sigasi) file.
- Why they exist: To support modern HDL workflows, such as scripted builds, multiple build targets, and advanced dependency management.
- Key Features:
- Multiple Build Targets: Modular projects support multiple build targets (e.g., separate targets for RTL and testbenches) that can depend on each other. This allows a testbench target to “see” and use design units from an RTL target without duplicating configuration.
- Scripted Targets: Large HDL projects often use dedicated build systems like Makefiles or Bazel. Through Scripted Targets, Sigasi can consume these descriptions to stay in sync with your external build environment as the project evolves.
- Who they are for: All new projects, regardless of size or complexity.
Classic Projects
Classic projects use the .project and .library_mapping.xml files and a .settings folder to describe the project’s structure.
- Why they exist: They predate Modular Projects and provide a file-system-based mapping approach that’s still in use across many existing codebases.
- Who they are for: Teams maintaining existing Classic project setups. For new projects, use Modular Projects instead.