```{warning} Outdated Documentation! This documentation version is out of date. Please check the [latest version 2026.1](https://hog.readthedocs.io/en/latest/). ``` # Hog: HDL on git ## Introduction Coordinating gateware development among many international collaborators is becoming a very widespread problem. Guaranteeing gateware synthesis with Place and Route **reproducibility** and assuring **traceability** of binary files is paramount. [Hog](https://gitlab.com/hog-cern/hog) tackles these issues by exploiting advanced git features and integrating itself with HDL IDEs: **Xilinx Vivado**, **Xilinx ISE (planAhead)[^ise]**, **Intel Quartus[^quartus]**, **Microchip Libero[^tcllib]** and **Lattice Diamond[^tcllib]**. The integration with these tools intends to reduce as much as possible useless overhead work for the developers. [^quartus]: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 of the functions you are looking for are not cited in the documentation they might be [scheduled for development in a future release](https://gitlab.com/hog-cern/Hog/-/issues) [^ise]:Hog provides a minimal support for earlier generations of Xilinx chips using the planAhead tool. The planAhead GUI is very similar to Vivado and should be very familiar to Vivado users. Under the hood it still uses the same tools as ISE but provides a Tcl-scriptable front-end that allows for easy integration with Hog. It has been tested only in version 14.7 and has some limitations, but does allow you to create, compile and keep track of the versioning of a project both locally and in the gitlab CI/CD. [^tcllib]:Libero SoC and Lattice Diamond do not include a full version of the `tcllib` package, required by several functions in Hog. Developers must install `tcllib` on their machine, and set an environmental variable to tell Hog where to find the package. For Libero Hog does not provide support to core container files (e.g. `.xci` files in Vivado), so instead they must be generated by a Libero Tcl command which can be added to the Hog project using the `post-creation.tcl` file. If you want to be informed of any published Hog release, please register to our [Newsletter](http://cern.ch/go/nBn8). :::{tip} Hog is **completely free** and it's developed mainly as a pet project by Davide and Francesco. If you use it, please cite [our paper](https://iopscience.iop.org/article/10.1088/1748-0221/16/04/T04006/meta) in your articles and proceedings. Here's the [citation](hog.bib) in Bibtex format. ::: ### Waste no time thanks to Hog To work with a repository handled with Hog, you just need to clone it, run the Hog script and start working! The animated `gif` below, shows one of our [example projects](01-Getting-Started/04-Example-Project), have a look: ![hog example gif](hog.gif) ### What's new in Hog 2025.1? - Support to Lattice Diamond. - Pre-synthesis check for files in project and list files added to Libero and Diamond. - Support for pre-simulation scripts for all simsets or specific simset. - Added support for multiple IPbus list files. - IPBus list file extension renamed `.ipb`. - Added support for custom user command to be added to the `Hog/Do`. - Included list files can be added with a specific reference path (to include list files in submodules). - Hog passes now parameters and generics to IPs within a Vivado block design. - Option to save DCP checkpoints in Vivado synthesis and implementation, for incremental workflows. - Updated GitLab badge to new format. - Support to constraints scoping in Vivado. - Pulse Width Timing included in timing analysis in Vivado. - Option to add a project description in the `hog.conf` file, and hide test projects from list. - Support to VHDL2019 for compatible Vivado versions. ### What is Hog? Hog is a **set of Tcl/Shell scripts** plus a suitable **methodology** to handle HDL designs in a git repository. Hog is included as a git **submodule** in the HDL repository and allows developers to create the Vivado/PlanAhead/Quartus/Libero project(s) locally and synthesise/implement it or start working on it. Using Hog will help you to: - easily and effectively **maintain HDL code on git** - ensure that **code was not modified** before building binary files - ensure **traceability of binary files** (even if produced locally) - work both with **Windows and Linux** - **reduce code duplication** by making it easy to share code among projects - waste no time to setup **Continuous Integration** on Gitlab or **Github actions** on GitHub 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: ```console git clone --recursive cd ./Hog/Do CREATE ``` The project will appear in `./Projects/` 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: ```console ./Hog/Do CREATE ``` 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: ```shell ./Hog/Do WORKFLOW ``` 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: ```shell ./Hog/Do SIMULATE ``` runs the simulation workflow. Other scripts are stored inside the `Hog/Tcl` and `Hog/Other` directories, have a look if you're curious! :::{tip} Directives for the `Hog/Do` script can be shortened. For example `./Hog/Do L` will list the projects and `./Hog/Do C ` will create ``. ::: 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](../../04-Developing-for-Hog/01-contributing) section. To report a [problem](../../03-Report-Suggest/01-Report) or suggest a [feature](../../03-Report-Suggest/02-Suggest), use the git issues in the [Hog git repository](https://gitlab.com/hog-cern/Hog). Please check in existing and solved issues before opening a new one. For questions related to Hog, please get in touch with [Hog support](mailto:hog-group@cern.ch). For anything related to this site, please get in touch with [Davide Cieri](mailto:davide.cieri@cern.ch) Keep up to date with Hog's [Newsletter](http://cern.ch/go/Zh9s). ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Getting Started 01-Getting-Started/* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: User Manual 02-User-Manual/* 02-User-Manual/01-Hog-local/00* 02-User-Manual/02-Hog-CI/00* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Hog Tutorial at CERN Indico Agenda 07*/* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Bug Report and Suggestions 03*/* ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Developing for Hog 04*/* Hog Doxygen Develop Hog Doxygen Master ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: Releases 06*/* Hog Releases Hog Newsletter ``` ```{toctree} :maxdepth: 1 :hidden: :glob: :caption: License and Authors 05-License/* ```