Developing 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
command: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:
/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 commandcasa_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 themaster
branch (default islatest_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 variableCASA_DEFAULT_REPOSITORY
is 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.secret
may be created / edited to store login / password information for the svn BioProj server. If not filled, thesvn
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:
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>
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.
Administration¶
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.