Create the project configuration

Open the project root with File → Open Folder. Select TOOL Options → Create Project Configuration or Generate property.json, enter a name, and select the toolchain. Configuration is created at .vscode/property.json. Edit existing fields directly; normal generation does not overwrite an existing file.

property.json holds shared project information: device, top levels, directories, libraries, and software applications. Prefer user or remote settings for machine-specific tool paths; use .vscode/settings.json for project overrides. See Toolchain path configuration. With Remote SSH, use paths on the remote extension host.

JSONC comments and trailing commas are supported. Keys are case-sensitive; duplicate keys are rejected. The schema requires toolChain, soc, and device; generation also writes prjName.PL. Generated device: "none" is a placeholder that must be replaced before vendor builds. Runtime defaults are not automatically written back to the file.

Common configuration example

Match the device, names, tops, and paths below to your actual design. Unused files, library, and filelist objects may be omitted. Omit the entire arch object when using the standard layout.

{
  "toolChain": "xilinx",
  "prjName": { "PL": "demo" },
  "device": "xc7a35tftg256-1",
  "srcTop": "top",
  "simTop": "top_tb",
  "arch": {
    "prjPath": "prj",
    "hardware": {
      "src": "user/src",
      "sim": "user/sim",
      "data": "user/data"
    },
    "software": {
      "src": "user/sdk",
      "data": "user/sdk/data"
    }
  },
  "files": { "src": [], "sim": [], "exclude": [], "scanIp": true },
  "library": {
    "state": "remote",
    "hardware": { "common": [], "custom": [] }
  },
  "IP_REPO": [],
  "filelist": { "sources": [], "includeDirs": [], "defines": {} },
  "soc": { "core": "none" }
}

Top levels are HDL module/entity names such as top, not top.v or file paths. Project names and HDL names are independent; renaming a project does not rename its modules.

Toolchain, names, and top levels

Field	Type / values	Meaning and effect
toolChain	String: xilinx or efinity	Selects the vendor workflow, device suggestions, and adapters: Vivado or Efinity. It does not install vendor software or select the quick-simulation backend.
prjName	Object	Holds hardware and software project names.
prjName.PL	Non-empty string	Hardware project name; demo produces a Vivado demo.xpr. Generation uses the entered name; the loader falls back to template. It need not match the HDL top.
prjName.PS	Optional string	Xilinx software workspace name, used for paths and the first application name. SOFT falls back to PL when omitted. Usually unnecessary for fabric-only projects.
device	String	Full FPGA part identifier, including relevant package and speed grade, used for synthesis, implementation, and vendor IP. Use a part identifier, not a board nickname. Empty values and none are unsuitable for vendor builds.
srcTop	Optional string	Design module/entity for hierarchy and synthesis. Otherwise the workflow resolves/selects a top; specify it explicitly when several candidates exist.
simTop	Optional string	Project simulation top, usually a testbench, independent of srcTop. Quick simulation and Netlist use the module selected for that operation.
simRuntime	String, e.g. "1000ns" or "all"	Xilinx backend extension passed to Vivado/XSim xsim.simulate.runtime. Omission retains Vivado defaults. It does not set quick interactive simulation duration. With all, the testbench must terminate itself.

The backend reads simRuntime, although base-schema completion does not yet list it.

Directory layout: arch

arch groups directory settings into arch.hardware and arch.software. The following defaults apply to a generated configuration with the whole arch object omitted.

Field	Type / standard default	Meaning and effect
arch.prjPath	String, prj	Base for vendor projects and intermediate output. Vivado normally uses its xilinx/ child and Efinity uses efinity/. Vivado does not append another xilinx if the path already ends with that name.
arch.hardware.src	String, user/src	Design HDL discovery and classification directory.
arch.hardware.sim	String, user/sim	Simulation HDL/testbench discovery directory.
arch.hardware.data	String, user/data	Constraints and project data such as XDC. Efinity also reads rust/efinity.defaults.toml and rust/pins.toml below it.
arch.software.src	String, user/sdk	Base software workspace directory; Xilinx SOFT normally adds a child named after PS or PL.
arch.software.data	String, user/sdk/data	Hardware handoff directory, searched for .hdf / .xsa by Xilinx SOFT.

Relative paths start at the workspace root; absolute paths are also accepted. Prefer / in Windows JSON paths or escape backslashes. The common backend expands these variables:

