Casa-distro concepts

repository

The repository is the root directory for all casa-distro files. It contains container images and environments.

environment

An environment is a workspace, directory and associated container image(s), containing a user installation of the applications (BrainVISA software) or a developer build (sources and build).

It represents all what is necessary to work on a distro at a given version for a given operating system. In casa_distro, an environment is identified by several variables:

Note that in casa-distro 2, we used to call this environment “build workflow”. We changed the name after extending it to user “run” environments which are not designed to build the software but just to use it.

An environment is based on an image located at the repository level. In some situations (developer environments with tests, release building) several images may be used within a single environment.

The hardware representation of an environment is a set of directories in the repository, under the sub-directory named after th environment name:

  • For a user environment:

    - host/conf: configuration of the environment (config file, etc.). There are some predefined content for conf that can be generated with the command casa_distro setup but the whole environment can be customized by editing files in this directory.
    - host/host_bin: directory containing run scripts for all BrainVISA executable programs, and also the The bv command. Programs here are meant to be run from the host machine, not from within the container. This directory can safely be setup in the host system PATH environment variable.
    - host/python: contains the python modules needed to run the The bv command on the host machine side.
    - home: a “home directory” for the user inside the casa-distro container of the environment. This is separated from the host home directory because as it is a container, the configuration here may differ from the host one, and cause confusions and incompatibilities.
    - install: the BrainVISA distribution directory. This directory is actually in the container image, and is not visible from the host machine.
  • for a developer environment:

    - host/conf: configuration of the environment (config file, BioProj passwords, bv_maker.cfg, etc.). The content of this directory is the input of the compilation, packaging and testing steps. There are some predefined content for conf that can be generated with the command casa_distro setup_dev but the whole environment can be customized by editing files in this directory.
    - host/src: source of selected components for the workflow. The content of this directory is first created by bv_maker from within a Docker container running the targeted operting system. Simply call casa_distro bv_maker for this. The same command can be used to update sources to latest revision or to recompile when source code has been modified.
    - host/build: build directory used for compilation. Like the src directory, the content of this directory is created by commands such as casa_distro bv_maker.
    - host/install: directory containing distribution packages. Packages that are created by bv_maker are stored in that directory.
    - home: a “home directory” for the user inside the casa-distro container of the environment. This is separated from the host home directory because as it is a container, the configuration here may differ from the host one, and cause confusions and incompatibilities.
    - test: directory used during testing. Typically reference data will be downloaded in this directory and compared to test data generated, in this directory, by test commands.

environment type

There are two environment types: * user: the environment is an installation of a ready-to-run, precompiled BrainVISA distribution in a container image. It is designed for users who just need to run the software. * dev: the environment is a developer environment, it is using a container image containing all development tools, and will hold source code and compilation files.

environment name

Identifier for the environment. The name has to be unique in a repository and can be used as a shortcut to select a specific environment, once setup and installed: it can replace distro, branch, version, system and type to select an existing environment.

distro

The identifier of the distro (distribution). It represents a set of software handled (installed or built) in the environment. Software distributions managed by casa-distro are composed of many versioned software components (more than 50 at the time of this writing).

There are a few predefined distro in casa-distro:

  • opensource: brainvisa projects subset which are fully open-source and don’t need a personal login/password to access the sources repositories. The contain the core libraries and software infrastructure (Aims, Anatomist, Axon, Soma-Workflow, Capsul, and more)
  • brainvisa: all BrainVISA public distribution
  • cati
  • cea: complete BrainVISA components, including internal (non-publicly distributed) components

system

the operating system the distro is built for (e.g. ubuntu-18.04, ubuntu-20.04, we used to have also win32 or win64).

branch

The name of the virtual branch used to select software component sources (latest_release, master or integration) in an environment. This variable is only used in developer environments, when user environments use version instead.

version

The version of the user distribution of BrainVISA.

image

Container image file, located in the repository. Casa-distro can use Singularity images (.sif or .simg files), Docker images (located in the docker images repository, not in Casa-distro repository directory), or VirtualBox images (.vdi or .ova files).

An images may be of three types: * user image: user-oriented, it contains a full system with BrainVISA already installed in it. * dev image: developer-oriented, it contains a system with all needed development tools, but not the BrainVISA software which are meant to be built by the developer, in the environment but outside of the image. * run image: normally not used by users nor by developers, but used by distribution maintainers to build a BrainVISA release (user image): it contains a system with the needed runtime third-party libraries and modules required to run the BrainVISA software. It is thus lighter than the corresponding dev image. A user image is a run image with BrainVISA additionally installed in it.