Some changes in section 01 and upgrading the packages

[^git_bash]: To open a git bash session navigate to the directory where you want to open the bash. Right click on the folder and select open git bash here.

For all of the following to work, Vivado (or Quartus) executable must be in your PATH environment variable: i.e. if you type `vivado` the program must run. If you intend to use Modelsim or Questasim, also the `vsim` executable must be in the PATH: i.e. if you type `vsim` the simulator should start.

For all of the following to work, Vivado (or Quartus or PlanAhead) executable must be in your PATH environment variable: i.e. if you type `vivado` the program must run. If you intend to use Modelsim or Questasim, also the `vsim` executable must be in the PATH: i.e. if you type `vsim` the simulator should start.

### Requirements

This is a list of the requirements:

- Optionally have Questasim installed and vsim in the PATH

### Cloning the repository

First of all, you have to clone the repository[^repository], let's call it *repo* from now on. Go to the website of the repository, choose the protocol (ssh, git, https, krb5) and copy the clone the link.

First of all, you have to clone the repository, let's call it *repo* from now on. Go to the website of the repository, choose the protocol (ssh, git, https, krb5) and copy the clone the link.

```bash

  git clone --recursive <protocol>://gitlab.cern.ch/repo.git

Now you have all the source code and scripts you need in the *repo* folder.

[^repository]: You will have to chose the *protocol* that works for you: ssh, https, or krb5. We used the `--recursive` option to automatically clone all the submodules included. In general a HDL repository may or may not include other submodules, but the Hog scripts are always included as submodules. If you have cloned the repository without the recursive options (or if that option does not work, we heard that it happens on Windows), you will have to go inside it and initialise the submodules `git submodule init` and update them `git submodule update`.

```{note}

You will have to choose the *protocol* that works for you: ssh, https, or krb5. We used the `--recursive` option to automatically clone all the submodules included. In general a HDL repository may or may not include other submodules, but the Hog scripts are always included as submodules. If you have cloned the repository without the recursive options (or if that option does not work, we heard that it happens on Windows), you will have to go inside it and initialise the submodules `git submodule init` and update them `git submodule update`.

```

### Create Vivado/PlanAhead/Quartus projects

To start working you can now create the Vivado/PlanAhead/Quartus project you are interested in, say it's called *project1*.

  ./Hog/CreateProject.sh project1

```

This will start a Hog script that creates the Vivado/PlanAhead/Quartus project in the directory `Projects/project1`.

inside this directory you will find the Vivado .xpr file (or the Quartus .qpf file).

This will create the Vivado/PlanAhead/Quartus project in the directory `Projects/project1`.

Inside this directory you will find the Vivado `.xpr` file (or the Quartus `.qpf` or the PlanAhead `.xise` files).

You can now open the project file with the GUI and synthesise/implement[^implement] the project.

You can now open the project file with Vivado/Quartus GUI and synthesise/implement[^implement] the project.

:::{admonition}

:class: note

[^implement]: Note that inside the Quartus GUI you must always run a full compile process after creating a new project, otherwise the synthesis process will fail. Due to the Quartus structure, only running the full compilation flow will ensure the Hog generics are properly set. 

Inside the Quartus GUI, you must always run a full compile process after creating a new project, otherwise the synthesis process will fail. Due to the Quartus structure, only running the full compilation flow will ensure the Hog generics are properly set.

:::

If you don't know the project name, just run `./Hog/CreateProject.sh` and you will get a list of the existing projects present on the repository[^Top].

If you do not know the project name, just run `./Hog/CreateProject.sh` and you will get a list of the existing projects present on the repository.

[^Top]: Alternatively, you can type `cd Top` (the Top folder is always present in a Hog handled HDL repository) and type `ls`: each directory in this path corresponds to a Vivado/PlanAhead/Quartus project in the repository.

:::{tip}

Alternatively, you can type `cd Top` (the Top folder is always present in a Hog handled HDL repository) and type `ls`: each directory in this path corresponds to a Vivado/PlanAhead/Quartus project in the repository.

:::

