Example GitLab Project#
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.
Vivado-Vitis Projects#
Hog supports two Vitis flows: Vitis Classic and Vitis Unified. Both integrate with Vivado to build FPGA designs with embedded software applications.
~/Work/Hog/hog-examples/ [main] tree -L 1 Top/vivado_vitis
...
Top/vivado_vitis
├── classic_zynqmp # Example Vivado + Vitis Classic project for ZYNQ MPSoC
└── unified_zynqmp # Example Vivado + Vitis Unified project for ZYNQ MPSoC
...
Vitis Classic#
Vitis Classic uses the XSCT Tcl shell. To run the project, you need Vivado and Vitis Classic (2022.2 or compatible version) available in your path. Modify the first line of Top/example_vivado_vitis_classic_zynqmp/hog.conf to match your installed version. Note that Vitis Classic is officially deprecated as of version 2025.1, replaced by the Vitis Unified IDE.
To create the full Vivado + Vitis Classic project:
./Hog/Do CREATE example_vivado_vitis_classic_zynqmp
This creates a Vivado project in Projects/example_vivado_vitis_classic_zynqmp/ and a Vitis Classic workspace in Projects/example_vivado_vitis_classic_zynqmp/vitis_classic/.
Vitis Unified#
Vitis Unified uses the new Vitis CLI Python API. To run the project, you need Vivado and Vitis Classic (2024.2 or compatible version) available in your path. Modify the first line of Top/example_vivado_vitis_unified_zynqmp/hog.conf to match your installed version.
To create the full Vivado + Vitis Unified project:
./Hog/Do CREATE example_vivado_vitis_unified_zynqmp
This creates a Vivado project in Projects/example_vivado_vitis_unified_zynqmp/ and a Vitis Unified workspace in Projects/example_vivado_vitis_unified_zynqmp/vitis_unified/.
Common Options for Both Flows#
Optionally, if you only want to create the Vivado project (without the Vitis workspace):
./Hog/Do CREATE example_vivado_vitis_classic_zynqmp --vivado_only
./Hog/Do CREATE example_vivado_vitis_unified_zynqmp --vivado_only
Or, if you only want to create the Vitis project (requires an existing XSA or a pre-synth XSA will be generated):
./Hog/Do CREATE example_vivado_vitis_classic_zynqmp --vitis_only
./Hog/Do CREATE example_vivado_vitis_unified_zynqmp --vitis_only
You can then open the Vivado or Vitis projects with the respective GUIs, or run the full synthesis, implementation, and Vitis build workflow with the WORKFLOW command:
./Hog/Do WORKFLOW example_vivado_vitis_classic_zynqmp
./Hog/Do WORKFLOW example_vivado_vitis_unified_zynqmp
Optionally, if you only want to build the Vitis applications (without re-running Vivado synthesis/implementation):
./Hog/Do WORKFLOW example_vivado_vitis_classic_zynqmp --vitis_only
./Hog/Do WORKFLOW example_vivado_vitis_unified_zynqmp --vitis_only
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.