# Example GitLab Project
```{warning} Outdated Documentation!
    This documentation version is out of date. Please check the [latest version 2026.1](https://hog.readthedocs.io/en/latest/).
```

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.

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