Developping in the Casa-Distro BrainVISA environment¶
Installation and setup¶
The BrainVisa download / install section explains how to install both a released, compiled, version of BrainVISA (This is what a “regular user” needs), or a developer environment which will build from sources.
Alternatively it is possible to install Casa-Distro from its sources on GitHub. To get the latest release you can simply download it from https://github.com/brainvisa/casa-distro, using the
git clone https://github.com/brainvisa/casa-distro.git /tmp/casa-distro
Once downloaded, no “install step” is required, you can use the casa_distro command directly:
Casa-distro is pre-setup to handle CATI/BrainVisa open-source projects. In this situation, once casa-distro has been downloaded or installed, a user has to follow the next steps:
Building CASA projects¶
Developers will need access to source and development tools. Thus instead of installing a “user” release of BrainVISA using the
casa_distro setupcommand, they will rather install a developer image and setup. This is done (once casa-distro is installed) using the command
casa_distro setup_dev system=ubuntu-18.04 distro=brainvisa branch=master
This will setup an environment dedicated to development.
This command specifies to setup a developer environment for the open-source projects set (
distro_source=opensourceis actually the default and can be omitted), for the
masterbranch (default is
latest_release), using a container system based on Ubuntu 18.04.
Directories and files will be created accordingly in the repository directory (location of casa-distro container images and environments), here the default is
The location of casa-distro repository can be specified either using the
base_directory=parameter to many sub-commands, or if the environment variable
CASA_DEFAULT_REPOSITORYis set to an appropriate directory.
Such an environment will use source code from BrainVisa code repositories (partly on https://github.com and partly on https://bioproj.extra.cea.fr). The code needs to be downloaded and built using a build system: bv_maker
Setup credentials for source code reposotories
This step is optional and is especially not need if just retrieving only the open-source projects. The file
svn.secretmay be created / edited to store login / password information for the svn BioProj server. If not filled, the
svnprogram will ask for them interactively, and propose to store them.
casa_distro bv_maker name=opensource-dev-ubuntu-18.04
If name, distro, branch, or system are not provided, all matching environments will be processed.
Additional options can be passed to the underlying bv_maker command, which will run inside the container. Typically, the documentation can be built, testing and packaging can be performed.
Update the casa_distro command¶
Once an environment has been initialized, and at least source code has been updated (using
casa_distro bv_maker), most distributions actually include the casa-distro project, which will be updated with the rest of the source code. As it is python-only, it can be run from the host system (if stored on the host filesystem), so it may be a good idea to use this updated
casa_distro command instead of the oned previously installed (either via pip or from github sources) to initialize the process.
Bash completion scripts have been developed for
bv_maker. Inside a casa-distro container, these completions are already setup and should be active as soon as environments have been built, and the container is restarted (exit a casa-distro shell and re-run it).
On the host, it is possible to source the bash completion scripts. You can set it in your
$HOME/.bashrc file by adding to it:
BUILD_WF=$HOME/casa_distro/opensource-dev-ubuntu-18.04 if [ -f "$BUILD_WF/host/src/development/casa-distro/*/etc/bash_completion.d/casa_distro-completion.bash" ]; then . "$BUILD_WF/host/src/development/casa-distro/*/etc/bash_completion.d/casa_distro-completion.bash" fi if [ -f "$BUILD_WF/host/src/development/brainvisa-cmake/*/etc/bash_completion.d/bv_maker-completion.bash" ]; then . "$BUILD_WF/host/src/development/brainvisa-cmake/*/etc/bash_completion.d/bv_maker-completion.bash" fi
This completion will help typing the commands and its options by providing possible options and values by typing
<tab> <tab> when typing the command code, which will significantly speed-up working intensively with casa_distro and bv_maker.
To update to the most recent versions of the projects sources, and rebuild, it is simply a matter of re-running
casa_distro bv_maker (with corresponding options, if needed).
It is possible to customize the projects list to be retrieved and built. It is done by editing the bv_maker.cfg file in the environment, which can be found in the directory
<repository> is the base casa-distro repository directory (passed as the
base_directory option of casa_distro if needed),
<environment> is the environment environment name.
The Casa-distro concepts document shows the vocabulary used to describe the elements of Casa-Distro.
What we call “administration” in Casa-Distro is handling tools to build a new (BrainVISA) release, to build new images, not just developing code. This part is the job of The casa_distro_admin command.