## List Files

Each top project folder must contain a `list` directory.
This directory holds the list files—plain text files that instruct Hog on how to build your project.
Each list file specifies the files to be added to the project.

You can also specify properties for each file by adding them after the file name, separated by spaces.
Comments can be added using `#`.
A typical list file looks like this:

```
source_dir/file1.vhd [prop_1] [prop_2]
# comment here, for example
source_dir/file2.vhd [prop_3]
source_dir/file3.vhd
```

Hog supports simple wildcards to specify source files. For example, the three files above could be added with:

```
source_dir/*.vhd [prop]
```

A property applied to a wildcard source file will be applied to all files matched by the wildcard.
Wildcards can be used in both the path and the filename, e.g. `*/src/*.vhd`.
During project creation, Hog will print a note listing the files found by wildcard expansion.
Currently, there is no way to exclude files from a wildcard (as with `.gitignore`), so ensure you are not adding unwanted files.

Hog uses different types of list files, identified by their extension:

- `.src` : Source files to be used in synthesis and implementation, or optionally for Vitis project builds when the .src file follows the naming convention "app_<app_name>.src".
- `.sim` : Files used only in simulation
- `.con` : Constraint files
- `.ext` : Source files that are not in the git-repository
- `.ipb` : IPBUS XML files

:::{note}
In `.src`, `.sim`, and `.con` list files, you must use paths relative to the repository root directory.
:::

---

### Source List Files (`.src`)

Hog creates an HDL library[^ise_library] for each `.src` list file and assigns all files included in the list file to that library.

For example, if there is a `lib_1.src` file in the list directory like this:

```
source_dir/file1.vhd
source_dir/file2.vhd
source_dir/file3.vhd
IP/ip1.xci
IP/ip2.xci
```

the files will be included in the Vivado project under the `lib_1` library.

To use them in VHDL[^library], use the following syntax:

```vhdl
library lib_1;
use lib_1.all;

...

u_1 : entity lib_1.a_component_in_lib1
  port map(
    clk  => clk,
    din  => din,
    dout => dout
  );
```

#### File Properties for Vivado Projects

For Vivado projects, the following properties can be specified for files in a `.src` list:

- `top=<top module name>`: Defines the top module of the project.
- `93`: (only for `.vhd` and `.vhdl` files) File type is VHDL 93. If not specified, Hog uses VHDL2008[^planahead].
- `nosynth`: File will not be used in synthesis.
- `noimpl`: File will not be used in implementation.
- `nosim`: File will not be used in simulation.
- `locked`: **ONLY FOR `.xci` FILES**. The IP will not be re-synthesized by the CI. See the [IP section](11-IPs.md) for details.
- `verilog_header` (**From Hog2022.1**): File type will be set to Verilog header.
- `SystemVerilog` (**From Hog2022.1**): File type will be set to SystemVerilog.
- `source` (**From Hog2022.1**): Only for Tcl files. The Tcl script will be sourced by Vivado. Also sets the `nosynth`, `noimpl`, and `nosim` properties.

[^planahead]: Note that VHDL2008 is not supported by PlanAhead/ISE synthesis tools.

#### File Properties for Quartus Projects

For Quartus projects, the following properties can be specified for files in a `.src` list:

- VHDL files:
  - `1987`: File type is VHDL 1987. If not specified, Hog uses the project default HDL version[^quartus_default].
  - `1993`: File type is VHDL 1993.
  - `2008`: File type is VHDL 2008.
- SystemVerilog files:
  - `2005`: File type is SYSTEMVERILOG 2005.
  - `2009`: File type is SYSTEMVERILOG 2009.
- Verilog files:
  - `1995`: File type is VERILOG 1995.
  - `2001`: File type is VERILOG 2001.
- Tcl macro files:
  - `qsys`: Indicates this file is used to generate an Intel Platform Designer system (`.qsys`).
- Intel Platform Designer system (`.qsys`):
  - `nogenerate`: Do not generate the system.

[^ise_library]: https://www.xilinx.com/support/documentation/sw_manuals/xilinx11/ise_c_working_with_vhdl_libraries.htm
[^library]: Libraries are ignored in Verilog and SystemVerilog.
[^quartus_default]: The Intel Quartus Prime default HDL version can be specified by adding a command in your `.qsf` file, e.g., `set_global_assignment -name VHDL_INPUT_VERSION VHDL_2008` in a `.tcl` listed in a `.con` list file. See the Quartus Prime scripting reference manual for details.

