# 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 Project

```console
~/Work/Hog/hog-examples/ [main] tree -L 1 Top/vivado-vitis
Top/vivado_vitis
└── classic_zynqmp  # Example Vivado and Vitis Classic project for ZYNQ MPSoC
```

To run the projects, you need to have Vivado 2022.2 and Vitis 2022.2 available in your path. If you wish, to run another Vivado version, simply modify the first line of the corresponding `Top/vivado_vitis/<proj>/hog.conf` file. Note that Vivado Classic is not supported for versions after 2023.2.

Explore the content of each project, to well understand how Hog handles the different source files. To create a complete Vivado-Vitis project, e.g. for the `vivado_vitis/classic_zynqmp` project, run the command below from the main path of your repository:

```console
./Hog/Do CREATE vivado_vitis/classic_zynqmp
```

This will create a folder `Projects/vivado_vitis/classic_zynqmp`, where the Vivado project `classic_zynqmp.xpr` will be created, and another folder `Projects/vivado_vitis/classic_zynqmp/vitis_classic` with the Vitis workspace.

Optionally, if you only want to create a Vivado project, run the command below from the main path of your repository:
```console
./Hog/Do CREATE vivado/vivado_vitis_zynqmp --vivado_only
```

Or similarly, if you only want to create a Vitis project, run the command below from the main path of your repository:
```console
./Hog/Do CREATE vivado_vitis/classic_zynqmp --vitis_only
```

You can then open the Vivado or Vitis projects with the respcective GUIs, or launching the Vivado synthesis and implementaition as well as the Vitis build workflow with the `Do` command:
```console
./Hog/Do WORKFLOW vivado_vitis/classic_zynqmp
```
Optionally, if you only want to build the Vitis project, run the command below from the main path of your repository:
```console
./Hog/Do CREATE vivado/vivado_vitis_zynqmp --vivado_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.