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

Converting an existing project to Hog involves copying your source files into a git repository, adding Hog as a submodule, creating Hog list files (text files containing the names of your source files), and writing a `hog.conf` file to store the project's properties.

## Before You Start

This guide assumes you are starting from a clean repository and want to convert a Vivado project stored in a local folder.

If you are migrating to Hog without changing repositories, you can follow these instructions but skip the creation of a new local repository. In this case, consider working in a new branch.

Suppose your new repository is called `new_repo` with URL `new_repo_url`, your project is named `myproject`, and it is currently stored in a local folder `mypath`. If you do not have a new repository, create one on GitLab.

## Creating the Git Repository

First, create a new folder for your HDL design, initialize it as a git repository, and connect it to the remote repository:

```bash
mkdir new_repo
cd new_repo
git init
git remote add origin <new_repo_url>
```

Here, `<new_repo_url>` is the URL to your new empty repository. You can obtain this URL from your GitLab server after creating a new repository.

By default, you will work on the `master` branch. If you prefer, you can create and switch to a new branch:

```bash
git checkout -b first_branch
git push origin first_branch
```

## Add Hog to Your Project

Hog should be included as a submodule in the root of your repository. To do this, run:

```bash
git submodule add ssh://git@gitlab.com:7999/hog-cern/Hog.git
```

If you prefer `https`:

```bash
git submodule add https://gitlab.com/hog-cern/Hog.git
```

Or for `krb5`:

```bash
git submodule add https://:@gitlab.com:8443/hog-cern/Hog.git
```

However, it is recommended not to include the protocol explicitly, but to let it be inherited from the parent repository. To do this, edit the `.gitmodules` file with your preferred text editor:

```bash
vim .gitmodules
```

Modify the URL value to use a relative path, for example:

```
[submodule "Hog"]
  path = Hog
  url = ../../hog-cern/Hog.git
```

If your repository is stored on `gitlab.cern.ch`, the URL should be:

```
  url = ../../hog/hog.git
```

Now update the submodule:

```bash
git submodule update
```

This will trigger an error if the repository path is incorrect.

## Copying Templates from Hog and Committing

Now that you have Hog locally, you can start setting up your repository. Hog provides templates you can use. For example, to add a `.gitignore`:

```bash
cp Hog/Templates/gitignore .gitignore
```

:::{note}
You may need to modify your `.gitignore` file if you have a more complex directory structure, especially for IP and BD files. The Hog template assumes IPs are stored in `IP/ip_name/ip_name.xci`. Adjust as needed for your setup.
:::

Make your first commit:

```bash
git add .gitignore .gitmodules Hog
git commit -m "Add Hog to the repository"
git push origin master
```

If you are working in a branch other than `master`, replace the last command with:

```bash
git push origin your_branch_name
```

## Early Tagging of Your Repository

Hog assumes that at least one version tag of the form **vM.m.p** is present in your repository. Create the first Hog tag:

```bash
git tag -m "First version" v0.0.1
git push --tags
```

The tag message is necessary to prevent git from creating a lightweight tag.

## Convert Your Project to Hog

### Automatic Conversion

:::{warning}
This feature is currently only supported for Vivado.
:::

If you want to integrate your project(s) within the Hog framework without modifying your directory structure, you can do so almost automatically. Copy your entire directory content, including the Vivado project, into the new repository:

```bash
cp ../old_repo/* .
```

