ctrl+shift+p filters: :st2 :st3 :win :osx :linux


by bootsiaz ST3

A hierarchical RTL project plugin for Sublime Text 3


  • 0.6.9
  • bitbucket.​org
  • 2 weeks ago
  • 41 minutes ago
  • 2 years ago


  • Total 545
  • Win 338
  • OS X 85
  • Linux 122
Oct 22 Oct 21 Oct 20 Oct 19 Oct 18 Oct 17 Oct 16 Oct 15 Oct 14 Oct 13 Oct 12 Oct 11 Oct 10 Oct 9 Oct 8 Oct 7 Oct 6 Oct 5 Oct 4 Oct 3 Oct 2 Oct 1 Sep 30 Sep 29 Sep 28 Sep 27 Sep 26 Sep 25 Sep 24 Sep 23 Sep 22 Sep 21 Sep 20 Sep 19 Sep 18 Sep 17 Sep 16 Sep 15 Sep 14 Sep 13 Sep 12 Sep 11 Sep 10 Sep 9 Sep 8
Windows 0 0 0 2 0 1 1 0 2 2 0 2 2 2 0 1 0 1 1 1 2 0 0 1 1 2 0 1 0 0 0 0 0 0 0 1 0 0 0 1 1 1 0 0 0
OS X 0 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 0 0 0 1 0 0 0 1 0 0 0 1 0 1 0 0 0 0 1 0 1 0 0 1 0 0 0 0 0
Linux 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0



HDLProject is a hierarchical RTL project plugin for Sublime Text 3.


  • Simple project creation: Add entire directories or libraries, individual files, or source vendor created project Tcl.
  • Create a hierarchical RTL project and navigate the project in the sidebar.
  • Open past projects and refresh project hierarchies.
  • Work on multiple projects in different windows.
  • Build integration with Vivado and Quartus tcl commands.
  • Option to expand Vivado-based IP into source file hierarchy.
  • View a signal or constant's definition in a popup when hovering.
  • Create simple makefiles.
  • Supports both VHDL and Verilog.

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,

  // 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.

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

      // 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,


Creating a Hierarchical Project

First, the HDLProject preferences file must be filled out with your project information and other desired settings. You can then access the project based commands from the Project menu.

A simple method of project creation is sourcing a .sublime-project file in the “files” list. The plugin supports the folder_exclude_patterns list on a path by path basis, which speeds up project creation for designs with large libraries.

Another simple method of project creation is mapping to an existing Vivado, Quartus, or ISE project. First, a project Tcl needs to be generated in the vendor tool. Then add this Tcl path to the “files” list for your project in the plugin preferences. If using Vivado make sure to select “write all project properties” when generating the Tcl.

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.

Note that on Windows, it works best with admin privileges. This allows for the creation of symlinks. Without raised privileges, hard links are created which slows down project creation, and some of the file system navigation ability is lost. I recommend always running ST3 with admin privileges on Windows if you use this plugin regularly. As a side effect, in administrator mode, you will not be able to access files on a network drive without creating the EnableLinkedConnections registry key. https://serverfault.com/questions/780639/enablelinkedconnections-isnt-working-on-some-windows-10-machines

Navigating the Project

The created project is separated into a 'hierarchy' and 'files' directories. The 'hierarchy' contains the hierarchical RTL. The 'files' contains the project files in their original source folders. Sidebar 'reveal' commands are provided to quickly jump between a file in the hierarchy to its source folder, and vice versa.

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. Constant popups are only supported in VHDL at the moment.

Creating a Makefile

  • Right-click and select HDLProject->Create Makefile
  • A simple makefile will be created from the active project showing the build order.
  • 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.

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.

Other Sublime Text Info



  • 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.


  • Cleaned up and simplified creation of symlinked file system
  • Fix for when there is no active view and a build is initiated.


  • Changed signal popups to enabled by default.
  • Added constant popups for VHDL when in project mode.
  • Cleaned up tool tip commands.
  • Changed popups to use on_hover instead of having to click.
  • Changed Vivado implement.tcl to open the checkpoint instead of the project when complete
  • Updated the parameters being passed to the tcl scripts (see Build Tcl Scripts section above).
  • Added Vivado tcl: add_file_to_project, open_project_in_gui, write_project_tcl
  • Added refreshing of open views after refreshing your HDLProject
  • Fix for signal name popup not showing signal's name in the definition.


  • Fix for bad reference to renamed function to get symlinked file target.


  • Fix for refresh loop on Windows when project file doesn't exist.
  • Fix for set_status where file_name variable was not defined.


  • Fixed is_visible methods for reveal sidebar commands.
  • Added support for creation of symlinked 'files' structure when on Windows without admin.
  • Added support for reveal-in-sidebar-file-sys when on Windows without admin.
  • Pulled sidebar commands out to top menu level.
  • Made use_win_symlinks preference False by default.
  • Changed Open Containing Folder command to Symlink Open Containing Folder for clarification.


  • Added dropdown for create project and added to command pallette.
  • Added support to use on Windows without admin priviledges.
  • Removed creation of symlinked dirs when on Windows and variable is not set.
  • Added use_win_symlinks variable.
  • Added support for getting real file paths of hard-linked files in a project.
  • Fixed reveal_in_sidebar_filesys command.


  • Improved UI
  • Deprecated vivado_user_tcl and quartus_user_tcl settings
  • Added build_tcl list setting
  • Added integration with Vivado and Quartus Tcl commands
  • Added example Vivado Tcl
  • Added ability to show dropdown list for build Tcl
  • Deprecated svn highlighting as it doesn't fit in with the theme of the plugin
  • Deprecated check_syntax command since it required hdlproject to become a project itself instead of a map to one
  • Added initial VHDL completions file
  • Fixed case sensitivity of output_path setting
  • Fix for signal tool tip in VHDL files when comments are in specific locations
  • Cleaned up canceling of build and fixed deadlock issue


If you have any feedback or feature requests, please feel free to contact me (Andrew) at info@hdlproject.com

Copyright 2017, Andrew Carter, All rights reserved.