Variable	Expansion
${workspace}	Current project workspace root.
${plname}	prjName.PL, falling back to template.
${psname}	prjName.PS, falling back to template during expansion. This differs from SOFT's workspace-name fallback to PL.

When customizing arch, specify all directories above. Standard structure is inserted only when the whole object is absent. A partial arch can make HDL scanning fall back to the whole workspace for missing src / sim, while vendor builders retain their own directory defaults, creating different scan and build scopes.

Xilinx IP and BD directories are normally siblings of the design source directory: user/ip/ and user/bd/ in the standard layout. There are no current arch.hardware.ip or arch.hardware.bd settings.

File membership: files

files supplements or excludes directory-discovered members; it does not replace arch scanning.

Field	Type / default	Meaning and effect
files.src	String array, no additions by default	Additional design HDL paths, such as shared/reset_sync.sv outside the scan directory.
files.sim	String array, no additions by default	Additional simulation HDL paths, such as tests/top_tb.sv.
files.exclude	String array, no extra exclusions by default	Excludes specified files from scanned/explicit project sources by normalized path. These are not gitignore patterns. It neither deletes files nor replaces removing references from library.
files.scanIp	Boolean, default true	Controls HDL indexing of Xilinx IP/BD generated directories. false reduces parsing in large projects and is written by Vivado project import. It does not remove IP/BD from the Vivado project.

Ordinary relative paths resolve against the workspace. Use .dideignore for directory/pattern-based exclusions without excluding required packages, headers, and libraries.

HDL libraries and vendor IP

library describes HDL references, with common/custom members under library.hardware. Packaged vendor IP repositories use the separate IP_REPO array.

Field	Type / default	Meaning and effect
library.state	"remote" / "local", default "remote"	Resolution mode. remote reuses shared/bundled libraries and can resolve packages through configured providers; local uses local paths without remote-package resolution. The name implies neither mandatory network access nor automatic source copying. Sidebar imports currently write remote.
library.hardware.common	String array, default empty	Common HDL files/directories, relative to the common root. remote can also delegate to configured providers. Include only needed members.
library.hardware.custom	String array, default empty	Custom HDL files/directories. Absolute paths are used directly; relative paths use digital-ide.lib.custom.path, or the workspace if no custom root is configured. Directory references discover their HDL descendants.
IP_REPO	String array, default empty	Xilinx packaged IP repository directories, relative to the workspace. Used for catalog queries and Vivado project loading, not as ordinary HDL lists or the Vivado installation path.

Referenced sources remain in place; removing a reference does not delete them. See Libraries for the sidebar workflow.

Filelist metadata: filelist

filelist retains metadata imported from .f and related lists. Actual HDL membership is written to files.src or files.sim.

Field	Type / default	Meaning and effect
filelist.sources	String array, default empty	Source filelist paths, including nested lists resolved during import. This is not an HDL file array. Editing it alone does not reimport sources.
filelist.includeDirs	String array, default empty	Include search directories such as user/src/include, relative to the workspace. Used by parsing and workflows consuming this metadata to locate include files, not as HDL library entries.
filelist.defines	Object, default empty	Macro names mapped to string values or null. Strings define values; null defines a name without a value and does not undefine it. Numeric values must also be strings.

Merge this fragment to define DATA_WIDTH=32 and a valueless SIMULATION macro:

{
  "filelist": {
    "sources": ["rtl.f"],
    "includeDirs": ["user/src/include"],
    "defines": { "DATA_WIDTH": "32", "SIMULATION": null }
  }
}

Reimport after changing source filelists. Inspect actual vendor commands for macro propagation; not every tool consumes the same metadata. See Filelists.

Software system: soc

soc describes processors and software applications. Fabric-only projects can keep {"core":"none"}. Software development also needs a matching hardware handoff and XSCT/Vitis.

Field	Type / default	Meaning and effect
soc.core	String, generated as "none"	Processor. Schema suggestions are none, cortexM3, microblaze, ps7_cortexa9_0, ps7_cortexa9_1, psu_cortexr5, and psu_cortexa53. none means fabric-only. SOFT first detects the processor from hardware handoff, then falls back to this field.
soc.os	String, SOFT default "standalone"	OS/BSP type: standalone, linux, xilkernel, or freertos10_xilinx. Valid combinations depend on processor, template, and vendor release.
soc.app	String or non-empty array of unique strings; default "Hello World"	Vendor templates such as Hello World, Empty Application, lwIP Echo Server, and FreeRTOS Hello World. An array requests multiple apps. Values are not existing source paths or custom application names.
soc.bd	String, normally omit	Legacy BD template field. Schema suggestions remain zynq_default, m3_xIP_default, MicroBlaze_default, and PCIe_Test. The loader retains it, but current build flows do not consume it to create BD files. Use actual .bd files and supported operations.

