# Working with an Existing Hog-Handled Repository This section is intended for developers who are starting to work with an existing HDL project managed by Hog. All the instructions below can be executed either in a Linux shell or in Git Bash on a Windows machine. :::{tip} To open a Git Bash session, navigate to the desired directory, right-click on the folder, and select "Open Git Bash here." ::: For all of the following steps to work, the Vivado (or Quartus/PlanAhead/Libero/Diamond) executable must be in your `PATH` environment variable. That is, if you type `vivado` in your terminal, the program should start. If you intend to use ModelSim, QuestaSim, Riviera, or another Xilinx-supported simulation software, the `vsim` executable must also be in your `PATH`. ## Requirements - Git (version 2.9.3 or greater) installed, and basic knowledge of git. - Vivado, PlanAhead, Quartus, Libero, Diamond or GHDL installed and in the `PATH`. - Libero, Diamond and GHDL require also `tcllib` to be installed in your system. - If using third-party simulators with Vivado, you also need to have `vsim` in the `PATH`. ## Cloning the Repository First, clone the repository (referred to as *repo* from now on). Go to the repository website, choose your preferred protocol (ssh, https, krb5), and copy the clone link. ```bash git clone --recursive ://gitlab.com/repo.git ``` Now you have all the source code and scripts you need in the *repo* folder. :::{note} Choose the *protocol* that works for you: ssh, https, or krb5. The `--recursive` option automatically clones all included submodules. While an HDL repository may or may not include other submodules, the Hog scripts are always included as a submodule. If you cloned the repository without the `--recursive` option (or if it did not work, which can happen on Windows), you will need to initialize and update the submodules manually: ```bash git submodule init git submodule update ``` ::: ## Creating IDE Projects To start working, create the IDE project you are interested in (let's call it *project1*). Navigate into the repository and run: ```bash ./Hog/Do CREATE project1 ``` This will create the project in the `Projects/project1` directory. Inside this directory, you will find the Vivado `.xpr` file (or the Quartus `.qpf` or PlanAhead `.xise` file). You can now open the project file with the GUI and synthesise/implement the project. :::{note} In 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 ensures that Hog generics are properly set. ::: If you do not know the project name, run `./Hog/Do LIST` to see a list of existing projects in the repository. To create all projects in the repository, you can run the Hog initialisation script: ```bash ./Hog/Init.sh ``` This script can also compile ModelSim/QuestaSim/Riviera libraries, add custom [Hog buttons](../02-User-Manual/01-Hog-local/02a-Hog-Buttons.md) to the Vivado GUI, and convert existing HDL projects to Hog. ## Adding a New File to the Project When you open *project1*, you can **work with the GUI (almost) as usual**. The `Hog/Do` script you ran has integrated Hog's Tcl scripts into the Vivado/PlanAhead/Quartus project. From now on, Hog scripts will run automatically every time you start the compilation workflow or any step in the workflow. In particular, the pre-synthesis script will interact with your local git repository and embed its version and git commit SHA into your HDL project. We say **almost as usual** because there is one exception: modifying the IDE project structure (e.g., changing project properties or adding/renaming project files). Adding a new file (HDL code, constraint, IP, etc.) to the project using the GUI is not enough. You **must also add** the file name to one of Hog's list files, as explained below. Suppose you want to add a new file located at `repo/dir1/file1.hdl`. First, add the new file (unknown to git) to the repository: ```bash cd repo git add ./dir1/file1.hdl git commit -m "Add new file file1.hdl" git push ``` Now that the file is safely on git, you need to add it to the Hog project so that other developers who clone the repository will see the file in their project. :::{note} Not all files in the git repository are part of a project: there can be non-HDL files, obsolete files, or new files not ready for use. Some files may be part of one project but not another. For example, the repository could contain `project2` and `project3`, each using different subsets of files. ::: This is a new file, unknown to Hog for now, and you want it to be included in the project the next time you run the `Hog/Do` script. To do this, add the file name and path of `file1.hdl` to a Hog list file. The list files are located in `repo/Top/project1/list/`. ### Manually Updating the List File Assume the list file you want to update is `lib1.src`. Open the file with a text editor and add the file name and path on a new line. Now that the new file is included in a list file, you can close the project and recreate it by running `./Hog/Do CREATE ` again. There is also a quicker option: add the file with the GUI **and** add it to a `.src` list file. If you do this in Vivado, make sure to select the correct library when adding the file. The library must have the same name as the `.src` file to which you added the source file. In our example, the HDL file was added to `lib1.src`, so the library to choose is *lib1*. You can select the library in the Vivado GUI from a drop-down menu when adding the file. This procedure is valid for any kind of source file. If your file is a constraint file, 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 (e.g., from `path1/f1.hdl` to `path2/f2.hdl`), do so and update the name in the appropriate list file. Don't forget to rename the file in git as well: ```bash git mv path1/f1.hdl path2/f2.hdl git commit -m "Renamed f1.hdl to f2.hdl" git push ``` #### Changing a Project Property If you change a project property in the GUI, make sure the change is propagated to the repository. To do this, modify the `hog.conf` file of the specific project and add or update the property. Generally, the easiest way is to copy and adapt what Vivado/Quartus/ISE writes in the Tcl console when you change the property. This helps you find the exact property name and value. For more details about the `hog.conf` file, see the [dedicated section](../02-User-Manual/01-Hog-local/01-conf.md) in the Hog manual. :::{tip} An easy way to check if you have modified `hog.conf` correctly is to close the project and recreate it using `./Hog/Do CREATE `. When you open the project again, verify that the property you modified is set as intended. ::: #### What Can Go Wrong? If you make a mistake (e.g., add a non-existent file, create a list file with an invalid extension, etc.), you will get an error when you run the `Hog/Do` script. Read Hog's error message and try to fix the issue. If you make a mistake with Vivado libraries or forget to update the list files, the error will appear at synthesis time because Vivado will not be able to find the component. ### Automatically Updating Hog Files :::{warning} This feature is currently only supported for Vivado. ::: Hog provides a Tcl script ([check_list_files.tcl](../02-User-Manual/01-Hog-local/06-Hog-utils.md)) to help manage list and `hog.conf` files. Users can work normally within the Vivado GUI, adding new files to projects (and selecting the proper library). Afterwards, they can automatically update the list and configuration files using the [Hog buttons](../02-User-Manual/01-Hog-local/02a-Hog-Buttons.md):  To check if the list files and `hog.conf` file are up to date, click the *CHK* button or run the following command (from a bash console): ```bash vivado -mode batch -notrace -source /Hog/Tcl/utils/check_list_files.tcl -tclargs -project ``` #### Automatically Update List Files To update the sources and constraint list files, click the Hog *LIST* button on the Vivado toolbar or run: ```bash vivado -mode batch -notrace -source /Hog/Tcl/utils/check_list_files.tcl -tclargs -project -recreate -force ``` :::{note} - New VHDL files will be added to `repo/Top//list/.src` - New constraint files will be added to `repo/Top//list/default.con` - Other files (Verilog, IPs, etc.) will be added to `repo/Top//list/default.src` ::: #### Automatically Update Simulations To update the simulation list files, click the Hog *SIM* button on the Vivado toolbar or run: ```bash vivado -mode batch -notrace -source /Hog/Tcl/utils/check_list_files.tcl -tclargs -project -recreate_sim -force ``` :::{note} This will update both the source files used for simulation and its properties. ::: ### Automatically Update `hog.conf` If you change a project property (e.g., synthesis or implementation strategy, maximum fanout), update the `hog.conf` file to ensure the modification is propagated to the repository. You can either click the *CONF* button on the Vivado toolbar or run: ```bash vivado -mode batch -notrace -source /Hog/Tcl/utils/check_list_files.tcl -tclargs -project -recreate_conf -force ``` ## Adding a New IP To add a new IP core (e.g., **my_ip1**), create it in out-of-context mode and save the `.xci` file (and only that) in a subfolder of your repository. Similarly, for Quartus, you can add the `.ip` file to your repository. If your target FPGA only supports `.qip` files (e.g., Intel Max10 FPGAs), you must add the folder in which the IP was generated to your project. :::{note} You can store IPs anywhere in your repository. ::: For example: `repo/some_folder/my_ip1/my_ip1.xci`. Pay particular attention to the `.gitignore` file. When Vivado synthesises IPs, it creates many additional files where the `.xci` file is located. To avoid committing these files to the repository, use a `.gitignore` file. :::{note} Every file that is not a `.xci` file inside the directory containing the IP must be ignored by git. ::: This can be specified in a global `.gitignore` file or in local `.gitignore` files in each directory used to store IPs. The `.gitignore` file provided in Hog templates assumes you are storing your IPs in a single directory called `IP` at the root of your repository. Once the IP is created and added to the repository, add the `.xci` file to any source list file in the `list` folder of your project. ### IP Initialization Coefficient Files (.coe, .mif) If you have a `.coe` or `.mif` file for RAM initialization, you can store it anywhere in the repository. Be sure to specify the path to this file as a **relative path** when customizing the IP. Additionally, the coefficient file must also be included in a Hog `.src` list file. :::{note} Browsing to the file location using the GUI will cause the absolute path to be loaded in the textbox. Be sure to replace this with a relative path. ::: The default `.gitignore` will tell git to ignore all files other than the `.xci` in the IP folder. To add your coefficient files to the repository, either exclude them in the `.gitignore` or store them in a different directory. ## A Few Things Before Getting to Work Here are a few details and suggestions that can be useful when working with a Hog-handled repository. ### Commit Before Starting the Workflow All Hog scripts handling version control are automatically added to your project, allowing you to create reproducible and traceable binary files—even when running locally. This will happen **only if you commit your local changes before running synthesis**. You don't have to push—just commit locally, then push when your work is ready. If you don't commit, Hog will alert you with a Critical Warning at the beginning of synthesis. ### Different List Files As explained above, source files from different list files will be added to your project in different "libraries": the name of each library is the name of the list file. When working with components from different list files, you need to formally include the libraries and reference the component from its library. For example, in VHDL: ```vhdl library lib1; use lib1.all; ... u_1 : entity lib1.a_component_in_lib1 port map( clk => clk, din => din, dout => dout ); ``` If working within the same library, you can use the "work" library