# Example GitLab Project

An example Hog-handled repository is available at [https://gitlab.com/hog-cern/hog-examples](https://gitlab.com/hog-cern/hog-examples).

## Clone the Repository

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

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

## Repository Structure

```console
~/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:

```console
~/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

```console
~/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:

```bash
./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:

```bash
./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.

```console
~/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:

```console
./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:

```console
./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):

```console
./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):

```console
./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:

```console
./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):

```console
./Hog/Do WORKFLOW example_vivado_vitis_classic_zynqmp --vitis_only
./Hog/Do WORKFLOW example_vivado_vitis_unified_zynqmp --vitis_only
```

### Quartus Project

```console
~/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:

```bash
./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

```console
~/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:

```bash
./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

```console
~/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:

```bash
./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

```shell
➜  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:

```bash
./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

```console
~/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:

```bash
./Hog/Do SIM ghdl
```

## Continuous Integration

Hog-CI is set up for this repository using static pipelines. See the [`.gitlab-ci.yml`](https://gitlab.com/hog-cern/hog-examples/-/blob/main/.gitlab-ci.yml?ref_type=heads) for configuration details. This main configuration file includes the individual CI configuration YAML files for each project. For example:

```yaml
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:

```yaml
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](https://gitlab.com/hog-cern/hog-examples/-/pipelines/1342176947).

### 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](https://gitlab.com/hog-cern/hog-examples/-/blob/main/.gitlab-ci.yml?ref_type=heads) for a simpler and more flexible configuration.