Vivadoのプロジェクトフォルダがひどすぎる!
Xilinx（現AMD）のFPGA開発環境であるVivadoは、GUIで使っているとプロジェクトフォルダ以下にとにかく大量のファイルを生成してきます。しかも、特定のサブフォルダ以下にまとまっておらず、プロジェクトのルートに大量のログファイルを置いたり、ソースファイルと同じフォルダに生成物を大量に生成してきたり、とにかくめちゃくちゃです。
ソースコードはGitで管理したいのに、というかちゃんと管理しておかないと途中で分からなくなったり、戻したいときに正しく戻せなかったりと何かと不便です。
学生時代に、同じくXilinxのISEという開発環境を使っていた時も同じ状況でしたが、その時は明らかなログファイルを除いて全部addしていました。そのため、過去のコミットをさかのぼる必要が出たときに不要なファイルや差分が多数表示されて面倒でした。
先人たちもいろいろとノウハウを公開していただいていたり、何ならxilinx（現AMD）から手順が公開されていたりします。これらを参考に、自分なりのやり方を試行錯誤してみたので備忘録として残しておきます。
環境
- Windows 11
- Vivado 2024.1
実現したいこと
以下の通りやっていきます。
- Gitで管理する
- クローンしたらすぐに書き込むビットストリームをそのまま生成できる
- 自動生成できるものは管理しない（生成日時がファイルに書いてあったりして意味のない差分がでるため）
- ビルドによるログファイルも基本的にはコミットしない
- リソースの使用率のレポートは残す
- どうしようもない場合は変な差分が混じっても許す
- Block Designは使ったことないので考慮しない
やり方
結論としては、以下の方針でフォルダを構成し、必要なファイルをコミットしていけばOKです。自分一人で作業することと、クローンしてプロジェクトを開き、そのままビルドできるようにしたいので.xprファイルもコミットします。変な差分が出ますが、tclでプロジェクトを再生成するのは面倒なのでここは妥協点です。使うすべてのPCで同じパスをワークスペースとして使うことで、パスの関係も崩れないように工夫しています。
- リポジトリにのフォルダに、ソース用フォルダ、プロジェクトフォルダを分けて作成する
- 自分で書いたHDLソースはコミットする
- IPカタログから生成した
.xciファイルだけコミットする - プロジェクトファイル（
.xprファイル）もコミットする - ファイルを追加するごとに
.tclファイルを生成しコミットする
別環境になってもそのままプロジェクトファイルを使えます。Githubなどで公開するならローカルのパスを含まないtclのほうが適しているかなとは思います。
フォルダの構成
いろいろと調べて試してみたところ以下のようなフォルダ構成にすると管理しやすいと思いました。gitのリポジトリになるフォルダがSource_controlで、プロジェクトフォルダとソースコード（HDLソースやIPの生成元ファイル）ごとに専用のフォルダを作って管理します。自分で書いたソースコードはHDLフォルダに、IP関連ファイルはIP_repoフォルダに保管します。xdcファイルもまとめてHDLフォルダに保存しています。
project_rootはvivadoでプロジェクトを作る際に、「Create project subdirectory」にチェックをしていると作られるフォルダです。こうしておくと、自動生成されるファイルのほとんどはproject_root以下に作られます。
Source_control
│ regenerateProject.tcl
├─IP_repo
├─project_root
│ └─ project.xpr
└─HDL
├─ vhdl_source.vhdl
├─ verilog_source.v
...
IPカタログのIPを任意フォルダに保存する
クロックを生成したりなどFPAGの基本機能を使う際に必ず使用しますが、適当にIPを追加するとプロジェクトフォルダ以下に作られてしまいます。しかも、非常に面倒なことにプロジェクトから削除しないとファイルの移動ができません。IPフォルダにも大量のファイルを自動生成してくるので間違ってコミットすると厄介です。
これを防ぐためにIPを生成するときに、左上のIP Locationのところから、IP_Repoに保存先を変更しておきます。
tclファイルの生成
Block Designを使用しない場合はプロジェクトにファイル（自作HDLソースやIPカタログのIPなど）を追加したときだけ行えばよいです。Vivadoのメニューバーから、「File」→「Project」→「Write Tcl」の順にクリックして生成する画面を開きます。適当な名前を付けてリポジトリの直下に保存します。
自動生成したtclファイルはローカルのパスがコメントとして含まれています。Githubなどに公開する場合は注意しましょう。
tclからプロジェクトを生成しなおすときは、リポジトリのフォルダをカレントディレクトリとしてtclを実行する必要があります。Vivadoを起動すると、下のほうに「Tcl console」というのがあるので、そこに、cdコマンドを入れてやってカレントディレクトリを移動します。
Windowsスタイルのパス表記に対応していません。フォルダの区切り文字は/です。Cドライブ直下のvivado_workspaceに保存している場合は次のようにコマンドを入れます。
cd c:/vivado_workspace/Source_control
.gitignoreの内容
ここまで、フォルダの構成を説明しましたが、そもそも間違ってコミットしないためにはgitignoreを設定しておくのが一番です。
gitignore.ioで生成したものを参考にしつつ、ビルドして試してみたりなどいろいろやってみて、最終的に以下のようなgitignoreに落ち着きました。上で説明したフォルダの構成に従ってリポジトリを構成して必要なファイルを追加していきます。
Write Tclによって生成したファイルによると、IP_repoフォルダ以下の*.xciファイルと、自分で追加したソースファイル、Write Tclで生成したTclファイルがあればプロジェクトを再生成できるというようにファイル先頭のコメントに書いています。
したがって、以下のように記述してやると自動生成されるファイルをすべて無視して、必要なものだけをコミットできます。
# ログや中間生成ファイルは無視する
*.jou
*.log
*.str
*.dcp
# プロジェクトフォルダ以下に作られるものをフォルダごと無視する
*.cache
*.hw
*.ip_user_files
*.sim
# IPのフォルダにも自動生成されるので必要なものだけ無視しない
IP_repo/**/**
!IP_repo/**/
!IP_repo/**/*.xci
# 論理合成や配線配置のレポートを例外としたいときは以下のように書く
*/*.runs/**/*
!*/*.runs/**/
!*/*.runs/**/*.rpt
# 論理合成の際に自動生成されるフォルダを無視するときはこう
# *.runs
おわりに
初めてVivadoを使ってみて、ISEより使い勝手はよくなっているものの大量のファイルをまき散らすところは変わっていなかったので、いろいろと調べて試してみました。いつかの自分やこれからVivadoで開発を始める人にこの記事が役に立つと幸いです。