How to release gateware
This page provides directives to create release builds that could be reproduced and identified.
A release build is any build that is run in production. During development, this whole procedure doesn't need to be followed.
A release build should contain a version so that it could be identified and reported.
A developer must be able to reproduce a release build, so that it is possible to run a simulation on any issue and possibly to release a new build that is as close as possible to a previous one.
Some tools may generate non deterministic outputs (like a place-and-route that use randomness). Most of them have a way to make them deterministic (like setting the random seed), otherwise do your best!
Any design that uses the fpga-dev-id has git commit id included in the bitstream. That provides an easy way to identify and reproduce builds. But there are pitfalls that could be avoided using this procedure.
The main flow with git is:
-
Bump the version in the meta-data version field.
-
Commit your main project and check you are using identified dependencies.
-
Tag your commit (so that the tag could be included in the build info).
-
Build your design
-
Test your design
-
If everything went well, push your commit and your tag. If you need to change the design, remove your tag and restart.
It is very important to build a non-dirty tree. To achieve that:
-
You need to commit your tree before building (as described)
-
All the dependencies must be submodules, and those submodules must be used for the build (ie don't override the
fetchto
ofhdlmake
).
The files that contain commit id are automatically generated. In order not to make the tree dirty, those file must be added in .gitignore
.