HDLProject is a VHDL and Verilog project IDE for Sublime Text 3.


  • Simplifies project creation
  • Creates a hierarchical project in the sidebar.
  • Automatic syntax checking.
  • Signal and constant definition popups.
  • Navigate between the file system and hierarchy in the sidebar.
  • Work on multiple projects in different windows.
  • Build integration with Vivado and Quartus.

Example Hierarchical Projects

Video Demo

HDLProject for Sublime Text Tutorial


Default Settings:


  // Custom output path for project creation. If not defined, system-specific default will be used.

  // Show the real source path in the status bar. (The symlink target as opposed to symlink itself.)
  "show_source_path": true,

  // Indicate whether the open hdl file will be revealed in the sidebar automatically. 
  "sync_sidebar": true,

  // Syntax checking requires Vivado installation and build_tool_path setting. 
  "check_syntax_on_save": true,

  // Open and print stdout to a panel when checking syntax.
  "check_syntax_panel": false,

  // Vivado or Quartus tcl scripts for a .xpr or .qsf project. 

  // A list of RTL projects. 
      // ID sets the basename of the output folder and the tag in the project menu
      "id": "project_foo",

      // Top level module/entity name
      // If not defined, it will automatically pick one. 
      "top_module": "JpegEnc",

      // A list of zero or more folders where the project files reside.

      // Can be a .sublime-project file
      // Can be a list of zero or more files (absolute paths).  
      // This is useful when there are multiple files with the same module/entity name. 
      // Can be a project tcl created in vivado, quartus

      // Use the next two settings if you want to build a FPGA project within Sublime
      // The FPGA project file, .qsf (quartus) or .xpr (vivado)
      // These are required for the build_tcl scripts. 
      "project_file": "/Users/bootsiaz/Downloads/mkjpeg/trunk/build/jpegenc.xpr",
      // FPGA vendor tool path, indicate the full path to the 'bin' folder
      "build_tool_path": "/opt/Xilinx/Vivado/2016.4/bin/",

      //If using vivado IP, indicate if you want to unwrap the hierarchy
      "unwrap_vivado_ip": false,


HDLProject Creation

A simple method of project creation is by sourcing a reference ST3 project. This ST3 .sublime-project can be easily created by opening a new view, adding folders to the project via the project menu, and saving the .sublime-project file. The path for this should then be included in the files list for your HDLProject in the preferences file. Once the HDLProject preferences file is filled out with your remaining project information, you can create a project via the command pallette (ctrl+shift+p), or from the project menu, using the Create HDL Project command.

In the reference .sublime-project file, folder_exclude_patterns and file_exclude_patterns lists are supported (although using wildcards is not).

Once the HDLProject is created, the status bar will indicate if there are any ambiguous files -- multiple HDL files with the same module/entity name. These can be cleaned up by running the Cleanup Module Ambiguity command from the command pallette. The ambiguous modules are displayed in a drop-down list, and the user can select which path they want to keep in the project, the remaining paths will be removed. The reference .sublime-project file will be automatically updated with new file_exclude_patterns.

Alternatively, if using Vivado or Quartus, it makes sense to keep these projects in sync with you HDLProject. You can do this by creating a project tcl in the vendor gui, and using this file as your reference project, instead of the .sublime-project. If using Vivado, make sure to select "write all project properties" when generating the Tcl. (A tcl script is also included to create the project tcl for Vivado.)

Note that for simple projects, you can add the folders and files directly into the lists in the HDLProject preferences file.

The preferences file supports an unlimited amount of HDLProject project configurations.

HDLProject on Windows

Note that on Windows, it is recommended to run ST3 with admin privileges.

This allows for the creation of symlinks. Running this plugin without raised privileges on Windows has only had minimal testing, (and hard links are created which slows down project creation, and some of the file system navigation ability is lost). As a side effect, in admin mode, you will not be able to access files on a network drive without creating the EnableLinkedConnections registry key.

Navigating the Project

The created directory structure is a tree of symlinked files and is stored at your custom output path provided in the preferences file. If not defined, it will be created at $TEMP/sublime_hdl_project on Windows, or ~/.sublime_hdl_project on OSX and Linux.

The created project is separated into a 'hierarchy' and 'files' directories. The 'hierarchy' contains the hierarchical RTL. The 'files' contains the original source folders. You can quickly jump between a file in the hierarchy to its source folder by using the sidebar Reveal in Sidebar File System and Reveal in Sidebar Hierarchy commands, accessed from the context menu when right-clicking on a file in the sidebar.

Build Tcl Scripts

HDLProject integrates with Vivado and Quartus tcl commands. You can create your own scripts and add their paths to the build_tcl list in the preferences file. Tcl scripts can then be run from either the Project menu, the build system HDLProject build, or from the command pallette. Note that Tcl scripts can only be run after a project has been created. Some example Tcl scripts are provided with the plugin to help get you started.

Builds can be cancelled at any time. Any succeeding build will cancel any build that is currently running. HDLProject includes a process manager object that will keep track of, and later terminate, any spawned processes when cancelling a build or closing ST3. This allows for complex tasks like building an entire FPGA project, opening the GUI, analyzing placement and routing, all from a tcl script, and initiated from ST3.