To create all the projects in the repository, you can run the Hog initialisation script, like this:

```bash

  git commit -m "add new file file1.hdl"

  git push

```

Now that the file is safely on git, we have to add it to the Hog project, so that if another developer clones the repository, as you did at the beginning of this guide, the file will appear in the project[^files].

Now that the file is safely on git, we have to add it to the Hog project, so that if another developer clones the repository, as you did at the beginning of this guide, the file will appear in the project.

[^files]:Not all the files stored in the git repository are part of a project: there can be non hdl files, obsolete files that are stored just in case, new files that are not ready to be used. Moreover some files could be part of a project and not of another. In our example, the repository could contain project2 and project3 that use different subsets of files in the repository.

```{note}

Not all the files stored in the git repository are part of a project: there can be non hdl files, obsolete files that are stored just in case, new files that are not ready to be used. Moreover some files could be part of a project and not of another. In our example, the repository could contain project2 and project3 that use different subsets of files in the repository.

```

This is a new file, unknown to Hog for now, and we want it to be included into the project the next time that we run the CreateProject script described above. To do this, you must add the file name and path of `file1.vhd` into a Hog list file. The list files are located in `repo/Top/project1/list/`.

Let's assume that the list file you want to add your file to is `lib1.src`.

Open the file with a text editor and add the file name and path in a new line.

Now that the new file is included in a list file, you can close the Vivado/Quartus project and re-create it by typing `./Hog/CreateProject.sh <project name>` again.

Now that the new file is included in a list file, you can close the project and re-create it by typing `./Hog/CreateProject.sh <project name>` again.

Do you really have to do this every time you add a new file to the project? There is a quicker way. You can add the file with the GUI and **also** add the file to a .src list file. If you choose to do this, in Vivado, you have to choose the correct library when adding the file. The library must have the same name of the .src file to which you added the source file. In our example, the hdl file was added to a list file called `lib1.src`, so the library that you have to choose is *lib1*. You can select the library in the Vivado GUI from a drop-down menu when you add the file.

This procedure is valid for any kind of source file. If your file is a constraint file, just add it to a .con list file in the list directory, e.g. `repo/Top/project1/list/lib1.con`.

##### Renaming a file already in the project

If you need to rename or move a file, say from `path1/f1.hdl` to `path2/f2.hdl` do so and change the name in the proper list file accordingly.

Don't forget to rename the file on git as well:

Do not forget to rename the file on git as well:

