Skip to content

Starting HAL

Jump to bottom
julianspeith edited this page Aug 17, 2026 · 18 revisions

Once built, HAL can be started either in GUI mode or as a pure command line tool. At the beginning, we recommend using the HAL GUI to get a better feeling for the tool. Using HAL as a command line application may become relevant for performance-critical applications, as the GUI may incur significant overhead.

The HAL executable is located in the bin folder of your build directory, so all commands below assume you are in build/bin (or that you have added it to your PATH).

Starting HAL in GUI mode

To start the HAL GUI, navigate to the executable (usually located in build/bin), type

./hal -g

into the command line, and press ENTER. Most other command line options will be ignored when starting the GUI, since their functionality is provided by the GUI instead. If the resolution of the HAL GUI appears to be off, try prepending QT_AUTO_SCREEN_SCALE_FACTOR=1 when invoking HAL in GUI mode. In that case, type

QT_AUTO_SCREEN_SCALE_FACTOR=1 ./hal -g

into the command line, and press ENTER.

You can optionally hand a netlist or an existing project to the GUI right away:

./hal -g -p path/to/my_project        # open an existing HAL project
./hal -g -i design.v -gl XILINX_UNISIM.hgl   # import a netlist into a new project

If -g is not recognized, the GUI plugin was not built — the option is contributed by the GUI plugin itself, not by the HAL core. See Building HAL.

You can now refer to "Using HAL" for an introduction to using HAL in GUI mode.

Starting HAL in command line mode

Running HAL solely using its command line interfaces may be useful when executing dedicated plugins that analyze the netlist without requiring user interaction. This way, such plugins can easily be run on a server or cluster that does not provide a GUI.

Note that HAL always operates on a project (see Using HAL). You therefore either import a netlist into a new project (-i), open an existing project (-p), or create an empty one (-e).

General options

  • -h, --help displays information regarding the usage of HAL, including all options contributed by plugins.
  • -v, --version displays the current version of HAL.
  • --licenses shows the licenses of open-source projects used within HAL.

Project and netlist options

  • -i, --import-netlist specify the netlist file that is then imported into a new project. This can be either a .hal file or of any netlist file format that is supported by the available netlist parsers.
  • -p, --project-dir provide the path to the project that should be loaded.
  • -gl, --gate-library specify the gate library that should be used to instantiate the netlist. You can pass either a full path to a gate library file, or just its file name (e.g. XILINX_UNISIM.hgl), in which case HAL searches its default gate library directories, see Gate Library Files. If this option is omitted on import, HAL tries every known gate library and picks one the netlist can be instantiated with — this works surprisingly often, but is slow and not always correct, so specifying the library explicitly is preferable.
  • -e, --empty-project create an empty project at the given path. Requires a gate library to be specified via -gl and cannot be combined with -i or -p.

If you pass -i without -p, the project directory is derived from the netlist file name.

Logging options

  • -l, --logfile specify a name and path for the log file that is created by HAL.
  • --log-time include time information in the log.
  • -L, --show-log-options show all logging options, e.g., to control the verbosity of individual log channels.
  • --no-log prevent HAL from creating a .log file at all.
  • --volatile-mode prevent HAL from writing a .hal progress file. Useful when running many analyses on a cluster where you do not want to persist intermediate state.

Plugin options

Plugins may register additional command line options. They only show up in hal -h if the respective plugin was built, which makes hal -h a convenient way to check which plugins are present in your build. The python_shell plugin, for example, contributes:

  • --python start an interactive Python shell.
  • --python-script run a Python script inside HAL and exit.
  • --python-args, --py-args supply arguments to the Python invocation. To provide multiple arguments, enclose them in quotes and separate them with spaces.

Note: these options hand control to the plugin before HAL opens a project of its own, so they cannot be combined with -p or -i — the Python shell starts up without a netlist and you load one yourself via hal_py.NetlistFactory. See Python Shell.

Examples

# import a Verilog netlist into a new project named "design"
./hal -i design.v -gl NangateOpenCellLibrary.hgl

# drop into an interactive Python shell (load the project from within it)
./hal --python

# run an analysis script; the script opens the project itself
./hal --python-script analyze.py --py-args "design"

For scripted analyses, the usual workflow is to open a project and drive HAL through the Python API — either via the python_shell plugin or through the Python editor inside the GUI. See Using HAL for a first walkthrough.

See also

  • Using HAL — importing a netlist and finding your way around once HAL is up
  • Python Shell — the --python route, in detail
  • GUI — the interface you land in without any options
  • Building HAL — getting there in the first place

Clone this wiki locally