Defining a dependency on another target makes HDL definitions from that target’s sources available in the current target’s sources, as well as in sources of all targets that would depend on this target. You can define a dependency on:
- Another target of the same project
- One or multiple targets of another project
- A library from the Library Database
Sigasi does not report errors, warnings, or linting issues in a dependency’s own sources. You can use this to avoid linting noise in code you cannot change and keep the analysis of your own project fast. Dependencies that are explicitly open in your workspace are still analyzed and linted in their own right. If you don’t want errors, warnings, or linting issues from a target dependency in the same project, for example a target that only exists to supply definitions to other targets, you can lower its analysis effort.
Adding simple dependencies from the projects view
These dependencies can be added to a target in a project, by right clicking on a project in the Projects View and selecting . You can also right click a target
under the Targets folder in the Projects View and select to add a dependency specifically to that target. Dependencies will show up under the Dependencies folder.
To see how all targets in your project depend on each other, and to spot cycles or unresolved dependencies at a glance, open the Target Dependency Diagram.
Manually adding dependencies
Alternatively, you can add dependencies by editing the project.sigasi file yourself.
You can add a dependency to a target under the dependencies field.
You can also add a dependency to a whole project,
by specifying them under the dependencies field at the root of the project configuration JSON.
Adding a dependency to a whole project is equivalent to adding it to all targets in the project.
Each dependency is an object with dependency project name as a key, and an object with the following fields as a value:
| Field | Description |
|---|---|
version | Depend on the specified version of the referenced project, tool libraries, or library |
targets | Depend on the specified targets of the referenced project, or on libraries of the referenced tool |
When you want to specify only a specific version or target, or depend on a target of the current project, a shorter dependency declaration syntax is available:
| Short version | Full version |
|---|---|
{ "common_cells": "1.0" } | { "common_cells": { "version": "1.0" } |
{ "apb_uart": ["test"] } | { "apb_uart": { "targets": ["test"] } } |
"rtl" | { "current_project": { "targets": ["rtl"] } } |
Note that the latter form is only allowed for dependencies between targets of the same project. It cannot be used to specify dependencies of the whole project.
Example:
{
"name": "Target Dependencies",
"version": "0.3",
"dependencies": [ // Dependencies for all targets of this project:
// Dependency on all targets of another project named "common_cells" with version "1.0"
{ "common_cells": "1.0" },
// Dependency on a target named "rtl" of another project named "apb_uart"
{ "apb_uart": ["rtl"] }
],
"targets": {
"ip1": { /* ... */ },
"rtl": {
// ...
"dependencies": [ // Dependencies specific to this target:
// Dependency on another target of this project with the name "ip1"
"ip1",
// Dependency on the UVM 1.2 library from the Library Database
{ "UVM": "1.2" },
// Dependency on "altera" and "lpm" libraries from the latest "Quartus" tool in Library Database
{ "Quartus": [ "altera", "lpm" ] }
// Dependency on Vivado 2023.2's "unisim" library from the Library Database
{ "Vivado": { "version": "2023.2", "targets": [ "unisim" ] } }
]
}
}
}version
Specifies the version of the project or library you depend on. If no dependency version is specified, the latest version found is used. Note that currently Sigasi does no interpretation of version strings, so:
- the latest version is determined by alphabetical comparison of version strings; and
- currently there’s no way to specify more complex version requirements (e.g., defining version ranges): only exact matches are supported.
targets
Specify a list of targets of the referenced project that should be available in current target. If no targets are specified, all targets from the referenced project become available.
If an empty list is specified, no targets are added. You can use this to override versions, as explained in the next part.
Dependency resolution
When you specify a dependency, Sigasi searches for it on the dependency search path.
For each target, dependencies are resolved independently. Together, they form a target’s dependency tree. You can view the dependency tree of the current project’s Target dependencies diagram.
Currently, only one version of the project or library can be present in a target’s dependency tree. If the dependency tree contains multiple versions of the same project or library, the last specified version (in other words, a version specified closer to the current target in a dependency tree) is used. You can use this to override dependency versions.
Overriding dependency versions
Because the last specified version of a dependency within the target’s dependency tree is used, you can override a version specified in transitive dependencies.
For example, the common target below depends on the 2021.1 version of Vivado’s unisim library.
In common, however, the version is overridden to version 2023.2, by specifying the dependency again.
By passing an empty targets list, we ensure only the version is overwritten, not the targets.
{
"name": "Dependency Version Override",
"version": "0.2",
"targets": {
"common": {
// ...
"dependencies": [
{ "Vivado": { "version": "2021.1", "targets": [ "unisim" ] } }
]
},
"rtl": {
// ...
"dependencies": [
"common",
// Incorrect way to override version. It overrides version, but also adds all Vivado libraries.
{ "Vivado": "2023.2" },
// Correct way to override a version. It overrides the version, but does not add any new libraries.
{ "Vivado": { "version": "2023.2", "targets": [] } }
]
}
}
}Dependency search path
When you specify a dependency, Sigasi searches for projects that match in your open VS Code workspace folders. If it cannot find them there, it searches:
- the directories on the project dependency search path,
- the directories on the
sigasi.dependencySearchPathsetting, - the tools and libraries database,
- the directories on the
SIGASI_DEPENDENCY_SEARCH_PATHenvironment variable, and - the built-in library database.
Each of these directories is searched for Modular Projects and library database definitions recursively. The first project or library that satisfies dependency requirements (name and version) is used.
You can use environment variables in the project dependency search path and the
sigasi.dependencySearchPathsetting. Supported formats:$ENV_VAR,${ENV_VAR}, and${ENV_VAR:default_value}. You can also use paths relative to the home directory (e.g.~/some/path).
Project dependency search path
The project dependency search path is a property of the modular project description. There are two main differences between the paths specified here and in the rest of the dependency search path.
First, the project dependency search path allows relative paths, not just absolute paths. They are resolved relative to the project’s root directory before they’re added to the dependency search path.
Second, these paths are only used to resolve the dependencies of this project. They’re not made available to any of the other projects in the workspace or elsewhere on the path. For example, consider the following five projects:
| Name | Project directory | Project dependency search path | Dependencies |
|---|---|---|---|
| kid | ~/example/kid/ | [] | |
| pa | ~/example/pa/ | ["../kid"] | kid |
| cousin | ~/example/auntie/kid/ | [] | |
| auntie | ~/example/auntie/ | ["."] | cousin |
| gran | ~/example/gran/ | ["../pa", "../auntie"] | pa, kid, cousin |
- Kid and cousin are two simple projects without any dependencies.
- Pa is stored next to kid on disk, and depends on it through its project dependency search path.
- Auntie depends on cousin, which is a project stored inside of it (think git submodules).
Auntie finds cousin because its own directory (
".") is on its dependency search path. - Gran depends on pa, kid and cousin.
Gran finds pa directly on its project dependency search path,
cousin in a subdirectory of a directory (
"../auntie"), but it does not find kid (even though its dependency pa can resolve it). After all, kid is not stored in../paor../auntie.
The dependency search path environment variable
The SIGASI_DEPENDENCY_SEARCH_PATH environment variable is a :-separated list of paths,
similar to the PATH environment variable on Linux.
You can define it as a
regular environment variable or through
Sigasi.
The built-in library database
Together with Sigasi we ship a library database that contains some common dependencies. It currently contains the UVM library versions 1.1d, 1.2, 2017-1.1, and 2020-3.1.
Analysis effort
Not every source in a project needs to be fully analyzed.
Code that you don’t own, such as a vendored subfolder, a Git submodule, or a target that only exists to supply definitions to other targets, is effectively a dependency that happens to live inside your own project.
By setting the analysis effort of such sources to minimal, Sigasi treats them exactly like the sources of a dependency. As described above, their definitions are available to the targets that use them, but the sources themselves are not validated or linted.
To change the analysis effort, right-click on a target, folder, or file in the Projects view and select .
This is stored under the analysis.effort key in the
settings file:
{
"@override": {
// A git submodule with third-party sources
"vendor/apb_uart": {
"analysis.effort": "minimal"
}
},
"@targets": {
// A target that only provides definitions to other targets
"cells": {
"analysis.effort": "minimal"
}
}
}The analysis effort defaults to full and follows the regular
setting priorities.
So a file can be analyzed fully in one target and minimally in another, and setting full on a more specific path brings that folder or file back into full analysis.
Fragments
A target can be marked as a fragment. This disables validation of that target unless it is added as a dependency of another non-fragment target. Fragment targets are validated in the context of the non-fragment targets that depend on them.
Fragments may be helpful if shared code is not complete (cannot be compiled) without specific configuration code.
Example:
{
"name": "Fragment Targets",
"version": "0.1",
"targets": {
"common": {
"fragment": true,
"libraryMapping": {
"common": "work"
}
},
"asic": {
"libraryMapping": {
"asic_cells": "work"
},
"dependencies": [
"common"
]
},
"fpga": {
"libraryMapping": {
"fpga_cells": "work"
},
"dependencies": [
"common"
]
}
}
}