---

#### Intel Platform Designer Systems

Intel Platform Designer system files (`.qsys` or `.tcl`) must be added to `.src` list files.
You have several options for handling these files:

- If a `.qsys` file is listed, Hog tries to generate the system by running the `qsys-generate` command. Properties of the `.qsys` file are used as command options for `qsys-generate`. For example, to use VHDL for synthesis:

  ```
  <qsys_path>/<qsys_name>.qsys --synthesis=VHDL
  ```

  :::{note}
  Do **not** use the `--output-directory` option; Hog sets this automatically.
  :::

  The system is generated in a folder with the same name and path as the `.qsys` file.
  After generating the IP variations, Hog automatically finds and adds the generated `.ip`, `.qip`, `.v`, and `.vhdl` files to the project.

  :::{note}
  All information about the qsys system generation is logged in `<qsys_path>/<qsys_name>.qsys-generate.log`.
  :::

- To add a `.qsys` file without generating the IP variation, specify the `nogenerate` option. In this case, Hog will not automatically add IPs to the project; you must generate and list them manually.

- You can also use a dedicated `.tcl` macro to create or modify a system. List this file using the `qsys` property. Hog will run `qsys-script` to generate the `.qsys` file. The `.qsys` file will be generated in the same folder as the `.tcl` macro. Once generated, it is treated as if it was listed in a `.src` file—IPs are generated and added to the project.

  To pass options to `qsys-generate`, list them after the `qsys` property:

  ```
  <qsys_path>/<qsys_name>.tcl qsys --synthesis=VHDL
  ```

  :::{note}
  When using Tcl scripts for Intel Platform Designer system generation, both the `.qsys` file and the generated folder must be listed in `.gitignore`.
  :::

  :::{note}
  All information about the qsys system creation is logged in `<qsys_path>/<qsys_name>.qsys-script.log`.
  :::

---

### Simulation List Files (`.sim`)

Simulation list files enumerate all HDL files used only for simulation.
Starting from `Hog2025.2`, you can also include simulation configuration properties directly in the `.sim` file.

`.sim` files include testbenches and other files not used for synthesis.

For each `.sim` file in the `Top/<project>/list` folder, Hog creates a "simulation set".

A `.sim` file with simulation properties uses a TOML-like format. For example:

```
#Simulator xsim
[files]
myfile.vhd
mytb.vhd
[properties]
RUNTIME=10us
TOP=TB_fifo
[generics]
MYGENERIC=1
[hog]
HOG_SIMPASS_STR="simulation passed"
```

Alternatively, you can still specify simulation properties using the `sim.conf` file (deprecated in future Hog releases). In that case, the `.sim` file should include just the shebang and the list of simulation sources, without TOML headers:

```
#Simulator xsim
[files]
myfile.vhd
mytb.vhd
```

For more information about simulation and `.sim` files, see the [dedicated section](02b-Simulation.md).

---

### Constraint List Files (`.con`)

All constraint files must be included by adding them to `.con` files.
Both `.xdc` (Vivado), `.sdc`, `.qsf`, and `.tcl` files can be added here.

For Vivado, the `nosynth` and `noimpl` properties can be specified if required.

:::{note}
When creating a Quartus Prime Project, all `.qsf` and `.tcl` files included in a `.con` list file will be automatically sourced. This can be used to apply global project settings or include a pinout file. To add a Macro Library for design, create a dedicated `.src` list file.
:::

Example `.con` file:

```
constr_source_dir/constr1.xdc           # constraint used for synthesis and implementation
constr_source_dir/constr2.xdc nosynth   # constraint not used in synthesis
constr_source_dir/constr3.xdc noimpl    # constraint used in synthesis only
```

Starting from Hog2025.1, constraints can be scoped to a particular module or cell using the `scoped_to_ref=` and `scoped_to_cells=` properties in `.con` files. For example:

```
# Using the reference module name only
constr1.xdc scoped_to_ref=uart_tx_ctl
# Using the cell name only:
constr1.xdc scoped_to_cells=uart_tx_i0/uart_tx_ctl_i0
```