```shell

  git mv path1/f1.hdl path2/f2.hdl

Create a new branch, check it out and commit your code there. To avoid direct commit to the master (or official) branch, you can configure the repository to forbid pushing directly to the some special branch, for example master.

To do this go to Settings and then Repository on Gitlab webiste. Then expand Protected Branches and add the branches that you want to protect.

To do this go to Settings and then Repository on Gitlab website. Then expand Protected Branches and add the branches that you want to protect.

### Increasing version number

Hog uses a version of the form *vM.m.p*. Where M is the major version, *m* is the minor version and *p* is the *patch*.

# -- Project information -----------------------------------------------------

project = 'Hog'

copyright = '2018-2020 The University of Birmingham'

copyright = '2018-2021 The University of Birmingham'

author = 'F. Gonnella, D. Cieri, N. Giangiacomi, N. Biesuz, A. Camplani'

# The full version, including alpha/beta/rc tags

#release = ''

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be

myst_dmath_enable = True

myst_deflist_enable = True

myst_figure_enable = True

myst_enable_extensions = [

    "dollarmath", "amsmath", "deflist", "html_image", "colon_fence",

    "smartquotes", "replacements", "substitution", "colon_fence"

]

myst_url_schemes = ("http", "https", "mailto")

myst_heading_anchors = 2

panels_add_boostrap_css = False

## Introduction

Coordinating firmware development among many international collaborators is becoming a very widespread problem. Guaranteeing firmware synthesis with Place and Route **reproducibility** and assuring **traceability** of binary files is paramount.

Hog tackles these issues by exploiting advanced git features and integrating itself with HDL IDE (Vivado or Quartus). The integration of these tools intends to reduce as much as possible useless overhead work for the developers.

Hog tackles these issues by exploiting advanced git features and integrating itself with HDL IDEs (Vivado, PlanAhead or Quartus). The integration of these tools intends to reduce as much as possible useless overhead work for the developers.

:::{admonition} Quartus support

:class: warning

Not all Hog features are supported for Quartus. If a feature described in the documentation is supported only by Xilinx IDEs, it is clearly stated.

If some of the functions you are looking for are not cited in the documentation they might be [scheduled for development in a future release](https://gitlab.cern.ch/hog/Hog/-/issues)

:::

### What is Hog

Hog is a set of Tcl/Shell scripts plus a suitable methodology to handle HDL designs in a Gitlab repository.

The main features of Hog are :

- a fast way to maintain your HDL code on git

- to have automatic tagging for easy versioning

- a fast way to maintain your HDL code on git,

- automatic tag creation for easy versioning

- automatic Gitlab release creation

- a template to run a continuous integration in your Gitlab repository

- the possibility of creating multiple project sharing one top level

- to store the output binary files on EOS

- to work both with Windows and Linux

- the possibility to store the output binary files on EOS

- multi-platform compatibility, working both with Windows and Linux

Everything is as transparent as we could think of. Hog is designed to use just a small fraction of your time to set up your local machine and get you to work to the HDL design as soon as possible.

- HDL source files

- Constraint files

- Vivado/Quartus settings (such as synthesis and implementation strategies)

- IDE settings (such as synthesis and implementation strategies)

For **traceability**, every time we produce a binary firmware file, we must:

cd <HDL repository>

./Hog/CreateProject <project_name>

```

The project will appear in ./Projects/<project>  and you can open it with your Vivado (ISE/Quartus) GUI.

[^create_project]: If you don't know the project name, just run `./Hog/CreateProject` and a list will be displayed.

The project will appear in `./Projects/<project>`  and you can open it with your Vivado (ISE/Quartus) GUI.

:::{tip}

If you don't know the project name, just run `./Hog/CreateProject` and a list will be displayed.

:::

### What is in the Hog folder

The Hog folder contains plenty of Tcl and Shell scripts.

### Other folders that you need

A folder called `Top` shall be in the root of the repository and it contains a sub-folder for each Vivado/PlanAhead/Quartus project in the repository. Each of these directories has a fixed -easy to understand- structure and contains everything that is needed to re-create the Vivado/PlanAhead/Quartus project locally, apart from the source files[^source] that the developer can place in the repository at his/her own convenience.

[^source]:Source files are the HDL files (.vhd, .v) but also the constraint files (.xdc, .sdc, .qsf, .tcl, ...). The IP files (.xci, .ip, .qip, ...) and the Board Design files must be stored in special folders, as explained later.

```{note}

Source files are the HDL files (.vhd, .v) but also the constraint files (.xdc, .sdc, .qsf, .tcl, ...). The IP files (.xci, .ip, .qip, ...) and the Board Design files must be stored in special folders, as explained later.

```

### Hog user manual

In this website you can find a quick guide to learn how to work in a [Hog-handled repository](../../01-Getting-Started/01-howto-existingProjects) or to [set up a new one](../../01-Getting-Started/03-howto-update-hog), as well as a complete user manual to understand all the details and learn how to maintain a Hog-handled repository.

### Quartus support

Currently Hog provides a minimal Quartus support allowing you to create, compile and keep track of the versioning of a project both locally and in the gitlab CI/CD. 

Note that not all hog/quartus features are supported.

We tried to clearly state if a feature refers only to Xilinx FPGA.

If some of the functions you are looking for are not cited in the documentation they might be [scheduled for development in a future release](https://gitlab.cern.ch/hog/Hog/-/issues)

### Contacts

Would you like to have fun with git and a Tcl? Please join us and read the [Developing for Hog](../../04-Developing-for-Hog/01-contributing) section.

sphinx_copybutton

sphinx_togglebutton

sphinx_thebe

sphinx>=3.2.1

sphinx>=3.4.2