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, using the git command:

    git clone /tmp/casa-distro

    Once downloaded, no “install step” is required, you can use the casa_distro command directly:

    /tmp/casa-distro/bin/casa_distro help

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

First time

  • Developers will need access to source and development tools. Thus instead of installing a “user” release of BrainVISA using the casa_distro setup command, they will rather install a developer image and setup. This is done (once casa-distro is installed) using the command casa_distro setup_dev:

    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=opensource is actually the default and can be omitted), for the master branch (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 $HOME/casa_distro.

    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_REPOSITORY is set to an appropriate directory.

    Such an environment will use source code from BrainVisa code repositories (partly on and partly on 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.secret may be created / edited to store login / password information for the svn BioProj server. If not filled, the svn program will ask for them interactively, and propose to store them.

  • build everything:

    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

Bash completion scripts have been developed for casa_distro and 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:

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"
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"

This completion will help typing the commands and its options by providing possible options and values by typing <tab> or <tab> <tab> when typing the command code, which will significantly speed-up working intensively with casa_distro and bv_maker.

Updating projects

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).

Customizing projects

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>/<environment>/host/conf/

where <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.

Casa-Distro concepts

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.