Hog: HDL on git

Introduction

Coordinating gateware development among many international collaborators is increasingly common. Ensuring gateware synthesis with Place and Route reproducibility and guaranteeing traceability of binary files is essential.

Hog addresses these challenges by leveraging advanced git features and integrating with HDL IDEs: Xilinx Vivado, Xilinx ISE (PlanAhead)[1], Intel Quartus[2], Microchip Libero[3], and Lattice Diamond[3]. Hog also supports the open-source VHDL simulator GHDL. Integration with these tools aims to minimize unnecessary overhead for developers.

If you want to be notified about new Hog releases, please subscribe to our Newsletter.

Tip

Hog is completely free. It is developed by an international team of researchers from academia and industry (Author list). If you use it, please cite our paper in your articles and proceedings. Here is the citation in BibTeX format.

Waste no time thanks to Hog

To work with a repository managed by Hog, simply clone it, run the Hog script, and start working!

The animated GIF below shows one of our example projects:

What’s new in Hog 2026.1?

• New Hog/Do TREE command to display the file tree of a project. See here.

• Supporting boolean generics to your top module in hog.conf. See here.

• New HOG_FAIL_TIMING CI option to fail the CI if timing is not met. See here.

• Update Hog/Do SIGASI command to generate Sigasi project files compatible with new Sigasi Visual HDL VSCode extension. See here.

• Improved custom command support. See here.

• Possibility of running only some simulation sets in CI, using the new HOG_SIMSETS environment variable. See here.

• Add options to execute the Hog/Do SIMULATION command to generate only the simuataltion scripts, or the run the workflow only until the elabaration step. See here.

• New Hog/Do RTL command, to run the RTL analysis directive with Vivado. See here.

• Improve the GitLab CI workflow, by retrieving build artifacts from previous pipelines belonging to the same MR. See here.

• Add support to Vitis projects. See here.

• Improved coloured and logger features. See here.

What is Hog?

Hog is a set of Tcl/Shell scripts plus a robust methodology to manage HDL designs in a git repository.

Hog is included as a git submodule in the HDL repository and allows developers to create Vivado/PlanAhead/Quartus/Libero projects locally, synthesise/implement them, or start working on them.

Using Hog helps you to:

• Easily and effectively maintain HDL code on git

• Ensure that code is not modified before building binary files

• Guarantee traceability of binary files (even if produced locally)

• Work seamlessly on Windows and Linux

• Reduce code duplication by making it easy to share code among projects

• Save time setting up Continuous Integration on GitLab or GitHub Actions

Warning

Specific instructions for Windows users are available in the Instructions for Windows users section.

Thanks to Hog CI you will be able to:

• automatically tag your repository for semantic versioning

• automatically create releases on GitLab/GitHub (including timing and utilisation reports, changelog, and binary files)

• automatically add changelog in the release note (use the FEATURE: keyword in commit messages)

• Speed up IP synthesis by archiving synthesised blocks

• Archive the output binary files on a remote file system

Rationale

For synthesis and Place and Route (P&R) reproducibility, we need absolute control of:

• HDL source files

• Constraint files

• IDE settings

For traceability, every time we produce a binary file, we must:

• know exactly the source code that produced the binary files

• be able to go back to that point in the repository

To do this, Hog automatically embeds the git commit SHA into the binary file together with a more understandable numeric version M.m.p. Moreover, it automatically renames the file, including the version and inserts the hexadecimal value of the SHA so that it can be retrieved (using a text editor) in case files are renamed.

Hog aims to reduce to the minimum the time needed for an external developer to get up to speed to work on an HDL project. Hog does not rely on any external tool or library. Only git (at least 2.9.3) and on those tools you must already have to synthesise, implement (Vivado/PlanAhead/Quartus) and simulate (Modelsim/Questasim/Riviera) the design.

Tip

To start working on any project contained in a Gitlab repository handled with Hog, you just need to:

git clone --recursive <HDL repository>
cd <HDL repository>
./Hog/Do CREATE <project>

The project will appear in ./Projects/<project> and you can open it with your Vivado (ISE/Quartus) GUI. If you don’t know the project name, just run ./Hog/Do LIST and a list will be displayed.

What does Hog do?

The heart of hog is the Do script. For example you can type:

./Hog/Do CREATE <my_project>

to create locally the Vivado/PlanAhead/Quartus/Libero project locally into the Projects directory. When creating the project, Hog integrates a set of Tcl scripts (contained in Hog/Tcl/integrated) into the IDE software.

If you don’t want to use the graphical interface of the IDE, run:

./Hog/Do WORKFLOW <my_project>

and Hog will run the complete workflow of the desired HDL project, creating the binary files in the bin directory.

To simulate in batch mode, run:

./Hog/Do SIMULATE <my_project>

runs the simulation workflow.

./Hog/Do VIEW <my_project>

shows a tree of all the files in the selected project, like this:

  fifo.src
  ├──sources/top/top_fifo.vhd top=top_fifo
  ├──sources/src/adder.vhd 93
  └──IP/fifo_generator_0/fifo_generator_0.xci

  other_lib.src
  └──sources/src/different_adder.vhd

  fifo.con
  └──sources/xdc/ku.xdc

  second.sim
  └──sources/sim/tb_second.vhd

  fifo.sim
  ├──sources/sim/tb_fifo.vhd
  ├──sources/sim/TB_example_wave.do
  └──sources/sim/TB_example.udo

Tip

Directives for the Hog/Do script can be shortened.

For example ./Hog/Do L will list the projects and ./Hog/Do C <project> will create <project>.

To learn everything about the Hog/Do script, just type ./Hog/Do HELP.

Contacts

Are you a git enthusiast? And a Tcl fan? Join us and read the Developing for Hog section.

To report a problem or suggest a feature, use the git issues in the Hog git repository. Please check in existing and solved issues before opening a new one.

For questions related to Hog, please get in touch with Hog support.

For anything related to this site, please get in touch with Davide Cieri

Keep up to date with Hog’s Newsletter.

---

[1]

Hog provides minimal support for earlier generations of Xilinx chips using the PlanAhead tool. The PlanAhead GUI is very similar to Vivado and should be familiar to Vivado users. Under the hood, it uses the same tools as ISE but provides a Tcl-scriptable front-end that allows easy integration with Hog. It has been tested only with version 14.7 and has some limitations, but it does allow you to create, compile, and track project versions both locally and in GitLab CI/CD.

[2]

Not all Hog features are supported for Quartus. If a feature described in the documentation is supported only by Xilinx IDEs, it is clearly stated. If some functions you are looking for are not mentioned, they might be scheduled for development in a future release.

[3] (1,2)

Libero SoC and Lattice Diamond do not include a full version of the tcllib package, which is required by several Hog functions. Developers must install tcllib on their machine and set an environment variable to tell Hog where to find the package. For Libero, Hog does not provide support for core container files (e.g., .xci files in Vivado); instead, these must be generated by a Libero Tcl command, which can be added to the Hog project using the post-creation.tcl file.