For a project with a matching Zynq handoff, merge a fragment such as:

{
  "prjName": { "PL": "demo", "PS": "demo_sdk" },
  "soc": {
    "core": "ps7_cortexa9_0",
    "os": "standalone",
    "app": ["Hello World", "Empty Application"]
  }
}

This does not convert the earlier Artix-7 example to Zynq. The device and .hdf / .xsa must match the actual design. The first app uses the software workspace name; later apps derive names from templates. See SDK build and processor debug.

Persistent programming: flash

flash configures Xilinx configuration-memory programming. Ordinary builds and volatile FPGA downloads do not require it. Use a part string or an object. Writing these fields alone does not program hardware.

Field	Type / default	Meaning and effect
flash	Optional string or object	A string is the full part name from get_cfgmem_parts; an object adds options. Identifies board configuration Flash, distinct from the FPGA device.
flash.part	Non-empty string, required in object form	Vivado configuration-memory part, e.g. w25q128fv-spi-x1_x2_x4. Must match the actual chip and a supported tool part.
flash.interface	Optional string	write_cfgmem interface override: SPIx1, SPIx2, SPIx4, SPIx8, BPIx8, or BPIx16. Match the board wiring.
flash.sizeMB	Optional positive integer	Capacity override in MBytes, not Mbits. 128 Mbit corresponds to 16 MB.
flash.format	"mcs" / "bin", default "mcs"	Generated configuration-memory image format.
flash.verify	Boolean, default true	Enables verification in the Flash programming flow.

{
  "flash": {
    "part": "w25q128fv-spi-x1_x2_x4",
    "interface": "SPIx4",
    "sizeMB": 16,
    "format": "mcs",
    "verify": true
  }
}

This is a field example, not a claim about your board. Without interface/capacity overrides, the programming flow uses configuration-memory part information.

Efinity extension fields

The current Efinity backend reads these fields, though base-schema completion does not yet list them. Use them in toolChain: "efinity" projects.

Field	Type / default	Meaning and effect
efinity	Optional object	Efinity-specific parameter container.
efinity.top	Optional string	Top priority: efinity.top → srcTop → legacy top → prjName.PL. Normally set only srcTop to avoid conflicting values.
efinity.family	Optional string	Device family, inferred from device when omitted. Explicit values must match the device and tools.
efinity.timingModel	Optional string	Timing model/speed grade. Overrides the grade parsed from device, then falls back to C4. Match the actual device.

Legacy fields and compatible aliases

Field	Current handling
enableShowLog	Retained Boolean schema field with default false, historically for compilation log display. The current extension and backend do not read it; inspect Output rather than relying on this switch.
simulationRuntime	Alias for simRuntime; a non-empty simRuntime takes precedence.
top	Efinity fallback below efinity.top and srcTop.
program.flash, programmer.flash, configuration.flash	Legacy Flash locations. The first present field wins in order: flash → program.flash → programmer.flash → configuration.flash. Use flash for new configurations.
flash.model, flash.cfgmemPart, flash.cfgmem_part	Aliases for flash.part; use part for new configurations.
flash.size_mb, flash.size	Aliases for flash.sizeMB, also in MBytes; use sizeMB for new configurations.

Retained fields and old template suggestions do not guarantee an implemented workflow. This reference covers every current schema field, plus backend extensions and compatible aliases.

Verify the project

1. Save configuration and check syntax/type diagnostics.
2. Expand Architecture and verify sources, testbenches, libraries, and instances; refresh if needed.
3. Verify both top levels. Right-clicking to set a top updates only its corresponding field.
4. Configure Toolchain path configuration, then run TOOL Options → Validate Configured Toolchains. Only explicit non-empty paths are checked; a green check means the executable ran and its version was recognized.
5. Inspect the device, tops, directories, and commands in Output before quick simulation or HARD.

For AI project inspection/configuration, follow Install dide-mcp, which includes a directly copyable installation prompt requiring no manual substitutions.

Project management operations · Device completion · Filelists