Example GitLab Project#

Warning

Outdated Documentation! This documentation version is out of date. Please check the latest version 2026.1.

An example Hog-handled repository is available at hog-cern/hog-examples.

Clone the Repository#

To clone the repository, run the following commands in a terminal:

mkdir Workdir
cd Workdir
git clone --recursive https://gitlab.com/hog-cern/hog-examples.git

Repository Structure#

~/Work/Hog/hog-examples/ [main] tree -L 1
.
├── BD                     # Vivado Block Design Folder
├── diamond                # Lattice Diamond HDL source files
├── dlx                    # GHDL project's source files
├── example_max10          # Quartus project's source files
├── Hog                    # Hog Submodule
├── hog-commands           # Custom Hog's commands
├── IP                     # Vivado/Quartus IP Folder
├── IP_repository          # Vivado User IP Repository
├── README.md              # Readme file
├── sources                # Vivado/Libero HDL sources
├── Top                    # Hog Top Project Folder
└── vpk120                 # Versal HDL soures

The repository contains several example Hog projects for different IDEs, and it is already set up to run Hog-CI. Inside the Top folder, projects are grouped by IDE:

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/
Top
├── diamond               # Diamond Projects
├── ghdl                  # GHDL Projects
├── ise                   # ISE/PlanAhead Projects
├── libero                # Libero Projects
├── quartus               # Quartus Projects
├── repo.conf             # Hog Repository Configuration File
└── vivado                # Vivado Projects

Vivado Projects#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/vivado
Top/vivado
├── abacus      # Digilent Basys3 Abacus Project
├── bd_design   # Project with a block design (.bd file)
├── bd_tcl      # Block design created using BD/bd.tcl script
├── fifo        # Project containing an IP block (.xci)
├── microblaze  # Block design with MicroBlaze processor, created using post-creation.tcl
├── proj.1      # Variant of the fifo project using Hog Flavour feature
├── proj.2      # Variant of proj.1 with flavour number set to 2
└── vpk120      # Example Versal project

To run a Vivado project, ensure Vivado 2022.2 is in your path. To use a different version, modify the first line of the corresponding Top/vivado/<proj>/hog.conf file.

To create a Vivado project (e.g., abacus), run:

./Hog/Do CREATE vivado/abacus

This will create the project in Projects/vivado/abacus/abacus.xpr. You can open it with the Vivado GUI or run the workflow from the command line:

./Hog/Do WORKFLOW vivado/abacus

This approach applies to all other projects. Check the Hog console logs to better understand the workflow.

Quartus Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/quartus
Top/quartus
└── example_max10 # Project with a simple counter, PLL .qip file, and .qsys files

To run the project, ensure Quartus 23.1 is in your path. To create and build the project:

./Hog/Do CREATE quartus/example_max10
./Hog/Do WORKFLOW quartus/example_max10

You can also open the project in the Quartus GUI. The project file is located at Projects/quartus/example_max10/example_max10.qpf.

Libero Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/libero
Top/libero
└── example_libero # Project with a simple adder and FIFO IP created via post-creation.tcl

To run the project, ensure Libero SoC 2022.2.0.10 is in your path. To create and build the project:

./Hog/Do CREATE libero/example_libero
./Hog/Do WORKFLOW libero/example_libero

You can also open the project in the Libero GUI. The project file is at Projects/libero/example_libero/example_libero.prjx.

ISE/PlanAhead Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/ise
Top/ise
└── example_planAhead

To run the project, ensure ISE 14 is in your path. To create and build the project:

./Hog/Do CREATE ise/example_planAhead
./Hog/Do WORKFLOW ise/example_planAhead

You can also open the project in the ISE GUI. The project is stored in Projects/ise/example_planAhead.

Diamond Project#

➜  hog-examples git:(ghdl) ✗ tree -L 1 Top/diamond
Top/diamond
└── example_diamond

To run the project, ensure Diamond 3.14 is in your path. To create and build the project:

./Hog/Do CREATE diamond/example_diamond
./Hog/Do WORKFLOW diamond/example_diamond

You can also open the project in the ISE GUI. The project is stored in Projects/diamond/example_diamond.

GHDL Project#

~/Work/Hog/hog-examples/ [main] tree -L 1 Top/ghdl
Top/ghdl

To simulate the project with GHDL, ensure GHDL is in your path and tcllib is installed. To run the simulation:

./Hog/Do SIM ghdl

Continuous Integration#

Hog-CI is set up for this repository using static pipelines. See the .gitlab-ci.yml for configuration details. This main configuration file includes the individual CI configuration YAML files for each project. For example:

include:
  - local: 'Top/vivado/fifo/gitlab-ci.yml'

This includes the configuration for the vivado/fifo project. Each individual configuration file specifies which jobs will be run. For example, for the vivado/fifo project:

GEN:vivado/fifo:
    extends: .generate_project
    variables:
      extends: .vars
      PROJECT_NAME: vivado/fifo

SIM:vivado/fifo:
    extends: .simulate_project
    variables:
      extends: .vars
      PROJECT_NAME: vivado/fifo

The main .gitlab-ci.yml also contains global variable settings, which are propagated to each stage. These variables can be overwritten in the variables section of each job configuration.

Note

Variables set in the GitLab CI/CD settings of the repository cannot be overwritten in the YAML configurations.

This setup results in build and simulation jobs being run in the CI. You can see an example pipeline at this link.

Dynamic CI#

A merge request is open in the repository to configure Hog-CI using the dynamic GitLab CI/CD feature. See the updated .gitlab-ci.yml for a simpler and more flexible configuration.