The guiding principle in internal development is to submit your work into the repository without breaking other people‘s work. When you commit, make sure that the repository compiles, that the flow runs, and that you did not clobber someone else’s work. In the event that you are responsible for “breaking the build”, fix the build at top priority.
We have some guidelines in place to help catch most of these problems:
#From the VTR root directory $ ./run_quick_test.pl
You may push if all the tests return [PASS]. It is typically a good idea to run tests regularily as you make changes.
The automated BuildBot will perform more extensive regressions tests and mark which revisions are stable.
Everyone who is doing development must write regression tests for major feature they create. This ensures regression testing will detect if a feature is broken by someone (or yourself).
In the event a regression test is broken, the one responsible for having the test pass is in charge of determining:
If the golden results need to be updated and you are sure that the new golden results are better, use the command ../scripts/parse_vtr_task.pl -create_golden your_regression_test_name_here
Keep in sync with the GitHub master branch as regularly as you can (i.e. git pull or git pull --rebase). The longer code deviates from the trunk, the more painful it is to integrate back into the trunk.
Whatever system that we come up with will not be foolproof so be conscientious about how your changes will effect other developers.
VTR welcomes external contributions.
The general proceedure is to file an issue on GitHub proposing your changes, and then create an associated pull request.
Here are some general guidelines:
Keep your pull requests focused and specific. Short pull requests are much easier to review (and hence likely to be merged). Large scale changes which touch a large amount of code are difficult to review, and should be discussed (e.g. in a GitHub issue) before hand.
If you are adding user-facing features, make sure the documentation has been updated
If you are adding a new feature, ensure you have added tests for the feature
Ensure that all tests (new and existing) pass
Some libraries used by VTR are developed in other repositories and integrated using git subtrees.
Currently these includes:
As an example consider libsdcparse:
To begin add the sub-project as a remote:
git remote add -f github-libsdcparse git@github.com:kmurray/libsdcparse.git
To initially add the library (first time the library is added only):
git subtree add --prefix libsdcparse github-libsdcparse master --squash
Note the ‘--squash’ option which prevents the whole up-stream history from being merged into the current repository.
To update a library (subsequently):
git subtree pull --prefix libsdcparse github-libsdcparse master --squash
Note the ‘--squash’ option which prevents the whole up-stream history from being merged into the current repository.
If you have made local changes to the subtree and pushed them to the parent repository, you may encounter a merge conflict during the above pull (caused by divergent commit IDs between the main and parent repositories). You will need to re-split the subtree so that subtree pull finds the correct common ancestor:
git subtree split --rejoin -P libsdcparse/
You can then re-try the subtree pull as described above.
[This is unusual, be sure you really mean to do this!] To push local changes to the upstream subtree
git subtree push --prefix libsdcparse github-libsdcparse master
For more details see here for a good overview.
Coverity Scan is a static code analysis service which can be used to detect bugs.
To view defects detected do the following:
Get a coverity scan account
Contact a project maintainer for an invitation.
Browse the existing defects through the coverity web interface
To submit a build to coverity do the following:
Download the coverity build tool
Configure VTR to perform a debug build. This ensures that all assertions are enabled, without assertions coverity may report bugs that are gaurded against by assertions. We also set VTR asserts to the highest level.
#From the VTR root mkdir -p build cd build CC=gcc CXX=g++ cmake -DCMAKE_BUILD_TYPE=debug -DVTR_ASSERT_LEVEL=3 ..
Note that we explicitly asked for gcc and g++, the coverity build tool defaults to these compilers, and may not like the default ‘cc’ or ‘c++’ (even if they are linked to gcc/g++).
Run the coverity build tool
#From the build directory where we ran cmake cov-build --dir cov-int make -j8
Archive the output directory
tar -czvf vtr_coverity.tar.gz cov-int
Submit the archive through the coverity web interface
Once the build has been analyzed you can browse the latest results throught the coverity web interface
If you get the following warning from cov-build:
[WARNING] No files were emitted.
You may need to configure coverity to ‘know’ about your compiler. For example:
```shell cov-configure --compiler `which gcc-7` ```
First make sure you have clang installed. define clang as the default compiler: export CC=clang export CXX=clang++
set to debug in makefile
On unix-like systems run scan-build make from the root VTR directory. to output the html analysis to a specific folder, run scan-build make -o /some/folder
make sure all test passes: microbechmark, full regression an vtr strong regression test.
ODIN_II/verify_full.sh takes care of running all of them at once. verify they are all successfull.