# How are Vivado's projects directories structured?

I'm working with Vivado to program FPGA's in VHDL. Can someone explain me what are the various directories that are created under the project's directory?

In my projects, the following folders are created:

• [project_name].cache
• [project_name].hw
• [project_name].ip_user_files
• [project_name].runs
• [project_name].sim
• [project_name].srcs

I want to use git to manage the projects, so I need to know what each directory consists of as I want to ignore the ones with compiled files.

• It's a secret, and if you ever figure it out, Xilinx will change it... – Dave Tweed Mar 5 '19 at 23:35
• I tend to keep source files in a separate directory one level up from the Vivado project. Then out of those directories normally the only thing I care about are the .xci and select .bd files in [project_name].srcs – ks0ze Mar 6 '19 at 14:00
• FYI, here's Xilinx's gitignore file if you want to use it as a starting point. I definitely doesn't cover everything though xilinx.com/support/answers/61232.html – ks0ze Mar 7 '19 at 12:56
• @ks0ze That's what I do. How sweet it is. – DKNguyen May 18 at 14:15

## 2 Answers

Don't add the project itself to git; instead add some sort of script to generate the project and required IP cores. There are all sorts of issues you'll run in to if you commit the actual project, the least of which being absolute paths in various places, not to mention a hard version dependence on Vivado. It should be possible to have Vivado export a TCL script to generate the project, so just commit that and use it to regenerate the whole project. Alternatively, it is possible to use some other build framework such as make or cmake to write out TCL scripts and run them in Vivado to do much the same thing.

Here is how I usually do it with makefiles:

vivado.mk that the above makefile includes: https://github.com/alexforencich/verilog-ethernet/blob/master/example/VCU118/fpga_10g/common/vivado.mk

• I like the approach you are suggesting, but because I don't know how the project is structured I think I wouldn't be able to do that. I've never used TCL either. If you could expand your answer it would be very useful! – MPA95 Mar 6 '19 at 0:50
• Oh.. the topic is actually an unsolved mystery and Xilinx have continued to keep it top secret till now... However some of Xilinx's loyal users have tried to put it all together here. Please have a look at some of the answers. It is not foolproof, but will give you a very good idea of how to go about it using TCL. – Vinay Madapura Mar 6 '19 at 9:37
• Xilinx themselves had published an appnote about using Vivado with a VCS, specifically git. Since publishing, I don't think they've changed their structure too dramatically. Having never used this path, I don't have sufficient understanding to distill this entire document into an Answer. – Kevin Kruse Mar 6 '19 at 14:07
• Actually, this appnote is more recent and step-by-step. – Kevin Kruse Mar 6 '19 at 14:08
• I can't say I've had problems with absolute paths in a long time with the Vivado project file. They tend to store both absolute and relative for everything now with relative being given priority. Also, I don't see a problem with enforcing a hard version dependency since IP blocks occasionally change between versions the user should have to take the extra step to change versions to ensure they aren't breaking anything – ks0ze Mar 7 '19 at 13:00

If I remember correctly... To check your vivado project into GIT, you only need to check in the following:

    [project_name].xpr      #VIVADO PROJECT FILE
[project_name].srcs/*   #CONTAINS ALL SOURCE: *.vhd, *.sv, *.v, *.bd, *.xci
[project_name].sdk/*    #CONTAINS ALL ZYNQ SOURCE: *.c *.h, etc...


All other directories and files under the vivado project directory are temporary and intermediate files that the compiler will recreate when you start the vivado project:

\$ start vivado [project_name].xpr


Below is my clean script to to cleanup vivado project directory before git check in. (Please, backup your project directory before running this script because i'm not 100% sure its always safe... Xilinx doesn't actually document which files and directories are safe to delete, and I had to learn this from trial and error.)

from vivado project directory run:

   rm -rf *.cache
rm -rf *.runs
rm -rf *.sim
rm -rf *.hw
rm -rf *.ip_user_files
rm -rf *.jou
rm -rf *.log
rm -rf *.str


Vivado always insists on copying your source files out of your source directory tree into the vivado project tree... which usually has the effect of messing up your ability to organize your source code and forces you to check in your vivado project instead...you just need to just give into letting vivado manage your source code and git directory structure...)

(The other vivado solution to this problem is to always recreate your project file from a tcl script and keep throwing away your project file everytime you want to update your source code... keep in mind you need to start vivado from a sub-shell if you do that because vivado likes to kill its calling shell on an error, effectively killing your script that called it... for a windows batch file "cmd /c vivado -mode tcl name_of_script.tcl"...)