For more information on constraint scoping, see the [official AMD documentation](https://docs.amd.com/r/en-US/ug903-vivado-using-constraints/Constraints-Scoping).

---

### List Files Are Recursive

A list file can include another list file, whose content will then be included.

You can mix source files and list files; Hog recognizes them by their extension.

This feature is useful if multiple projects in the same repository share a subset of files.
A common list file can be created and stored anywhere in the repository, then included in specific project list files.

By default, when a list file is included recursively, Hog uses the file name of the **included** list file as the library name.
You can specify a custom name using the `lib` keyword as a property of the included list file. For example:

```
file_a.vhd
file_b.v
...

bar.src lib=my_library

...
```

Now Hog will set `my_library` as the library for all VHDL files in `bar.src`.


From Hog2025.1, you can also define a different reference path for the included list file using the `path=` property. This is useful when sharing a VHDL library in a submodule with a Hog list file, which can then be included in any project. For example:

```
my_submodule_list_file.src path=path/to/submodule
```

---

### External List Files (`.ext`)

External proprietary files that cannot be published in the repository should be included using a `.ext` list file.
This should be used **only** for files that cannot be published due to copyright.

The `.ext` list file has a special syntax: the MD5 hash of each file must be added after the file name, separated by one or more spaces:

```
/afs/cern.ch/project/p/project/restricted/file_1.vhd  725cda057150d688c7970cfc53dc6db6
/afs/cern.ch/project/p/project/restricted/file_2.xci  c15f520db4bdef24f976cb459b1a5421
```

You can obtain the MD5 hash by running:

```bash
md5sum <filename>
```

Or, in the Vivado or QuartusPrime Tcl shell:

```tcl
md5::md5 -filename <file name>
```

At synthesis time, Hog checks that all files are present and that their MD5 hash matches the one in the list file.

:::{admonition} Absolute or relative paths in `.ext` files?
:class: warning

`.ext` list files must use absolute paths or paths relative to `HOG_EXTERNAL_PATH`, if defined.
To use this in Hog-CI, the path must be accessible to the CI machine (e.g., on a protected `afs` folder).
:::

:::{note}
This feature is not implemented for Quartus projects.
:::


---
### View the list files of your project
You can view the content of the list files of your project by running the following command in your terminal:

```bash
./Hog/Do VIEW <project_name>
```

This will print the content of all the list files of your project in a tree format. For example:

```shell
(base) ➜  hog-examples git:(2026.1) ✗ ./Hog/Do VIEW Top/vivado/abacus
*********************************************************
*                 _  _            ___ __ ___  __   _    *
*  (\____/)      | || |___ __ _  |_  /  |_  )/ /  / |   *
*  / @__@ \      | __ / _ / _` |  / | () / // _ \_| |   *
* (  (oo)  )     |_||_\___\__, | /___\__/___\___(_|_|   *
*     ~~                  |___/                         *
*                                                       *
* Copyright 2018-2026  The University of Birmingham     *
* Documentation: https://cern.ch/hog                    *
* Register to our newsletter: http://cern.ch/go/nBn8    *
* Version: Hog2026.1                                    *
*********************************************************

INFO: [Hog:CheckLatestHogRelease] Checking for latest Hog release, can take up to 5 seconds...
INFO: [Hog:CheckLatestHogRelease] Latest official version is Hog2025.2-5, nothing to do.
INFO: [Hog:InitLauncher] Project vivado/abacus uses vivado IDE

abacus.src
├──sources/abacus/Adder_Subtractor.v
├──sources/abacus/Binary_to_BCD_B2_bcdout2.v
├──sources/abacus/Display_REM.v
├──sources/abacus/multi_4_4_pp1.v
├──sources/abacus/Seg_7_Display.v
├──sources/abacus/Basys3_Abacus_Top.v top=Basys3_Abacus_Top
├──sources/abacus/Binary_to_BCD_B_bcdout.v
├──sources/abacus/Divider.v
├──sources/abacus/multi_4_4_pp2.v
├──sources/abacus/Segment_Scroll.v
├──sources/abacus/Binary_to_BCD_B1_bcdout1.v
├──sources/abacus/Display_QU.v
├──sources/abacus/multi_4_4_pp0.v
└──sources/abacus/multi_4_4_pp3.v

abacus.con
└──sources/xdc/Basys3_Master.xdc

INFO: [Hog:Msg] All Done.
```