A disciplined project directory structure will help keep a large Quartus/ Modelsim project organized, keep source and test files easily accessible, increase the portability of a design, and minimize the chance of accidentally duplicating files. Quartus, Modelsim, and various IP components all generate a massive number of miscellaneous files that can bloat a directory and make it difficult to find important files.
The project directory structure given here serves as a reference for structuring your own projects to avoid many common problems.
Posted below is a EEC 180 Modelsim/Quartus video tutorial with a focus on file organization. Note that the text editor used in the video is Atom, which is not commonly used. The video was created by a former EEC 180 TA, Mark Hildebrand.
A top level folder is used as the root of the entire design. The folder should be named something meaningful for the design. Basic subdirectories include:
hdl/ test/ synthesis/ simulation/ ip/
Each of these are briefly described below. Other items that may appear in the top directory include a README, a Makefile, code used to generate Verilog source code etc.
The HDL directory is where all hardware Verilog source *.v files to be used for synthesis belong. (NOTE, testbench files should not be placed here.) If a design is very simple, this directory can be flat (i.e. no subdirectories). However, as projects become more complicated, you may find it beneficial to start structuring your code hierarchically into subdirectories.
Practical note: When System Builder generates a project, all of the generated files are in the same directory. The first thing I do is build a skeleton for the directory structure given here and move the System Builder generated files into their respective locations. This involves changing where the Quartus project is looking for its top level Verilog file, but this is easily fixed by linking the correct file in Quartus.
All Verilog testbenches for the design go into the "test" folder. This serves two purposes. First, it clearly separates the files used for synthesis from the files used for simulation. Since test bench files always contain unsynthesizable Verilog constructs (e.g., "#" delays), this separation minimizes the possibility of accidentally adding a testbench file to the Quartus project. Second, by keeping the test files in a different location, the hierarchy of the synthesis code is easier to read for both you and for anyone reviewing your code.
The structure of the subdirectories in this folder should be similar to the "hdl" folder.
The main file in here is the Modelsim project file (.mpf). Since Modelsim generates some intermediate files, keeping the modelsim project in its own directory ensures that these intermediate files don't mix with your source or test files. This makes your source and test files much easier to find.
This is where the Quartus project lives. Files that belong here include the .qpf, .sdc, and .qsf files generated by System Builder. Like Modelsim, Quartus also generates intermediate files, so putting it in its own directory keeps the source "hdl" directory clean.
Files related to any IP components used in your design go in this directory. I usually try to keep one subdirectory per IP component. Note that both synthesis and simulation may require items in here, and this is fine. By keeping the IP separate from regular source files, the distinction between the two is clearly delineated.
Avoid naming any files or directories with spaces in their names. For example, use "lab2" instead of "lab 2".
Written by Mark Hildebrand 2020/04/15 Added Filename Convention section 2020/04/09 A variety of edits for increased clarity (BB) 2018/06/11 Minor edits (BB) 2017/05/01 Written (MH)