:::{warning}
If your project contains submodules, do not copy them from the original repository. Instead, add them as submodules. See the [submodules](#submodules) section for details.
:::

Now, run the `Init.sh` script:

```bash
./Hog/Init.sh
```

This script scans for all non-Hog Vivado projects in your directory and (optionally) converts them into Hog projects. It automatically creates a `Top` directory, with one subdirectory for each Vivado project converted. Inside each, you'll find a `hog.conf` file and a `list` subdirectory.

Your old Vivado project(s) are now obsolete and should be deleted.

Commit your project files (e.g., Top directory, source files, IPs[^IPs], etc.):

[^IPs]: IP files require special care. See the [IPs](#intellectual-properties-ip) section for details.

```bash
git add Top
git add path_1/file_1.vhd
git add path_2/file_2.xdc
git add path_3/file_3.xci
git commit -m "Add files to project"
```

To check for uncommitted files:

```bash
git status
```

:::{warning}
When copying your old directory, you may also copy many temporary files you don't want in your repository. Be careful to add only the necessary files. Proper `.gitignore` rules can help.
:::

Now you are ready to create your Hog project (stored in the `Projects` directory):

```bash
./Hog/Do CREATE myproject
```

### Manual Conversion

#### Generating the Hog Directory Structure

Create a directory structure similar to this:

![](../01-Getting-Started/figures/directory_structure_new.jpg)

A full description of each folder is in the [Hog User Manual](../../02-User-Manual/00-what-is-hog).

#### Top Folder

Every Hog-handled HDL repository must have a `Top` directory, which stores configuration files needed to create HDL projects. Each subdirectory inside `Top` (the **project top-directory**) represents an HDL project.

Create your project top-directory:

```bash
mkdir -p Top/myproject
```

Each project top-directory must contain a `list` subdirectory for Hog list files:

```bash
mkdir Top/myproject/list
```

A file named `hog.conf` must be in the project top-directory. Hog reads this configuration file to create a project.
This is a recap of what we have learned up to now:

- A `Top` folder must be in the repository
- Inside this folder, there is one subfolder for each project in the repository, called the project top-directory
- Inside each project's top-directory there is 1. a `list` subdirectory containing the list files 2. a `hog.conf` file;

For more advanced Hog features, additional files and folder are located in the `Top` folder, but we do not discuss them now for simplicity.

To create the project's `hog.conf` script, we will start from the template provided in the `Hog/Templates` folder:

```bash
cp Hog/Templates/hog_vivado.conf Top/myproject/hog.conf
```

Templates are provided for Vivado, PlanAhead, and Quartus: `hog_vivado.conf`, `hog_ise.conf`, and `hog_quartus.conf`.

Edit the configuration file as needed (e.g., FPGA name, synthesis/implementation strategies). The template contains comments to guide you.

Commit your changes:

```bash
git add Top
git commit -m "Add Hog Top folder"
```

:::{note}
Hog supports a complex subfolder structure. For example:

```bash
mkdir -p Top/subfolder/myproject
```

The resulting project name will be `subfolder/myproject`.
:::

#### Importing Source Files

Copy your source, simulation, and constraint files into the repository. Except for reserved directories (`Top`, `Projects`, `bin`), you can organize your files as you prefer.

For example, create a directory for your project files:

```bash
mkdir -p lib_myproject/source lib_myproject/simulation lib_myproject/constraint
cp ../old_repo/source_1.vhd lib_myproject/source
cp ../old_repo/source_2.v lib_myproject/source
cp ../old_repo/simulation_1.vhd lib_myproject/simulation
cp ../old_repo/simulation_2.v lib_myproject/simulation
cp ../old_repo/constraint_1.xdc lib_myproject/constraint
cp ../old_repo/constraint_2.tcl lib_myproject/constraint
```

Add the file paths to the appropriate list files. For example:

- `Top/myproject/list/myproject.src` for source files
- `Top/myproject/list/myproject.sim` for simulation files
- `Top/myproject/list/myproject.con` for constraint files

:::{note}
Paths in list files are relative to the repository root.
:::

You can add comments (lines starting with `#`) and empty lines in list files.

Check that files are correctly picked up by regenerating the Hog project:

```bash
./Hog/Do CREATE myproject
```

Open the created project in  `Projects/myproject/myproject.xpr` (or `.qpf` for Quartus) and verify all files are present. If not, update the list files and recreate the project. When satisfied, commit your work:

```bash
git add lib_myproject
git add Top/myproject/list/myproject.src
git add Top/myproject/list/myproject.sim
git add Top/myproject/list/myproject.con
git commit -m "Add source files"
```

#### Submodules

If your project uses files from another repository, add it as a git submodule:

```bash
git submodule add my_submodule_url
```

Add submodules wherever you like in your repository. Files from submodules must also be listed in a Hog list file.

#### Intellectual Properties (IP)

IP files can be stored anywhere in your repository or submodules. To avoid committing generated files, follow these rules:

- Each IP file (`.xci` for Vivado) must be in a subfolder named after the IP (excluding the extension).
- Only the IP file should be committed (e.g., `.xci` for Vivado, `.ip` for Quartus).
- Use a `.gitignore` file to ignore all non-IP files (a template is provided in `Templates`).

For each IP:

```bash
mkdir -p path_to_your_ips/ip_name/
cp ../old_repo/ip_name.xci path_to_your_ips/ip_name/
```

Add the `.xci` files to a `.src` list file (e.g., `IP.src`).

:::{note}
There is no concept of library for IPs, so it is common to use a separate `.src` file for them. You may also add them to your main source list file if you prefer.
:::

Check that files are picked up by regenerating the project:

```bash
./Hog/Do CREATE myproject
```

If satisfied, commit your changes:

```bash
git add path_to_your_ips
git add Top/myproject/list/IP.src
git commit -m "Add IP files"
```

If you have `.coe` or similar files for RAM initialization, add them to a `.src` list file and specify them with a relative path when customizing the IP.

## The Top Module of Your Project

Specify the top module with the property `top=top_module_name`. For example, if your top module is `mytop` in `mytop.vhd`, your list file would include:

```
# Example .src file
mytop.vhd top=mytop
...
```

:::{note}
If not specified, Hog uses `top_<project_name>` as the default top module.
:::

Hog provides a set of parameters/generics to your top module at synthesis. You should add these to your top module to store versioning information. See the [parameters/generics list](../02-User-Manual/01-Hog-local/03-parameters-generics.md) and [templates](../02-User-Manual/01-Hog-local/05-templates.md) for details.

## Code Documentation

Hog can help you document VHDL code by automatically generating and deploying documentation using [Doxygen](http://www.doxygen.nl/) version 1.8.13 or later.

If your code uses Doxygen-style comments, you can generate documentation by creating a `doxygen` directory containing the necessary files, including a `doxygen.conf` file. You can copy a template from `Hog/Templates/doxygen.conf` and modify it.