LArSoft Continuous Integration¶
This package and instructions are superseded by the lar_ci package (note the underscore "
_" in place of the hyphen "
The LArSoft Continuous Integration setup provides integration builds of LarSoft and related tools, and reports on current and past builds, along with detailed information on pre- and post-install tests of the software. For a high-level overview, please go to: http://larsoft.org/continuous-integration/
For the most part, you don't need to do anything special to take advantage of the system; if you merge changes into the develop branch of one of the LAr-related software packages, and do a git push you will automatically trigger a continuous_integration build, and you can check the results at the Reporting Website.For more information about:
- the CI information available, see an annotated Test_result_display example.
- the database schema used to store CI information, see this Database_schema document.
- what CI tests are running now, see the currentRunningCITests site.
Prior to the CI workflow, there is an 'eval' stage where Jenkins sets up the environment for the workflow. There are five stages to the CI workflow: checkout, build, unit-tests, install, ci-tests.
There are several components of the system: (1) The builds are run via the Fermilab Build Service currently under the lar_ci_beta project there. (2) The software used to manage the builds is kept in the "lar_ci" ups product; The trigger, workflow and test_runner scripts live there. The workflow script reports results to the (3) "lar_ci_db" package, which allows for querying and presenting the results.
Requesting a CI Build¶
The whole 5-stage series of events is kicked off by Jenkins upon receipt of a trigger. See Triggering_Builds, particularly if you're a coordinator who wants to learn to fire off experimental workflows/builds. The result is a grid of dimension 5 by
Np at Reporting Website, where
Np is the number of platforms on which the build takes place. Three of the stages which the user may care about are elucidated below.
The checkout stage (
git pull origin branchname on all N repositories) produces output which can be accessed by clicking on the appropriate box on the grid. Build summary text is at the bottom, showing the unique hash of each of the repositories at this instant, ensuring a reproducible build. More can be learned about the changes to the code in this build by clicking the Change List link there, which takes you back to the Jenkins page and a nicely formatted repo-by-repo summary of the pushes since the last build.
Pre-Install (or Unit) Tests¶
Stand-alone unit tests are written to use only libraries within a particular package. They are generally simple tests that exit with non-zero status if some simple unit of execution gives a non-standard result.
In some packages the tests make heavy use of Boost macros. See the examples in the test directory of any of the repositories, as at
larreco/test/HitFinder/HitAnaAlg_test.cc. With only slight customization to the CMakeLists.txt files your test is built and run at this stage of the workflow. An example which is less obfuscated by these Boost macros -- a straightforward main()! -- is seen at
Click on the "unit_test" boxes to see the summary, as given by, say, unit_test.
More useful, in some meaningful ways, are tests which allow the user to see if actual runtime properties are as expected. See Test_Runner_Introduction for much more information. The power of these tests is that all the libraries of the install are now at one's disposal, unlike with the above unit tests, and that means the
lar binary can be used and modules can be exercised. Click on the "ci_tests" boxes to see results; example output is at ci_tests. And, again, click here to learn what CI tests are running now.