HOWTO: Setting up a project

Setting up a project

• Using JSON file
• Using legacy prj file
• Compilers' default flags
• Environment variables

HDL Checker can work with or without a configuration file. Both LSP and HTTP mode function very similarly, except LSP mode will look for sources under a workspace's root URI if no configuration file is found (therefore, as of now, using LSP is preferred). More info on LSP can be found on the LSP Spec.

Because automatic library discovery might be incorrect, one can use a JSON configuration file to list files or to hint those which libraries were guessed incorrectly.

Notes:

• Glob patterns follow Python's glob module, which has a slightly different behavior in Python 2.7 and 3.x. For more info, see https://docs.python.org/library/glob.html
• If a configuration file is specified, HDL Checker will not search the root directory automatically. To search for files, you can specify folders in the include key of the config file
• Legacy project file format does not support listing files without libraries
• If a configuration file is specified, HDL Checker will try to decode it as JSON first and, if that fails, will parse as prj

Changes on this behavior will be reflected on this page.

Using JSON file

JSON format is as show below:

Note: Notation below uses JSON5 for the comments for readability only, configuration files follow "regular" JSON.

{
  /*
   * List of source files (optional, defaults to []).
   * If specificed, must be a list of either strings or source spec tuples, where
   * source spec tuple is a tuple in the form [string, dict[string, string]] (see
   * below for details).
   */
  "sources": [

    /*
     * Sources can be defined solely by their individual paths or glob patterns.
     * Absolute paths are unchanged, relative paths are made absolute by using
     * the path to the configuration file. Sources imported from an included file
     * will follow the same principle but using the path to the included path.
     */
    "/some/vhdl/file.vhd",
    "/some/verilog/file.v",
    "/some/systemverilog/file.sv",
    "/vhdl/files/only/*.vhd",
    "/all/files/recursively/**/*",

    /*
     * Tuples can be used to add more info on the path. First element of the
     * tuple must the a string with the path, second element is optional
     * (defaults to an empty dictionary). Dictionary can specify the path's
     * library ({"library": "name_of_the_library"}), special compile
     * flags({"flags": ["flag_1", "flag_2"]}) or both.
     *
     * Glob patters are also supported here.
     */
    [ "/path/with/library/and/flags", { "library": "foo", "flags": ["-2008"] } ],
    [ "/path/with/library",           { "library": "foo" } ],
    [ "/path/with/flags",             { "flags": ["-2008"] } ]
  ],

  /*
   * Extra config files to be added to the project (optional, defaults to [])
   * If specificed, must be a list of stings.
   */
    "include": [
        // Includes a path directly
        "/path/to/another/json/file.json",

        /*
         * Including a folder is also possible. If the folder constains a file
         * whose name matches the HDL_CHECKER_DEFAULT_PROJECT_FILE environment
         * variable (see below), the file will be used. If the config file does
         * not contain the "sources" key, HDL Checker will search the folder for
         * files.
         *
         * If no such file is found, the path is searched for sources (which
         * includes subfolders)
         */
        "/search/this/path/"
    ],

  /*
   * Language / scope specific info (optional, defaults to {}). Setting these,
   * event if empty, will override values defined per compiler. Flags should be
   * specified as a list of strings.
   *
   * The scope keys are:
   *   - "single": flags used to build the file being checked
   *   - "dependencies": flags used to build the dependencies of the file being
   *     checked
   *   - "global": flags used on both target and its dependencies
   *
   * For example, suppose the compilation sequence for a given source S is A, B,
   * C and then S. The tool will compile A, B and C using global and dependencies
   * flags, while S will be compiled using global and single flags.
   */
  "vhdl": {
    "flags": {
      "single": ["flag_1", "flag_2"],
      "dependencies": [],
      "global": []
    }
  },

  "verilog": {
    "flags": {
      "single": [],
      "dependencies": [],
      "global": []
    }
  },
  "systemverilog": {
    "flags": {
      "single": [],
      "dependencies": [],
      "global": []
    }
  }
}

Using legacy prj file

Old style project file syntax is as follows:

# This is a comment

[ builder = (msim|ghdl|xvhdl) ] # This is being deprecated, listed here for documentation only!

[ global_build_flags[ (vhdl|verilog|systemverilog) ] = <language specific flags> ]

# Specifying sources
(vhdl|verilog|systemverilog) <library name> <path/to/source> [file specific flags]

An example project file could be:

global_build_flags = -32  # Common flags for all languages
global_build_flags[vhdl] = -rangecheck
global_build_flags[verilog] = -lint
global_build_flags[systemverilog] = -lint

# Relative paths (relative to the project file if using HTTP mode or the project
# root if using LSP mode)
vhdl          my_library foo.vhd                               -check_synthesis
vhdl          my_library foo_tb.vhd                            -2008
verilog       my_library verilog/a_verilog_file.v              -pedanticerrors
# Absolute paths are handled as such
systemverilog my_library /home/user/some_systemverilog_file.sv -pedanticerrors
# Wildcards are supported
vhdl          my_library library/*.vhd
vhdl          my_library library/*/*.vhd

Setting specific flags can be done per language or per file:

global_build_flags[vhdl] = <flags passed to the compiler when building VHDL files>
global_build_flags[verilog] = <flags passed to the compiler when building Verilog files>
global_build_flags[systemverilog] = <flags passed to the compiler when building SystemVerilog files>

Compilers' default flags

When unset, HDL Checker sets the following default values depending on the compiler being used:

• ModelSim

Language	Scope	Flags
VHDL	Global	-explicit
VHDL	Dependencies	-defercheck -nocheck -permissive
VHDL	Single	-check_synthesis -lint -rangecheck -pedanticerrors
Verilog/SystemVerilog	Global	None
Verilog/SystemVerilog	Dependencies	-permissive
Verilog/SystemVerilog	Single	-lint -pedanticerrors -hazards

• GHDL

Language	Scope	Flags
VHDL	Global	-fexplicit -frelaxed-rules
VHDL	Dependencies	None
VHDL	Single	None
Verilog	N/A	N/A
SystemVerilog	N/A	N/A

• XVHDL

XVHDL has no default flags set.

Environment variables

HDL_CHECKER_DEFAULT_PROJECT_FILE

Default file name HDL Checker looks for.

Default .hdl_checker.config (Linux/Mac), _hdl_checker.config (Windows)

HDL_CHECKER_WORK_PATH

Name of the temporary folder HDL Checker creates and uses as scratch pad.

Default .hdl_checker (Linux/Mac), _hdl_checker (Windows)