The following parameters are passed to the tcl scripts:

  • arg0: project_file setting from the preferences file for the active project
  • arg1: top_module setting from the preferences file for the active project
  • arg2: The file name of the open view window.active_view().file_name()

Signal Inspector Tool

The signal inspector tool provides a popup whenever hovering over a defined signal or constant. Enable or disable with ctrl+shift+l (cmd+shift+l in OS X). It is enable by default. Constant popups only work in an active project.

Syntax Checking

Syntax checking requires a Vivado installation and the location for any one project specified with the build_tool_path setting. The check_syntax_on_save setting will call the syntax checker thread when any file is saved within a HDL Project window. The number of errors is displayed in the status bar. You can navigate syntax errors in your project by using the go_to_prev_syntax_error and go_to_next_syntax_error commands. A dot is placed in the gutter to the left of the line associated with any error. Hovering over the dot will provide a popup with the error message from the syntax log. To view the syntax log, enable the check_syntax_panel setting. Note that syntax checking only works within an active project.

Retrieving Compile Order

To get a list of files in the right compile order, run the Create Makefile command from the command pallette. If a file you need is missing from the project, for example a non-HDL file, you can specify it in the 'files' section in the project settings.

Key Mapping

Windows and Linux:

{ "keys": ["ctrl+shift+l"], "command": "toggle_signal_tool_tip" },
{ "keys": ["ctrl+shift+b"], "command": "cancel_tcl_build"},


{ "keys": ["super+shift+l"], "command": "toggle_signal_tool_tip" },
{ "keys": ["super+shift+b"], "command": "cancel_tcl_build" },


VHDL completions for common keywords is included. This can be used in tandem with the VHDL plugin.


  • Tested on Windows 7/10, Mac OS Sierra, Ubuntu 14.04/16.04


The current version of HDLProject is free to evaluate indefinitely. Please note, this is not an open-source tool. As such, only the python binaries are included in the repository.

Known Issues

  • Hierarchical package file are not supported for makefiles.
  • Signal tooltip does not support multiple signal declarations on the same line.
  • The Windows path character limit of 260 may be exceeded, preventing creation of the project.
  • VHDL
    • Ignores architecture specification in instance statement
    • Configuration declarations are not parsed.
    • Currently does not support entity declaration in a different file from the architecture.
  • Verilog
    • Ignores ifdef statements, all code is parsed.
  • Itegration with Quartus has had minimal testing.
  • Since 0.6.7, I have been unable to test in OS X.
  • Constant popups are only supported in VHDL at the moment.
  • Whenever first opening a project or removing or adding files, it is recommended to run the Refresh HDL Project command. This is not currently done automatically.

Other Sublime Text Info



  • Added ability to detect ambiguous modules
  • Added ability to remove ambiguous modules from a .sublime-project reference project.
  • Replacement of dialogues with warning and error messages.
  • Added command to open reference ST3 project


  • Updated syntax check to only auto-run when .vhd or .v files are saved.
  • Added persistent status for number of syntax errors.
  • Fix for get_symlink_target.
  • Fix for window not found error in on_activated_async
  • Fixed project creation from .sublime-project when paths are relative
  • Added storing repeated module names, but not available to user yet.
  • Added remove file from project tcl for Vivado.
  • Fixed exception in process manager during syntax check
  • Updated mkdir to ensure within defined output directory


  • Added syntax check for VHDL and Verilog (requires Vivado install)
  • Added syntax check settings to preferences file.
  • Added syntax error navigation and popups.
  • Signal popup now only available in project mode.
  • Added more commands to command pallette.
  • Increased max projects for project menu dropdown.
  • Removed popup dialogue when symlink creation fails due to Windows path limit, now a warning in the panel instead.
  • Fix for panel auto-scroll.
  • Various stability fixes.


  • Added check if running as admin on Windows.
  • Removed confusing use_win_symlinks setting.
  • Updates to support longer library paths in VHDL instances
  • Now supports library paths with and without component/entity keywords


  • Fixed bug in missing file printout


  • Added open project file command for opening the file pointed to by project_file.
  • Changed behaviour of make directory errors to give warnings in the panel instead instead of blocking with a popup error.
  • Changed behaviour of file does not exist errors to instead give warnings in the panel instead as opposed to blocking with a popup error -- non-existing files will now have "black_box" suffix in hierarchy.
  • Updated refresh project to re-focus all views to prevent non-activated files after first refresh.
  • Fix for errors removing hierarchy when refreshing.
  • Added support for loading projects from sublime project files, including support for folder_exclude_patterns.
  • Changed behavior of constant popup to avoid auto-updating project - now up to user.
  • Changed behvior of signal and constant popups to load the file less often -- no longer has any affect with on_activated. So file has to be saved to see difference.


If you have any feedback or feature requests, please feel free to contact me (Andrew) at


Package Control: BitBucket:

Copyright 2017, Andrew Carter, All rights reserved.