Automated tests with bbi_daily¶
BBI stands for BrainVISA Build Infrastructure. The casa_distro_admin
bbi_daily
command orchestrates automated builds and tests in a given base
directory. This page is written as a guide to setting up automated tests, see
bbi-daily-help for the reference documentation.
Walkthrough¶
Here is a detailed log of how nightly builds are set up in NeuroSpin. You can take inspiration from it to create your own personalized set-up.
Install
singularity
. Configure the fakeroot functionality of Singularity, as explained in the Singularity Admin Guide. In short, you need admin rights on your machine, and you have to run:sudo singularity config fakeroot --add $USER
(with
$USER
beinga-sac-ns-brainvisa
in this case).Create a directory dedicated to the nightly builds and
cd
into it:export CASA_BASE_DIRECTORY=/volatile/a-sac-ns-brainvisa/bbi_nightly mkdir "$CASA_BASE_DIRECTORY" cd "$CASA_BASE_DIRECTORY"
Create the
jenkins_auth
file in the base directory. This text file must consist of two lines: the first line contains the username on the Jenkins server, the second line contains the token that can be generated in the Jenkins web interface (click on the user on top right corner, select Configure and create a new API token). This token will be used instead of the account password to upload build results. One advantage of using a token is the possibility to revoke it at any time. It is recommended to use one token per BrainVISA Build Environment and name the token accordingly.- warning:
You should make this file non-readable by others, e.g. create it with:
chmod 0600 jenkins_auth
Download the
casa-dev
image using the link found on the Downloads page of <https://brainvisa.info/>. Also download the associated JSON file (to be extra safe, check that the md5sum of the image matches that stored in the JSON file).:wget https://brainvisa.info/download/casa-dev-5.0.sif wget https://brainvisa.info/download/casa-dev-5.0.sif.json md5sum casa-dev-5.0.sif
Create a directory for your development environment and set it up:
cd "$CASA_BASE_DIRECTORY" mkdir brainvisa-master-5.0 singularity run -c --bind ./brainvisa-master-5.0:/casa/setup \ casa-dev-5.0.sif distro=brainvisa branch=master
Edit the
conf/svn.secret
file with your BioProj login and password.Check out and compile an initial build while you do the rest of the configuration (until you run
bbi_daily
):"$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/bin/bv_maker
Put the reference test data in
"$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/tests/ref/
. Best is to copy it from a known-good source.bbi_daily
will install the compiled software in a user image, create a fresh user environment from that user image, and run tests in there. You can control this process with a few optional parameters, that you should insert in theconf/casa_distro.json
of the dev environment, as a new dictionary under thebbi_user_config
key. Below is the list of keys in this dictionary with their default values:"bbi_user_config": { "name": "<dev_name>-userimage", "directory": "<dev_directory>/../<user_name>", "image": "{base_directory}/<user_name>{extension}", "version": "%Y-%m-%d" }
Note that the value of
version
will be interpreted bytime.strftime()
.Check that the whole
bbi_daily
process is able to run successfully:"$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/bin/casa_distro_admin \ bbi_daily
This will take a long time. Beware that the output of each step is displayed only when that step is finished, so the command may seem to hang for a long time.
Set the
bbi_daily
command to run on a regular basis usingcrontab -e
:MAILTO=your.email@host.example 37 5 * * * PATH=/usr/local/bin:/usr/bin:/bin CASA_BASE_DIRECTORY=/volatile/a-sac-ns-brainvisa/bbi_nightly SINGULARITY_TMPDIR=/volatile/tmp /volatile/a-sac-ns-brainvisa/bbi_nightly/brainvisa-master-5.0/bin/casa_distro_admin bbi_daily jenkins_server='https://brainvisa.info/builds'
- note:
Remember to set all the needed environment variables.
PATH
may need to be set additionally, in case your Singularity installation is under/usr/local
(by default cron limitsPATH
to/usr/bin:/bin
).