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[1] 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[2], use the following syntax:

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[3].
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 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.

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[4].
- 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.

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.

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.

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:

md5sum <filename>

Or, in the Vivado or QuartusPrime Tcl shell:

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.

Absolute or relative paths in .ext files?

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

./Hog/Do VIEW <project_name>

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

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

List Files

Contents

List Files#

Source List Files (.src)#

File Properties for Vivado Projects#

File Properties for Quartus Projects#

Intel Platform Designer Systems#

Simulation List Files (.sim)#

Constraint List Files (.con)#

List Files Are Recursive#

External List Files (.ext)#

View the list files of your project#

Source List Files (`.src`)#

Simulation List Files (`.sim`)#

Constraint List Files (`.con`)#

External List Files (`.ext`)#