Transitioning from Classic Projects

Classic Projects can be easily translated to Modular Projects by using a manual target. A manual target allows you to manually define library mapping, language version, include directories, etc. just as you would with Classic Projects.

Since Modular Projects work a bit differently, some workflows don’t carry over one-to-one to. This guide explains the equivalent workflows in Modular Projects.

Classic Projects remain fully supported. You don’t have to migrate, but we recommend doing so as the Classic format can no longer be evolved and Classic Projects can not be included in dependencies from Modular Projects.
Features such as settings sharing and scripted targets cannot be supported by Classic Projects.

In short

1. Create a manual target for your projects with corresponding library mapping and include paths
2. Migrate your Common Libraries:
   1. Create (a project with) a target for every linked folder in Common Libraries
   2. Include every linked folder that was in Common Libraries as a dependency
   3. Include every Tools and Libraries library as a dependency
3. Migrate Linked Resources (files from outside the project tree) to a target’s directory, and adjust their library mapping and include paths
4. Adjust your scripts to use project.sigasi and .sigasi
5. Remove the .project and .library_mapping.xml files, and the .settings folder

Common Libraries

In Classic Projects, Common Libraries is a virtual folder for the VHDL standard libraries and reusable external HDL files. Its files are superficially analyzed, never linted.

Modular Projects no longer use this folder, instead:

• Standard libraries (std, ieee) are provided automatically, under an immutable VHDL Standard Libraries node.
• External source and pre-extracted libraries become dependencies.

Adding external source as a dependency

In Classic Projects, you could depend on an external source tree by dragging its folder into Common Libraries as a linked folder.

In Modular Projects, you can use Dependencies instead: you can depend on another target (within the same project or from another project), or a library from the Library Database. The dependency’s definitions become available to your target while its sources are analyzed on their own. Just like Common Libraries, you get no linting noise from code you don’t own.

Add a dependency by right-clicking a project or target and choosing Add Dependency, or edit the dependencies field in project.sigasi.

Using libraries from the Tools and Libraries Database

In Classic Projects, you could extract tool and verification libraries (Vivado, Quartus, UVM, UVVM) into the Tools and Libraries Database, then enable them on the Common Libraries settings page.

The Tools and Libraries Database is unchanged, you extract and manage libraries there as before. Only how you use them changes: instead of modifying the Common Libraries settings page, add a library from the database as a dependency, e.g., a UVM version, or Vivado’s unisim.

Linked resources and environment variables

In Classic Projects, Linked Resources pulled in files from outside the project tree, and ENV- variables kept those paths portable across machines.

Modular Projects do not support linked resources. Instead, you can point a target’s directory at the external location; its libraryMapping, override, and includeDirectories paths resolve from there, and Sigasi scans it as part of the target. For a self-contained, reusable tree, model it as its own target or project and pull it in as a dependency.

Instead of ENV- prefixes, use environment variable substitution. You can use environment variables like $VAR, ${VAR}, or ${VAR:default} in the directory field. For example, a Classic Project’s ENV-HOME path becomes ${HOME}/.... To define variables that travel with the project, use the environment field in project.sigasi.

The Targets node

In a Classic Project there were no targets: all files were mapped to libraries and analyzed as one unit. A Modular Project shows a Targets node instead.

A target is a self-contained set of files that Sigasi compiles and analyzes together. All targets are listed under the Targets node in the Projects view.

Your whole Classic Project maps to a single target. A Modular Project created from an existing codebase starts with exactly that: one target (named rtl by default) whose library mapping does what your Classic Project’s mapping did. If that’s all you need, you can ignore the node.

Targets let you split a design into independently-compiled units. For example rtl and tb, or synthesis and simulation connected with dependencies. There are two kinds:

• Manual targets declaratively map files to libraries; similar to a Classic Project.
• Scripted targets reuse existing build scripts (a Makefile, a simulator do-file, …) to derive the structure.

Project configuration files

A Classic Project spreads its configuration across the .project (the Eclipse project description) and .library_mapping.xml files (library assignments), and a .settings folder full of .prefs files. These are all in Eclipse’s XML and .prefs formats.

A Modular Project uses two JSONC  (JSON with comments) files instead:

• project.sigasi that defines the name, targets, library mapping, language and compiler settings, and dependencies.
• .sigasi/settings.json that defines linting and formatting preferences, tunable per target, folder, or file.

Let’s map out where each Classic Project configuration file goes:

If you were using a minimal project setup that only had a .project file, no .library_mapping.xml or .settings, you can also drag your sigasi.project into the .sigasi folder.

If you have scripts that read or write these files

Scripts that depend on the exact location or format of the .project, .library_mapping.xml, or the .settings/*.prefs files will no longer work. Point them at project.sigasi and .sigasi/settings.json instead. The JSONC format is easier to generate and manipulate than Eclipse’s XML and .prefs.

See the Project Description File Reference and Settings File Reference for the exact format and every field your scripts can target.

Version control

For which files to track (commit project.sigasi and .sigasi, ignore .sigasi/generated), see Modular projects in version control systems.

Need help?

If a Classic Project’s workflow you rely on isn’t covered here, or you’re not sure how to migrate it, our Support team is happy to help.