The **bv_env** program sets up paths to run all programs from a build tree or binary package installation of software built or installed via the *brainvisa-cmake* environment.

 program sets up paths to run all programs from a build tree or binary package installation of software built or installed via the 

It sets basically ``PATH``, ``LD_LIBRARY_PATH``, ``PYTHONPATH`` and ``BRAINVISA_SHARE`` environment variables, and saves their previous values in ``BRAINVISA_UNENV_*`` variables.

When run with no arguments, ``bv_env`` just prints the environment it would set.

When run with arguments, ``bv_env`` will run the commandline specified as arguments, in the bv_env environment.

 will run the commandline specified as arguments, in the bv_env environment.

/home/myself/brainvisa_install/bin/bv_env anatomist /home/myself/data/mri.nii /home/myself/data/brain_mesh.gii

The environment is set only duing the command execution time, it does not modify shell variables from the calling program or shell.

The program is relocatable, this means that if you move the install tree after it is installed, bv_env will find out from where it is run and adapt, so it will still be valid.

These scripts do the same as the bv_env program, except that they do not run a program on-the-fly, but change the calling shell environment variables. As it depends on the shell type used, there are several scripts for *sh/bash*, *csh/tcsh*, or windows *DOS* shells.

These scripts do the same as the bv_env program, except that they do not run a program on-the-fly, but change the calling shell environment variables. As it depends on the shell type used, there are several scripts for 

We have to admit that currently we only use *bash* shells and the other scripts are mostly untested.

In Unix shells (sh, bash, csh, tcsh), to actually modify the running environment, the scripts have to be *sourced*, not just run. Ex:

In Unix shells (sh, bash, csh, tcsh), to actually modify the running environment, the scripts have to be 

will just appear to no nothing (it will modify variables internally during the script execution, but the calling shell will not be modified).

The programs are relocatable, this means that if you move the install tree after it is installed, ``bv_env.*`` scripts will find out from where it is run and adapt, so it will still be valid.

The programs are relocatable, this means that if you move the install tree after it is installed, 

 scripts will find out from where it is run and adapt, so it will still be valid.

However to find out where they are run from, the scripts need to access the shell commands history, so the above commands will work in an interactive shell, but not from within a script or ``.bashrc`` configuration script.

However to find out where they are run from, the scripts need to access the shell commands history, so the above commands will work in an interactive shell, but not from within a script or 

To overcome this problem, she ``bv_env.sh`` script can be passed an argument, which is the build / install directory location:

 script can be passed an argument, which is the build / install directory location:

. /home/myself/brainvisa_install/bin/bv_env.sh /home/myself/brainvisa_install

If you need to run an "external" program, a program not part of the BrainVisa package, from a program within the BrainVisa environment, it may cause environment and libraries conflict problems, because BV programs need some libraries installed within the installation directory and environment, but "external" programs need the system versions.

If you need to run an “external” program, a program not part of the BrainVisa package, from a program within the BrainVisa environment, it may cause environment and libraries conflict problems, because BV programs need some libraries installed within the installation directory and environment, but “external” programs need the system versions.

When running such a program, it is possible to "undo" the environment setup of *bv_env*, using the **bv_unenv** program.

When running such a program, it is possible to “undo” the environment setup of 

The **bv_unenv.sh** script is the equivalent to undo *bv_env.sh* script.

that *brainvisa-cmake* provides a *bash_completion* script which helps and speeds up the use of ``bv_maker``. It can be used **in a bash shell** by *sourcing* the script:

.. code-block:: bash

    . $(dirname $(which bv_maker))/../etc/bash_completion.d/bv_maker-completion.bash

You may copy this line in your ``~/.bashrc`` file.

. $(dirname $(which bv_maker))/../etc/bash_completion.d/bv_maker-completion.bash

This program is for the management of source retrieval, configuration and compilation of BrainVISA projects.

In order to work, the commands svn and svnadmin must be installed on your system. On some Linux systems they are in two separate packages (e.g. subversion and subversion-tools).

sources: Create or updated selected sources directories from Subversion
repository.

status: Display a summary of the status of all source repositories.

configure: Create and configure selected build directories with CMake.

testref: Execute tests in a special mode to generate machine-specific
reference files (this is needed by some tests).

testref_pack: Create the machine-specific reference files for tests in
installed binary package.

To get help for a specific command, use -h option of the command. Example: "bv_maker build -h".

To get help for a specific command, use -h option of the command. Example: “bv_maker build -h”.

To get help on how to configure and write a bv_maker configuration file, see:

Options:
-h, --help            show this help message and exit
-d DIR, --directory=DIR
                      Restrict actions to a selected directory. May be used
                      several times to process several directories.
-c CONFIG, --config=CONFIG
                      specify configuration file. Default
                      ="/casa/host/conf/bv_maker.cfg"
-s DIR, --sources=DIR
                      directory containing sources
-b DIR, --build=DIR   build directory
--username=USERNAME   specify user login to use with the svn server
-e, --email           Use email notification (if configured in the general
                      section of the configuration file)
--def, --only-if-default
                      apply only steps which are defined as default steps in
                      the bv_maker.cfg config file. Equivalent to passing
                      --only-if-default to every substep which supports it.
-v, --verbose         show as much information as possible
--version             show bv_maker (brainvisa-cmake) version number

Restrict actions to a selected directory. May be used
several times to process several directories.

specify configuration file. Default
="/casa/host/conf/bv_maker.cfg"

=”/casa/host/conf/bv_maker.cfg”

Use email notification (if configured in the general
section of the configuration file)

apply only steps which are defined as default steps in
the bv_maker.cfg config file. Equivalent to passing
--only-if-default to every substep which supports it.

–only-if-default to every substep which supports it.

Display information about configuration, sources directories and build directories.

Options:
-h, --help         show this help message and exit
--only-if-default  only perform this step if it is a default step, or
                   specified in the "default_steps" option of bv_maker.cfg
                   config file. Default steps are normally "sources" for
                   source sections, and "configure build" for build sections

only perform this step if it is a default step, or
specified in the "default_steps" option of bv_maker.cfg
config file. Default steps are normally "sources" for
source sections, and "configure build" for build sections

specified in the “default_steps” option of bv_maker.cfg
config file. Default steps are normally “sources” for
source sections, and “configure build” for build sections

Create or updated selected sources directories from Subversion repository.

Options:
--no-cleanup          don't cleanup svn sources
--no-svn              don't update svn sources
--no-git              don't update git sources
--only-if-default     only perform this step if it is a default step, or
                      specified in the "default_steps" option of
                      bv_maker.cfg config file. Default steps are normally
                      "sources" for source sections, and "configure build"
                      for build sections
--ignore-git-failure  ignore git update failures, useful when working on a
                      feature branch

specified in the "default_steps" option of
bv_maker.cfg config file. Default steps are normally
"sources" for source sections, and "configure build"
for build sections

specified in the “default_steps” option of
“sources” for source sections, and “configure build”

ignore git update failures, useful when working on a
feature branch

Options:
--no-svn              don't display the status of svn sources
--no-git              don't display the status of git sources
--git-command=EXTRA_GIT_COMMANDS
                      run one or more extra commands in every Git
                      repository. The commmands are interpreted in a shell
                      so that you can pass arguments.

run one or more extra commands in every Git
repository. The commmands are interpreted in a shell
so that you can pass arguments.

Options:
-c, --clean        clean build tree (using bv_clean_build_tree -d) before
                   configuring

clean build tree (using bv_clean_build_tree -d) before
configuring

Options:
-c, --clean        clean build tree (using bv_clean_build_tree -b) before
                   building

Executes tests in the testref mode (used to generate reference files).

Options:
-m MAKE_OPTIONS, --make_options=MAKE_OPTIONS
                      options passed to make (ex: "-j8") during test
                      reference generation. Same as the configuration option
                      make_options but specified at runtime. The commandline
                      option here overrides the bv_maker.cfg options.

options passed to make (ex: "-j8") during test
reference generation. Same as the configuration option
make_options but specified at runtime. The commandline
option here overrides the bv_maker.cfg options.

options passed to make (ex: “-j8”) during test

Options:
-t CTEST_OPTIONS, --ctest_options=CTEST_OPTIONS
                      options passed to ctest (ex: "-VV -R carto*"). Same as
                      the configuration option ctest_options but specified
                      at runtime. The commandline option here overrides the
                      bv_maker.cfg options.

options passed to ctest (ex: "-VV -R carto*"). Same as
the configuration option ctest_options but specified
at runtime. The commandline option here overrides the
bv_maker.cfg options.

options passed to ctest (ex: “-VV -R carto*”). Same as

Options:
                   source sections, "configure build" for build sections.

source sections, "configure build" for build sections.

source sections, “configure build” for build sections.

Options:
                      "sources" for source sections, "configure build" for
                      build sections.
--package-date=PACKAGE_DATE
                      sets the date of the pack to install. This is only
                      useful if a %(date)s pattern has been used in the
                      package directory sections of bv_maker.cfg.
--package-time=PACKAGE_TIME
                      sets the time of the pack to install. This is only
                      useful if a %(time)s pattern has been used in the
--package-version=PACKAGE_VERSION
                      sets the version of the pack to install. This is only
                      useful if a %(version)s pattern has been used in the
--prefix=PREFIX       sets the prefix directory to install the pack.
--local               True if the installation must be done locally. Default
                      is False.
--offline             True if the installation must be done using offline
                      installer. Default is False.
--debug               True if the installation must be done in debug mode
                      (i.e. generated files must not be deleted). Default is
                      False.

"sources" for source sections, "configure build" for
build sections.

“sources” for source sections, “configure build” for

sets the date of the pack to install. This is only
useful if a %(date)s pattern has been used in the
package directory sections of bv_maker.cfg.

sets the time of the pack to install. This is only
useful if a %(time)s pattern has been used in the

sets the version of the pack to install. This is only
useful if a %(version)s pattern has been used in the

True if the installation must be done locally. Default
is False.

True if the installation must be done using offline
installer. Default is False.

True if the installation must be done in debug mode
(i.e. generated files must not be deleted). Default is
False.

False.

Create test reference files in installed package for the selected build directory.

Options:

Options:

Run command to publish package for the selected publication directory.

Options:

Options:
                   building

Options:

Options:

Options:
                      is False.
                      False.

Options:

Options:

Options:

Options:

Options:

Options:

Options:

``Brainvisa-cmake`` provides a set of CMake functions which help configuring Brainbisa-cmake projects. They can (should) be used within ``CMakeLists.txt`` files of peojects.

 provides a set of CMake functions which help configuring Brainbisa-cmake projects. They can (should) be used within 

BRAINVISA_ADD_COMMAND_HELP( name
                            [COMPONENT <component>]
                            [HELP_COMMAND <command>]
                            [HELP_DEPENDS <dependencies>] )

Add executable target and reference executable for the component.
Executables added with ``BRAINVISA_ADD_EXECUTABLE`` are referenced a
cache variable named ``${component}-commands``.

Executables added with 

BRAINVISA_ADD_EXECUTABLE( <name>
                          [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL]
                          source1 ... sourceN
                          [COMPONENT <component>]
                          [IS_SCRIPT]
                          [HELP_COMMAND <command> arg1 ... argN]
                          [HELP_GENERATE On/Off]
                          [OUTPUT_NAME commandname] )

if ``OUTPUT_NAME`` is set, ``set_property( TARGET <name> PROPERTY OUTPUT_NAME <commandname> )``
is called, and the command help is set with the name ``<commandname>`` instead of ``<name>``.

``set_property( TARGET <name> PROPERTY OUTPUT_NAME <commandname> )``

set_property( TARGET <name> PROPERTY OUTPUT_NAME <commandname> )

BRAINVISA_ADD_SIP_PYTHON_MODULE( <module> <directory> <mainSipFile>
                                 [ SIP_SOURCES <file> ... ]
                                 [ SIP_INCLUDE <directory> ... ]
                                 [ SIP_INSTALL <directory> ] )

Search recursively PyQt linguist source files (``*.ts``) generated from python
(PyQt) sources, in the directory source share directory
and generates the commands to create the associated ``*.qm`` files in the build
share directory and creates associated install rules.

) generated from python
and generates the commands to create the associated 

 files in the build

BRAINVISA_ADD_PYTRANSLATION(
  <name of the source share directory where finding the *.ts files>
  <name of the destination share directory where writing the *.qm files> <component>
  [source directory to search python files] )

Search recursively qt linguist source files (``*.ts``) in the directory source share directory
and generates the commands to create the associated ``*.qm`` files in the build share directory
and creates associated install rules.

) in the directory source share directory

 files in the build share directory

BRAINVISA_ADD_TRANSLATION(
  [source directory to search c++ files] )

BRAINVISA_ADD_TEST( NAME <name> [CONFIGURATIONS [Debug|Release|...]]
                    [WORKING_DIRECTORY dir]
                    COMMAND <command> [arg1 [arg2 ...]]
                    [TYPE Exe|Python] )

Add a test to the project with the specified arguments.
brainvisa_add_test(testname Exename arg1 arg2 ... )
If ``TYPE Python`` is given, the appropriate python interpreter is used to
start the test (i.e.: target python for cross compiling case).
Test command is also launched through bv_env_test command.

brainvisa_add_test(testname Exename arg1 arg2 … )
If 

 is given, the appropriate python interpreter is used to

brainvisa_add_test( axon-tests "${PYTHON_EXECUTABLE_NAME}"
                    -m brainvisa.tests.test_axon )

BRAINVISA_COPY_AND_INSTALL_HEADERS( <headers list> <include directory>
                                    <install component>
                                    [NO_SYMLINKS] )

Recursively copy and install all files in <source directory> except files named
``CMakeLists.txt``, ``*~`` or ``*/.svn/*``.

BRAINVISA_COPY_DIRECTORY( <source directory> <destination directory>
                          <component>
                          [IMMEDIATE]
                          [GET_TARGET <target variable>]
                          [NO_SYMLINKS] )

BRAINVISA_COPY_FILES( <component> <source files>
                      [SOURCE_DIRECTORY <directory>]
                      DESTINATION <destination directory>
                      [IMMEDIATE]
                      [GET_TARGET <target variable>]
                      [TARGET <target name>]
                      [GET_OUTPUT_FILES <target variable>]
                      [NO_SYMLINKS] )

Create targets to copy, byte compile and install all Python code
contained in a directory.

BRAINVISA_COPY_PYTHON_DIRECTORY( <python directory> <component>
                                 <destination directory>
                                 [NO_SYMLINKS]
                                 [INSTALL_ONLY] )

``<component>``
name of the component passed to ``BRAINVISA_INSTALL``.

``<destination directory>``
directory where the wiles will be copied
(relative to build directory).

BRAINVISA_COPY_PYTHON_DIRECTORY( <python directory> <component> )

``<destination directory>`` is set to the right most directory
name in ``<python directory>``

BRAINVISA_COPY_PYTHON_DIRECTORY( ${CMAKE_CURRENT_SOURCE_DIR}/python
                                 brainvisa_python )

BRAINVISA_DEPENDENCY( <package type> <dependency type> <component>
                      <component package type>
                      [ <version ranges> ]
                      [BINARY_INDEPENDENT] )

BRAINVISA_DEPENDENCY( RUN DEPENDS libblitz RUN "2.0.3-4" )
BRAINVISA_DEPENDENCY( DEV DEPENDS libblitz DEV ">= 2.0" )
BRAINVISA_DEPENDENCY( RUN RECOMMENDS dcmtk RUN "3.1.2" )
BRAINVISA_DEPENDENCY( DEV RECOMMENDS dcmtk DEV )
BRAINVISA_DEPENDENCY( RUN DEPENDS soma-io RUN "3.2.4-20100908" )
BRAINVISA_DEPENDENCY( DEV DEPENDS soma-io DEV ">= 3.2.0;<< 3.3.0" )
BRAINVISA_DEPENDENCY( RUN DEPENDS soma-base RUN ">= 3.2.0;<< 3.3.0"
                      BINARY_INDEPENDENT )
BRAINVISA_DEPENDENCY( DEV DEPENDS soma-base DEV ">= 3.2.0;<< 3.3.0" )

BRAINVISA_FIND_FSENTRY( output_variable
                        PATTERNS [ <pattern> ... ]
                        PATHS [ <path> ... ] )

BRAINVISA_FIND_FSENTRY( real_files
                        PATTERNS *.so PATHS /usr/lib/ )
foreach( file ${real_files} )
  message( "${file}" )
endforeach()

BRAINVISA_GENERATE_COMMANDS_HELP( [COMPONENT]
                                  <component_1> ... <component_N>  )

Add rules to generate docbook documentation with ``make doc`` or ``make <component>-doc``
or ``make usrdoc`` or ``make <component>-usrdoc`` if it a user manual or tutorial
or ``make devdoc`` or ``make <component>-devdoc`` if it is developer manual.

BRAINVISA_GENERATE_DOCBOOK_DOC( [EXCLUDE docbook_project_name] )

Docbook support has been deprecated in brainvisa-cmake, Sphinx is now much preferred.

Add rules to generate doxygen documentation with "make doc" or "make devdoc".

Add rules to generate doxygen documentation with “make doc” or “make devdoc”.

BRAINVISA_GENERATE_DOXYGEN_DOC( <input_variable>
                                [<file to copy> ...]
                                [INPUT_PREFIX <path>]
                                [COMPONENT <name>] )

``<input_variable>``
variable containing a string or a list of input sources.
Its content will be copied in the ``INPUT`` field of the
Doxygen configuration file.

Its content will be copied in the 

``<file to copy>``
file (relative to ``${CMAKE_CURRENT_SOURCE_DIR}``) to copy in
the build tree. Files are copied in ``${DOXYGEN_BINARY_DIR}``
if defined, otherwise they are copied in
``${PROJECT_BINARY_DIR}/doxygen``. The doxygen configuration
file is generated in the same directory.

. The doxygen configuration

``COMPONENT``
component name for this doxygen documentation. it is used to create the output directory and the tag file name.
By default it is the ``PROJECT_NAME``. but it is useful to give an alternative name when there are several libraries documented with doxygen in the same project.

By default it is the 

. but it is useful to give an alternative name when there are several libraries documented with doxygen in the same project.

Before calling this macro, it is possible to specify values that are going to be written in doxygen configuration file by setting variable names ``DOXYFILE_<doxyfile variable name>``. For instance, in order to set project name in Doxygen, one should use:

Before calling this macro, it is possible to specify values that are going to be written in doxygen configuration file by setting variable names 

. For instance, in order to set project name in Doxygen, one should use:

find_package( Doxygen )
if( DOXYGEN_FOUND )
  set( component_name "cartodata" )
  set( DOXYFILE_PREDEFINED "${AIMS_DEFINITIONS}" )
  set( DOXYFILE_TAGFILES "cartobase.tag=../../cartobase-${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_VERSION_MINOR}/doxygen" )
  BRAINVISA_GENERATE_DOXYGEN_DOC(
    _headers
    INPUT_PREFIX "${CMAKE_BINARY_DIR}/include/${component_name}"
    COMPONENT "${component_name}" )
endif( DOXYGEN_FOUND )

Add rules to generate epydoc documentation with ``make doc`` or ``make <component>-doc`` or ``make devdoc`` or ``make <component>-devdoc``.

BRAINVISA_GENERATE_EPYDOC_DOC( <source directory>
                               [ <source directory> ... ]
                               <output directory>
                               [ EXCLUDE <exclude list> ] )

Epydoc has been deprecated in brainvisa-cmake, Shinx is now much preferred.

BRAINVISA_GENERATE_EPYDOC_DOC( "${CMAKE_BINARY_DIR}/python/soma"
  "share/doc/${PROJECT_NAME}-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}/epydoc/html"
  EXCLUDE soma.aims* )

Add rules to generate sphinx documentation with ``make doc`` or ``make <component>-doc`` or ``make devdoc`` or ``make <component>-devdoc``.

BRAINVISA_GENERATE_SPHINX_DOC( <source directory> <output directory>
                               [TARGET <target_name>]
                               [USER] )

BRAINVISA_GENERATE_SPHINX_DOC( "doc/source"
  "share/doc/soma-workflow-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}" )

if ``TARGET`` argument is not specified, the target name defaults to ``${PROJECT_NAME}-sphinx``

if ``USER`` is specified, the generated doc will be part of the usrdoc (user
documentation) global target, and included in user docs packages.
Otherwise, by default, sphinx docs are considered developer docs (devdoc)

 is specified, the generated doc will be part of the usrdoc (user

Retrieve one (or more) list of file names from a ``.pro`` file. This macro
exists for backward compatibility with the older ``build-config`` tool (now abandoned).

 file. This macro
exists for backward compatibility with the older 

BRAINVISA_GET_FILE_LIST_FROM_PRO( <pro file name> <pro variable>
                                  <cmake variable>
                                  [<pro variable> <cmake variable>...] )

BRAINVISA_GET_FILE_LIST_FROM_PRO(
  ${CMAKE_CURRENT_SOURCE_DIR}/libvip.pro "HEADERS" _h "SOURCES" _s )

Transform a list into a string containing space separated items. Each item
is surounded by double quotes.

BRAINVISA_GET_SPACED_QUOTED_LIST( <list variable> <output variable> )

set( _list a b "c d" )
BRAINVISA_GET_SPACED_QUOTED_LIST( _list _quotedList )
# equivalent to SET( _quotedList "\"a\" \"b\" \"c d\"" )

BRAINVISA_INSTALL_DIRECTORY( <directory> <destination> <component> )

BRAINVISA_INSTALL_DIRECTORY( "/usr/lib/python2.7" "python"
                             "brainvisa-python" )

Checks and creates install rules for the libraries of the given component.
A list of library files is given in parameter, and the function gets the absolute path of these files, check existance,
and check that it is a dynamic library. The library files are set in an install rule for the component.
The symlinks that point to the library are found and created in the install directory via a custom command attached to the install target of the component.

BRAINVISA_INSTALL_RUNTIME_LIBRARIES( <component> <list of library files> )

find_package(LibXml2)
BRAINVISA_INSTALL_RUNTIME_LIBRARIES( libxml2 ${LIBXML2_LIBRARIES} )

Run ``pyside-uic`` / ``pyuic4`` / ``pyuic`` on a ``.ui`` file to generate the
corresponding ``.py`` module

BRAINVISA_PYUIC( <source_ui_file> <dest_py_file> <relative_path> )

Works like ``QT4_WRAP_UI``, but in addition, the directory of
generated files is user-defined (``<input_outdir>``).

, but in addition, the directory of
generated files is user-defined (

Remove all symlinks from a list of paths by applying ``get_filename_component( ... REALPATH )``
to each element of the list.

file( GLOB glob_result /usr/lib/*.so )
BRAINVISA_REAL_PATHS( real_files ${glob_result} )

Resolve symbol library pathes. A list of library or symbol files is given in parameter, and the function gets the absolute path of these files,
check existance, and check that it is a symbol for dynamic library. If the file is a symbol file for dynamic library, try to find the matching
library file.

BRAINVISA_RESOLVE_SYMBOL_LIBRARIES( <output_variable>
                                    PATHS <list of library files> )

BRAINVISA_RESOLVE_SYMBOL_LIBRARIES( libxml2 ${LIBXML2_LIBRARIES} )

Convert version number either to hexadecimal version either to string version.

BRAINVISA_VERSION_CONVERT( <variable> version
                           [HEX] [STR] [BYTES <number_of_bytes>] )

BRAINVISA_VERSION_CONVERT( result "0x30206" STR )
BRAINVISA_VERSION_CONVERT( result "3.2.6" HEX BYTES 2 )

Duplicate implicit target name: "brainvisa_generate_doxygen_doc".

Duplicate implicit target name: “brainvisa_generate_doxygen_doc”.

Duplicate implicit target name: "brainvisa_generate_sphinx_doc".

Duplicate implicit target name: “brainvisa_generate_sphinx_doc”.

Hyperlink target "brainvisa-generate-doxygen-doc" is not referenced.

Hyperlink target "brainvisa-generate-sphinx-doc" is not referenced.

There are several possibilities to compile a series of BrainVISA components. One can use a standard CMake procedure where each component have its own build directory and links between components are done via CMake cache variables. But at the time of this writing, there are 44 components in 21 BrainVISA project. Configuring and compiling all of them manualy can be a hard work. This is why bv_maker script have been developped in order to easily create a complete source synchronization and compilation pipeline for a selected set of projects or components. This document describes the use of bv_maker.

Subversion. The command svnadmin must also be installed on your system. On some Linux distributions it is not in the subversion package (for instance in Ubuntu you must install subversion-tools package).

Other dependencies depends on the components you want to build.

If you work at the I2BM (Neurospin, MirCen or SHFJ), you can call the bash function *bv_setup_devel* in your ``.bashrc`` file. This will add ``/i2bm/brainvisa`` paths in your environment variables where some useful dependencies for the development environment are installed.

If you work at the I2BM (Neurospin, MirCen or SHFJ), you can call the bash function 

 paths in your environment variables where some useful dependencies for the development environment are installed.

bv_maker is part of the brainvisa-cmake project. Since you need bv_maker to download the sources and do the first build directory, you may have to download a temporary version with the following code:

git clone https://github.com/brainvisa/brainvisa-cmake.git /tmp/brainvisa-cmake
cd /tmp/brainvisa-cmake
cmake -DCMAKE_INSTALL_PREFIX=. .
make install

Creating a developpment environment is not supported under Windows. Building Windows version of BrainVISA software is done on Linux using cross-compilation.

You can now use :code:`/tmp/brainvisa-cmake/bin/bv_env_host bv_maker` to setup your environement (**you must edit the configuration file first**). You will always have a copy of brainvisa-cmake installed in a build directory at configuration time. Therefore, you may delete this temporary brainvisa-cmake version and use the one in your build directory.

). You will always have a copy of brainvisa-cmake installed in a build directory at configuration time. Therefore, you may delete this temporary brainvisa-cmake version and use the one in your build directory.

You must create this file in the following directory: ``$HOME/.brainvisa/bv_maker.cfg``. In this file you can configure mainly two types of directory:

source directory: A source directory contains the source code of a set of selected projects. This source code will be updated (to reflect the changes that occured on BioProj server) each time you use bv_maker configure. You can define as many source directory as you want. In a source directory configuration you can select any project and combine several versions of the same project.

build directory: A build directory will contain compiled version of the projects. A build directory can contain any project but only one version per project is allowed. You can define as many build directory as you want.

See :doc:`bv_maker configuration syntax <configuration>` for a complete documentation with examples.

# definition of the source directory: open-source projects in bug_fix version (i.e. the branch with the highest version) except web project because it takes space
[ source $HOME/brainvisa/source ]
  + opensource bug_fix
  - web

# definition of the build directory: build open-source projects from the source directory except anatomist-gpl and anatomist-private components
[ build $HOME/brainvisa/build/bug_fix ]
  make_options = -j4
  build_type = Release
  opensource bug_fix $HOME/brainvisa/source
  - anatomist-*
  - communication:web

The option ``build_type`` is very important, the execution can be two to three times slower if the build is not in Release mode.

 is very important, the execution can be two to three times slower if the build is not in Release mode.

To compile using Qt5 or / and Python3, it is possible to add in the ``build`` sections appropriate ``cmake_options`` variables. Read :ref:`build_qt5` and :ref:`build_py3`.

To compile using Qt5 or / and Python3, it is possible to add in the 

(look at the section `In case of problems`_ for troubleshooting)

After this step, you have a version of ``brainvisa-cmake`` installed in each build directory you have defined. You can therefore find :doc:`bv_maker <bv_maker>` in ``<build_directory>/bin/bv_maker``.

 installed in each build directory you have defined. You can therefore find 

You should now remove the temporary bv_maker that have been downloaded in step 2 and use the one installed in your build directory: ``<build_directory>/bin/bv_maker``.

You should now remove the temporary bv_maker that have been downloaded in step 2 and use the one installed in your build directory: 

If you want to use all your build directory, set the following environment variables: ``PATH``, ``LD_LIBRARY_PATH``, ``PYTHONPATH`` and ``BRAINVISA_SHARE``. To make it easier, we provide a program called :doc:`bv_env <bv_env>` that sets up the required environment variables:

If you want to use all your build directory, set the following environment variables: 

**CMake has caches**. They sometimes keep erroneous values. Do not hesitate to remove the ``CMakeCache.txt`` file at the root of the build trees before reconfiguring. It sometimes solves incomprehensible configure problems.

. They sometimes keep erroneous values. Do not hesitate to remove the 

 file at the root of the build trees before reconfiguring. It sometimes solves incomprehensible configure problems.

See also the `contributors doc <https://brainvisa.github.io/contributing.html>`_ of the `BrainVisa developers doc <https://brainvisa.github.io>`_ project

`contributors doc <https://brainvisa.github.io/contributing.html>`_

git https://github.com/neurospin/highres-cortex.git master highres-cortex/master

see `the BrainVISA developers doc here <https://brainvisa.github.io/contributing.html#feature_branch>`_.

`the BrainVISA developers doc here <https://brainvisa.github.io/contributing.html#feature_branch>`_

see `the password issue in the developers doc <https://brainvisa.github.io/contributing.html#remote_credentials>`_.

`the password issue in the developers doc <https://brainvisa.github.io/contributing.html#remote_credentials>`_

You must create this file in the following directory: ``$HOME/.brainvisa/bv_maker.cfg``.

**source directory**: A source directory contains the source code of a set of selected projects. This source code will be updated (to reflect the changes that occured on BioProj or GitHub servers) each time you use bv_maker sources. You can define as many source directories as you want. In a source directory configuration you can select any project and combine several versions of the same project.

: A source directory contains the source code of a set of selected projects. This source code will be updated (to reflect the changes that occured on BioProj or GitHub servers) each time you use bv_maker sources. You can define as many source directories as you want. In a source directory configuration you can select any project and combine several versions of the same project.

**build directory**: A build directory will contain compiled version of the projects. A build directory can contain any project but only one version per project is allowed. You can define as many source directory as you want.

: A build directory will contain compiled version of the projects. A build directory can contain any project but only one version per project is allowed. You can define as many source directory as you want.

A section may also contain conditional parts. See the `Conditional subsections`_ section for details.

The :doc:`bv_maker` configuration file is composed of sections delimited by a line enclosed in square brackets: ``[ ... ]``. Each section contains the definition of a directory (either a source directory, or a build directory), or a "general" section. In this file, blank lines are ignored and spaces at the begining or end of lines are also ignored. It means that you can indent and separate lines as you wish. For instance:

 configuration file is composed of sections delimited by a line enclosed in square brackets: 

. Each section contains the definition of a directory (either a source directory, or a build directory), or a “general” section. In this file, blank lines are ignored and spaces at the begining or end of lines are also ignored. It means that you can indent and separate lines as you wish. For instance:

  + standard trunk
  + standard bug_fix
  - communication
  + perso/myself/myproject

  make_options = -j8
  standard bug_fix $HOME/brainvisa/source

[ build $HOME/brainvisa/build/trunk ]
  standard trunk $HOME/brainvisa/source
  + $HOME/brainvisa/source/perso/myself/myproject

A line begining with ``#`` or ``//`` is considered as a comment and ignored. Comments cannot be added at the end of a line. For instance the following are valid comments:

 is considered as a comment and ignored. Comments cannot be added at the end of a line. For instance the following are valid comments:

Each line in a section contains either a "variable" definition, or some section-specific declarations such as components definitions.

Each line in a section contains either a “variable” definition, or some section-specific declarations such as components definitions.

Some variables may support additive or substractive declarations, once they have been defined a first time:

This possibility depends on the variable type (here a list), but also on the variable itself (which must be understood in bv_maker as additive)

Most variables are strings, but a few are lists: elements are separated by blank spaces.

Some variables are "dictionaries" which may contain several sub-variables. A typical example is the ``env`` variable which contains environment variables to be set during execution of the steps for the given directory section. The syntax is the following:

Some variables are “dictionaries” which may contain several sub-variables. A typical example is the 

 variable which contains environment variables to be set during execution of the steps for the given directory section. The syntax is the following:

env = PATH: /home/myself/bin:$PATH, LD_LIBRARY_PATH:/home/myself/lib:$LD_LIBRARY_PATH

env += PATH: /home/myself/bin:$PATH, LD_LIBRARY_PATH=/home/myself/lib:$LD_LIBRARY_PATH

The difference between the two above examples is that the first will override the full set of environment variables defined in bv_maker.cfg, whereas the second will only add / replace 2 entries.

The above syntax is somewhat limited. If needed a "pythonic" syntax is allowed:

The above syntax is somewhat limited. If needed a “pythonic” syntax is allowed:

env += {'PATH': '/home/myself/bin:$PATH', 'LD_LIBRARY_PATH': '/home/myself/lib:$LD_LIBRARY_PATH'}

Some variables (not all) with string values support environment variables substitution (``$VARIABLE``), and / or "python-like" string substitution (``%(variable)s``)for a few variables (``date``, ``hostname``, ``time``, ``os``, a few more in some sections).
Dictionary variables do support both:

Some variables (not all) with string values support environment variables substitution (

, a few more in some sections).

env += PATH: $HOME/bin:$PATH, BRAINVISA_TEST_DIR: $HOME/tests-%(hostname)s-%(date)s

Environment variables may be set by the user, or by the system, prior to running bv_maker, or through the ``env`` variables in ``bv_maker.cfg`` sections. Additionally, bv_maker itself sets a few helpful variables:

Environment variables may be set by the user, or by the system, prior to running bv_maker, or through the 

 sections. Additionally, bv_maker itself sets a few helpful variables:

``NCPU``:
number of processor cores in the current machine. Useful to pass build options matching the power of the build machine:

    make_options = -j$NCPU

The general section is optional, and contains variable which are independent from each other sections (or shared accross them).

The general section definition starts with a line with the following syntax:

Option variables are stored in this section using the syntax ``option = value``. The following options are supported:

``env``: environment variables dictionary. Note that the ``env`` dictionary in the general section is handled a bit differently than the one in the other sections: in other sections variables defined this way are local to the current section, and only passed to the actual environment when a commandline is run (such as ``cmake``, ``make`` etc.). In the general sections variables are actually set globally to the environment, thus they are available all along the bv_maker session, including within the run of bv_maker: this means that variables which are to be used during path substitutions inside ``bv_maker.cfg`` should be defined here.

 dictionary in the general section is handled a bit differently than the one in the other sections: in other sections variables defined this way are local to the current section, and only passed to the actual environment when a commandline is run (such as 

 etc.). In the general sections variables are actually set globally to the environment, thus they are available all along the bv_maker session, including within the run of bv_maker: this means that variables which are to be used during path substitutions inside 

``email_notification_by_default``: ``ON```or ``OFF`` (default). If set to ``ON``, email notification will always be used if ``failure_email`` or ``success_email`` are provided. Otherwise, the default behavior is to use email notification only when the ``bv_maker`` commandline is invoked with the ``--email`` option.

 are provided. Otherwise, the default behavior is to use email notification only when the 

``global_status_file``: if this file is specified, a line will be appended to it for each source/build directory. This line will log the build status for the given directory: OK/FAILED, last step executed, directory, start and stop date and time, machine and system. It can be parsed and displayed using the command ``bv_show_build_log``.

: if this file is specified, a line will be appended to it for each source/build directory. This line will log the build status for the given directory: OK/FAILED, last step executed, directory, start and stop date and time, machine and system. It can be parsed and displayed using the command 

``failure_email``: email address where bv_maker outputs are sent in case of failure. If not specified, no email will be sent and bv_maker outputs will be sent to the standard output. One email will be sent for each directory and build step that fail.

: email address where bv_maker outputs are sent in case of failure. If not specified, no email will be sent and bv_maker outputs will be sent to the standard output. One email will be sent for each directory and build step that fail.

``failure_email_by_project``: dictionary of email addresses, in a project-indexed dictionary (json or python syntax). Adresses can be lists of strings. Ex:

  .. code-block:: bash

      failure_email_by_project = {'aims': 'maintainer@aims.org', 'anatomist': ['maintainer@aims.org', 'maintainer@anatomist.org']}

: dictionary of email addresses, in a project-indexed dictionary (json or python syntax). Adresses can be lists of strings. Ex:

    failure_email_by_project = {'aims': 'maintainer@aims.org', 'anatomist': ['maintainer@aims.org', 'maintainer@anatomist.org']}

failure_email_by_project = {'aims': 'maintainer@aims.org', 'anatomist': ['maintainer@aims.org', 'maintainer@anatomist.org']}

``jenkins_build_name``: pattern to Jenkins job name used to submit to a Jenkins dashboard. Only used if ``jenkins_server_url`` is also set. The pattern here may include replacement strings specified in a python style ``"%(variable)s"``. Allowed variables are:

  * ``date``
  * ``directory_id``: ``directory_id`` specified in the current section, or directory name of the build section (short name without path)
  * ``hostname``
  * ``os``
  * ``project``
  * ``step``
  * ``time``

: pattern to Jenkins job name used to submit to a Jenkins dashboard. Only used if 

 is also set. The pattern here may include replacement strings specified in a python style 

* ``date``
* ``directory_id``: ``directory_id`` specified in the current section, or directory name of the build section (short name without path)
* ``hostname``
* ``os``
* ``project``
* ``step``
* ``time``

``directory_id``: ``directory_id`` specified in the current section, or directory name of the build section (short name without path)

 specified in the current section, or directory name of the build section (short name without path)

``jenkins_server_url``: URL of a `Jenkins <https://jenkins.io/>`_ server which can be used to log build and tests logs. The log will be sent to the Jenkins dashboard through client commandline interface as an external job.

 server which can be used to log build and tests logs. The log will be sent to the Jenkins dashboard through client commandline interface as an external job.

``jenkins_token``: Jenkins API token (or password) for Jenkins server

``success_email``: email address where bv_maker outputs are sent in case of success. If not specified, no email will be sent and bv_maker outputs will be sent to the standard output. One email will be sent for each directory and build step that succeeds.

: email address where bv_maker outputs are sent in case of success. If not specified, no email will be sent and bv_maker outputs will be sent to the standard output. One email will be sent for each directory and build step that succeeds.

``smtp_server``: SMTP (email server) hostname to be used to send emails

``from_email``: displayed expeditor of sent emails. If not specified, it will be ``<user>-<hostname>@intra.cea.fr`` (the suffix is needed, and is correct for our lab)

: displayed expeditor of sent emails. If not specified, it will be 

``reply_to_email``: displayed reply email address in sent emails. If not specified, ``appli@saxifrage.saclay.cea.fr``.

: displayed reply email address in sent emails. If not specified, 

A source directory definition section starts with a line with the following syntax:

where ``<directory>`` is the name of the directory that will be created and whose content will synchronized with selected source directories located in BrainVISA Subversion server. The directory name can contain environment variable substitution by using ``$VARIABLE_NAME``. For instance, on Unix systems, ``$HOME/brainvisa`` will be replaced by the brainvisa directory located in the user home directory. If the specified directory does not exist, it will be created (as well as parent directories) when the sources will be processed by bv_maker.

 is the name of the directory that will be created and whose content will synchronized with selected source directories located in BrainVISA Subversion server. The directory name can contain environment variable substitution by using 

 will be replaced by the brainvisa directory located in the user home directory. If the specified directory does not exist, it will be created (as well as parent directories) when the sources will be processed by bv_maker.

The content of the source directory section is composed of a set of rules to select and unselect Subversion directories to copy in the source directory. Each source directory is first associated with an empty list of subdirectories. Then, the configuration file is parsed in order to modify this list. Each line in the source directory section correspond to an action that can modify the list. These actions are executed in the order they are given. It means that you can unselect directories previously selected or the contrary. For instance if one wants to select all components but one, he will make a first action to select all components and a second one to remove the component to ignore. There are three kind of actions that can be done to modify this list of subdirectories. The syntax of the configuration rules corresponding to these actions are described in the following paragraphs.

In the source section, it is also possible to define some option variables, delcared in the syntax ``option = value``. The following options are supported:

In the source section, it is also possible to define some option variables, delcared in the syntax 

``build_condition``: a condition which must be True to allow configure and build steps, otherwise they will be skipped. The condition is evaluated in **python language**, and is otherwise free: it may typically be used to restrict build to certain systems or hostnames, some dates, etc.

: a condition which must be True to allow configure and build steps, otherwise they will be skipped. The condition is evaluated in 

, and is otherwise free: it may typically be used to restrict build to certain systems or hostnames, some dates, etc.

``cross_compiling_dirs``: dictionary of directories. ``cross_compiling_dirs`` contains toolchain substitutions for source directory. This is used when execution needs different path to access sources (i.e.: in windows cross compilation, for pure python components, it is necessary to access source directories through network shares, instead of NFS mount point). For instance, the following configuration line: ``i686-w64-mingw32://computer/basedir`` will replace the source directory path with the UNC path ``//computer/basedir`` in a build directory that uses the i686-w64-mingw32 ``cross_compiling_prefix``. The network share ``//computer/basedir`` must have been properly configured on ``computer`` to be accessible.

 contains toolchain substitutions for source directory. This is used when execution needs different path to access sources (i.e.: in windows cross compilation, for pure python components, it is necessary to access source directories through network shares, instead of NFS mount point). For instance, the following configuration line: 

``revision_control``: ``ON`` (default) or ``OFF``. If enabled, revision control systems (*svn*, *git*) will be used to update the sources. If OFF, the sources directory will be left as is as a fixed sources tree.

) will be used to update the sources. If OFF, the sources directory will be left as is as a fixed sources tree.

``default_steps``: steps performed for this build directory when bv_maker is invoked without specifying steps (typically just ``bv_maker``). Defaults to: ``sources``.

: steps performed for this build directory when bv_maker is invoked without specifying steps (typically just 

``ignore_git_failure``: don't stop after the sources step if one or more git repositories cannot be updated in fast-forward mode (which also occurs when working on a non-principal branch). Later steps will thus be performed, but the source step will still be reported as failed.

: don’t stop after the sources step if one or more git repositories cannot be updated in fast-forward mode (which also occurs when working on a non-principal branch). Later steps will thus be performed, but the source step will still be reported as failed.

``revision_control``: ``ON`` (default) or ``OFF``. When ON, sources components will be updated using revision control systems (RCS) (svn, git...), and a list of valid components will be generated during the :ref:`sources step <sources_step>` and saved in a file, named ``components_sources.json`` in the main sources directory. If sources are only local, turning ``revision_control`` to OFF will avoid using RCS, but will still generate the list of components for building.

. When ON, sources components will be updated using revision control systems (RCS) (svn, git…), and a list of valid components will be generated during the 

 in the main sources directory. If sources are only local, turning 

 to OFF will avoid using RCS, but will still generate the list of components for building.

``stderr_file``: file used to redirect the standard error stream of bv_maker when email notification is used. This file is "persistant" and will not be deleted. If not specified, it will be mixed with standard output.

: file used to redirect the standard error stream of bv_maker when email notification is used. This file is “persistant” and will not be deleted. If not specified, it will be mixed with standard output.

``stdout_file``: file used to redirect the standard output stream of bv_maker when email notification is used. This file is "persistant" and will not be deleted. If neither it nor ``stderr_file`` are specified, then a temporary file will be used, and erased when each step is finished.

: file used to redirect the standard output stream of bv_maker when email notification is used. This file is “persistant” and will not be deleted. If neither it nor 

 are specified, then a temporary file will be used, and erased when each step is finished.

``update_git_remotes``: ``ON`` (default) or ``OFF``. If ON, all git remotes will be fetched, otherwise only the current active branch in a component will be fast-forwarded. The default value in brainvisa-cmake < 3 used to be ``OFF``, but this was changed in order to make things clearer/easier and to handle git-lfs projects. The former "light" mode (no fetch + detached branch mode) has been deprecated also: it still works for repositories created usinbg bv_maker 2.x but new repositories are not initialized this way any longer. See :ref:`git_repositories`

. If ON, all git remotes will be fetched, otherwise only the current active branch in a component will be fast-forwarded. The default value in brainvisa-cmake < 3 used to be 

, but this was changed in order to make things clearer/easier and to handle git-lfs projects. The former “light” mode (no fetch + detached branch mode) has been deprecated also: it still works for repositories created usinbg bv_maker 2.x but new repositories are not initialized this way any longer. See 

A line starting with a plus will use Subversion to add some directories from the BrainVISA BioProj repository. The selections of the directories is done by selecting components according to their name and version. Once the components are selected, bv_maker is able to find the corresponding directories in BrainVISA repository. component_selection is used to select a list of components according to their name (see `Component selection`_). It is not mandatory to provide a version_selection. If it is given, it is used to further filter the list of selected components according to their version (see `Version selection`_).

A line starting with a plus will use Subversion to add some directories from the BrainVISA BioProj repository. The selections of the directories is done by selecting components according to their name and version. Once the components are selected, bv_maker is able to find the corresponding directories in BrainVISA repository. component_selection is used to select a list of components according to their name (see 

). It is not mandatory to provide a version_selection. If it is given, it is used to further filter the list of selected components according to their version (see 

A line starting with a minus is has the same syntax as the previous action but removes the selected directories from the list.

In order to include some directories that do not correspond to registered BrainVISA components, one can directly give the directory name in ``repository_directory``. This directory name must be given relatively to the main BrainVISA repository URL: https://bioproj.extra.cea.fr/neurosvn/brainvisa. By default, ``repository_directory`` is also used to define where this directory will be in the source directory. It is not mandatory to provide a value for local_directory. If it is given, it is used instead of repositor_directory to define the directory location relatively to the source directory.

In order to include some directories that do not correspond to registered BrainVISA components, one can directly give the directory name in 

. This directory name must be given relatively to the main BrainVISA repository URL: 

 is also used to define where this directory will be in the source directory. It is not mandatory to provide a value for local_directory. If it is given, it is used instead of repositor_directory to define the directory location relatively to the source directory.

For instance, the following configuration will link the repository directory https://bioproj.extra.cea.fr/neurosvn/brainvisa/perso/myself/myproject with the local directory ``/home/myself/brainvisa/perso/myself/myproject``.

For instance, the following configuration will link the repository directory 

Whereas the following configuration will link the same repository directory with the local directory ``/home/myself/brainvisa/myproject``.

Whereas the following configuration will link the same repository directory with the local directory 

[ source /home/myself/brainvisa ]
  + perso/myself/myproject myproject

A build directory definition section starts with a line with the following syntax:

where ``<directory>`` is the name of the directory where the compilation results will be written. As the source directory, the build directory name can contain environment variable substitution.

 is the name of the directory where the compilation results will be written. As the source directory, the build directory name can contain environment variable substitution.

This section defines the list of components that will be built and their version and the source directory where they can be found. The components and versions are defined as they were in the source directory. It is also possible to remove components from the list with a line beginning with a minus.

:ref:`configure <configure_step>`: configure build and generate Makefiles using CMake.

:ref:`build <build_step>`: compile programs and libraries, install files (as symbolic links) in the build directory tree so as to be ready for local execution.

: compile programs and libraries, install files (as symbolic links) in the build directory tree so as to be ready for local execution.

:ref:`doc <doc_step>`: generate documentation for the built components.

:ref:`testref <testref_step>`: run tests in a special mode so as to generate reference data for later tests comparisons.

: run tests in a special mode so as to generate reference data for later tests comparisons.

In the build section, it is also possible to define some build options:

``cmake_options``: passed to cmake (ex: ``-DMY_VARIABLE=dummy``)

``ctest_options``: passed to ctest in the test step (ex: ``-j4 -VV -R carto*``)

``build_type``: ``Debug``, ``Release`` or none (no optimization options)

``clean_build``: ``ON`` or ``OFF`` (default), if set, the build tree will be cleaned of obsolete files before the build step (using the command ``bv_clean_build_tree``)

 (default), if set, the build tree will be cleaned of obsolete files before the build step (using the command 

``clean_config``: ``ON`` or ``OFF`` (default), if set, the build tree will be cleaned of obsolete files before the configuration step (using the command ``bv_clean_build_tree``)

 (default), if set, the build tree will be cleaned of obsolete files before the configuration step (using the command 

``cross_compiling_prefix``: toolchain name to use for cross-compilation mode. If ``cross_compiling_prefix`` is set, bv_maker runs in cross-compilation mode for the build directory (i.e. it adds definitions to tell cmake to work using a specific toolchain initial cache file, a specific toolchain file and the defined ``cross_compiling_prefix``). Toolchain initial cache file must be found at ``<brainvisa_cmake_directory>/cmake/toolchain/<cross_compiling_prefix>/init-cache.cmake``. Toolchain file must be found at ``<brainvisa_cmake_directory>/cmake/toolchain/<cross_compiling_prefix>/toolchain.cmake``. For instance, if ``<brainvisa_cmake_directory>`` is ``$HOME/brainvisa/source/brainvisa-cmake`` and ``cross_compiling_prefix`` is ``i686-w64-mingw32``, searched files are ``$HOME/brainvisa/source/brainvisa-cmake/cmake/toolchain/i686-w64-mingw32/init-cache.cmake`` and ``$HOME/brainvisa/source/brainvisa-cmake/cmake/toolchain/i686-w64-mingw32/toolchain.cmake``

 is set, bv_maker runs in cross-compilation mode for the build directory (i.e. it adds definitions to tell cmake to work using a specific toolchain initial cache file, a specific toolchain file and the defined 

``default_steps``: steps performed for this build directory when bv_maker is invoked without specifying steps (typically just ``bv_maker``). Defaults to: ``configure build``, but may also include ``doc`` and ``test``.

``test_ref_data_dir``: directory where reference data will be written (during :ref:`testref step <testref_step>`) and read (during :ref:`test step <test_step>`) for comparison.

``test_run_data_dir``: directory where data will be written during the :ref:`test step <test_step>`.

In the above example, the *bug_fix* version of standard components which are located in ``$HOME/brainvisa/source`` directory will be compiled in the build directory ``$HOME/brainvisa/build/bug_fix`` in ``Release`` mode with the option ``-j8`` passed to make command (compilation distributed on 8 processors).

 passed to make command (compilation distributed on 8 processors).

A build directory may also be a *python virtualenv* directory. To specify it the section type may be virtualenv instead of build:

 directory. To specify it the section type may be virtualenv instead of build:

A virtualenv directory will be initialized the first time it is used, and a python virtualenv environment will be installed there. Then it will be used as a build directory in addition. This allows to use ``pip install`` commands within it with a local install, just for this build directory.

A virtualenv directory will be initialized the first time it is used, and a python virtualenv environment will be installed there. Then it will be used as a build directory in addition. This allows to use 

 commands within it with a local install, just for this build directory.

Components can be selected according to their name and (in some context) to their version. This paragraph explain how to use component_selection and version_selection and gives some examples of their usage.

Information about the components, components groups and versions are extracted from git repository and stored in the following file: https://github.com/brainvisa/brainvisa-cmake/blob/master/python/brainvisa/maker/components_definition.py

Information about the components, components groups and versions are extracted from git repository and stored in the following file: 

A component_selection is a string that is used to select one or more component according to their name. The following rules are used to transform this string into a list of components:

If component_selection is a group name, all components of this group are selected. At the time of this writing, four groups are defined:

* **all** which contains all known components,
* **opensource** for all open source components
* **standard** containing only standard components of BrainVISA project
* **anatomist** containing Anatomist and its dependencies.

**standard** containing only standard components of BrainVISA project

If component_selection is a project name, all components of this project are selected

If component_selection is a component name, only this component is selected

Component selection must be a single pattern (with Unix shell-style wildcards) or two patterns separated by a colon:

#. If there is only one pattern, all components matching this pattern are selected
#. If there are two patterns, all components that are in a project matching the first pattern and that are matching the second pattern are selected

If there is only one pattern, all components matching this pattern are selected

If there are two patterns, all components that are in a project matching the first pattern and that are matching the second pattern are selected

To select the version of a component or a group of component, it is possible

to give the exact version number of a branch (4.0) or a tag (4.0.1)

to use one of the following keywords:

* **development**, **trunk**: trunk version in svn repository
* **bug_fix**, **branch**, **stable** : latest stable version, the higher version number in branches directory of svn repository
* **tag**, **latest_release**: latest tag version, the higher version number in tags directory of svn repository

**bug_fix**, **branch**, **stable** : latest stable version, the higher version number in branches directory of svn repository

 : latest stable version, the higher version number in branches directory of svn repository

**tag**, **latest_release**: latest tag version, the higher version number in tags directory of svn repository

: latest tag version, the higher version number in tags directory of svn repository

Select latest bug fixing branch of all components in anatomist project:

A section of the configuration file may contain conditional parts. This allows to specialize parts of the configuration according to host system, host name, or whatever.

A conditional subsection should be located inside an existing section (sources or build). It follows the syntax:

[ if <expression> ]
  <config lines>
  ...
[ else ]
  <other config lines>
[ endif ]

The ``[ else ]`` block is of course optional, and a global section end also ends the conditional section, so the ``[ endif ]`` section may be omitted if it is at the end of the section.

 block is of course optional, and a global section end also ends the conditional section, so the 

The condition expression may contain substitution variables as in the shape ``%(variable)s`` syntax. The following variables are recognized:

The condition expression may contain substitution variables as in the shape 

Other variables depend on the configuration of the section itself, which is only done later, so they are not available yet when parsing conditions.

The condition expression is then evaluated in python language (using the ``eval()`` function), thus allows all python language syntax and loaded libraries. The expression result is cast to a boolean value.

The condition expression is then evaluated in python language (using the 

 function), thus allows all python language syntax and loaded libraries. The expression result is cast to a boolean value.

  [ if gethostname() == 'my_machine' ]
    make_options = -j8
  [ else ]
    make_options = -j2
  [ endif ]

  - connectomist-*

  # ...
  cmake_options += -DDESIRED_QT_VERSION=5
  # ...

  # ...
  cmake_options += -DPYTHON_EXECUTABLE=/usr/bin/python3
  # ...

Under Unix (filesystems supporting symbolic links) , after building, a link to the matching python executable will be found in ``bin/python`` so that the ``python`` command within this build tree will point to ``python3`` and will be used by all python scripts.

Under Unix (filesystems supporting symbolic links) , after building, a link to the matching python executable will be found in 

There are two kinds of dependencies that are defined in brainvisa-cmake: compilation dependencies and packaging dependencies. Compilation dependencies are declared by standard CMake commands such as find_package. But these commands cannot be used to identify the dependencies of the runtime, development or source packages that will be distributed. For instance, if a component uses the two following lines:

These two compilation dependencies are identical. However, on the one hand, ``find_package( libjpeg )`` implies that the runtime package depends on a package containing ``libjpeg.so`` (assuming dynamic link) and the development package requires a package containing the headers (``*.h``) of *libjpeg*. On the other hand, ``find_package( doxygen )`` implies only that the development package requires Doxygen in order to build the development documentation.

These two compilation dependencies are identical. However, on the one hand, 

 implies that the runtime package depends on a package containing 

 (assuming dynamic link) and the development package requires a package containing the headers (

 implies only that the development package requires Doxygen in order to build the development documentation.

Therefore it is necessary to explicitly define packaging dependencies in brainvisa-cmake.

Each component compiled with brainvisa-cmake can lead to several packages:

The **runtime package** which is the main package containing all necessary files to use the component (e.g. programs, dynamic libraries, configuration files, etc.).

 which is the main package containing all necessary files to use the component (e.g. programs, dynamic libraries, configuration files, etc.).

The **development** package that contains supplementary files allowing to develop programs that use the component (e.g. C header files, cmake files, etc.).

 package that contains supplementary files allowing to develop programs that use the component (e.g. C header files, cmake files, etc.).

The **documentation** packages contain documentation about the component.
The documentation itself divides into:

* **user documentation**
* **development documentation**

 packages contain documentation about the component.

the **test** package contains test material (scripts, programs, data)

*Brainvisa-cmake* defines a function in order to define the packaging dependencies of each package type:

 defines a function in order to define the packaging dependencies of each package type:

BRAINVISA_DEPENDENCY( <pack_type> <dependency_type> <component> <component_pack_type> [ <version ranges> ] [BINARY_INDEPENDENT] ).

The package types can be: **RUN**, **DEV**, **DOC**, **USRDOC**, **DEVDOC**, **TST**.

*Brainvisa-cmake* allows to declare four different kinds of relationship between packages: **Depends**, **Recommends**, **Suggests** and **Enhances**. The meaning of these relationships is described in the `Debian Policy Manual <https://www.debian.org/doc/debian-policy/ch-relationships.html>`_.

 allows to declare four different kinds of relationship between packages: 

`Debian Policy Manual <https://www.debian.org/doc/debian-policy/ch-relationships.html>`_

More information about the usage of this function can be found in the section :doc:`compile_existing`.

More information about the usage of this function can be found in the section 

Note about how to handle binary incompatibilities (not used yet)

To handle **binary incompatibilities** between packages, it is necessary to provide information to brainvisa-installer. It is possible to rely on the dependency system to code this information. When a package has to be recompiled because one of its dependencies has changed, the new package may be binary incompatible with the old one; even if the source of the component have not been changed. For instance if Aims is modified in a binary incompatible way, it is necessary to recompile Anatomist but the new compiled version will not be binary compatible with the previous one. This situation would lead to two different Anatomist packages containing the same Anatomist versions but with two different binary signatures.

 between packages, it is necessary to provide information to brainvisa-installer. It is possible to rely on the dependency system to code this information. When a package has to be recompiled because one of its dependencies has changed, the new package may be binary incompatible with the old one; even if the source of the component have not been changed. For instance if Aims is modified in a binary incompatible way, it is necessary to recompile Anatomist but the new compiled version will not be binary compatible with the previous one. This situation would lead to two different Anatomist packages containing the same Anatomist versions but with two different binary signatures.

If we can attach a unique number to each binary signature of a specific version of a component, we would be able to include this number into the package version. For instance, the previous example could lead to two packages ``anatomist-3.2.0-0`` and ``anatomist-3.2.0-1`` where ``3.2.0`` is Anatomist version and the fourth number identifies binary signature changes. With this version system, packages that are binary linked to another package would include a dependency with a full version, including binary signature number. But a package that requires a specific version but without binary linking (such as Python extensions) would ignore the binary signature number in their dependencies.

If we can attach a unique number to each binary signature of a specific version of a component, we would be able to include this number into the package version. For instance, the previous example could lead to two packages 

 is Anatomist version and the fourth number identifies binary signature changes. With this version system, packages that are binary linked to another package would include a dependency with a full version, including binary signature number. But a package that requires a specific version but without binary linking (such as Python extensions) would ignore the binary signature number in their dependencies.

The number representing the binary signature can be a counter that is incremented each time a new package with the same version is compiled. The good point for this solution is that it gives easily readable versions on packages. The drawback is that we must provide a way for brainvisa-cmake to store a counter for each component. It can be hard to do if compilation is not always done on the same build tree. Another possibility would be to use compilation date with the format ``YYYYMMDD`` (assuming that there is not two releases of a component on the same day). For instance a package ``anatomist-free_3.2.0.20091011_ubuntu-9.04_i686.deb`` would mean Anatomist version ``3.2.0`` compiled on October, 11th 2009. It is much easier to implement but leads to not very good looking version strings.

The number representing the binary signature can be a counter that is incremented each time a new package with the same version is compiled. The good point for this solution is that it gives easily readable versions on packages. The drawback is that we must provide a way for brainvisa-cmake to store a counter for each component. It can be hard to do if compilation is not always done on the same build tree. Another possibility would be to use compilation date with the format 

 (assuming that there is not two releases of a component on the same day). For instance a package 

 compiled on October, 11th 2009. It is much easier to implement but leads to not very good looking version strings.

Thanks to the dependencies definition, the use of this binary signature number can be completely managed by brainvisa-cmake during packaging. The developer of a component would only have to indicate, for each runtime dependency, whether there is a binary link or not. I suggest to define a binary link by default unless the **BINARY_INDEPENDENT** option is used.

Thanks to the dependencies definition, the use of this binary signature number can be completely managed by brainvisa-cmake during packaging. The developer of a component would only have to indicate, for each runtime dependency, whether there is a binary link or not. I suggest to define a binary link by default unless the 

note about how to handle binary incompatibilities (not used yet)

Third-party dependencies used to be packaged but this is not supported anymore starting with the container-based BrainVISA releases (BrainVISA 5.0).

Documentation in software projects is supported via external tools like `Doxygen <http://www.doxygen.org>`_ or `Sphinx <http://sphinx-doc.org>`_, and are integrated in brainvisa-cmake infrastructure.

Documentation in software projects is supported via external tools like 

Documentation is generated within the ``doc`` step of ``bv_maker``:

Alternatively, building documentation can be triggered via the ``make`` command from a build directory. Several targets control documentation:

 command from a build directory. Several targets control documentation:

and generally project-specific targets will exist, like for instance:

Documentation for a project will be generated in a subdirectory of the build tree, in:

`Doxygen <http://www.doxygen.org>`_ is used to genrate API documentation for C++ sources. It generates HTML pages, an possibly other formats, which we are not using in ``brainvisa-cmake``.

 is used to genrate API documentation for C++ sources. It generates HTML pages, an possibly other formats, which we are not using in 

In ``brainvisa-cmake`` projects, such documentation should be setup in the ``CMake`` config files of the project. Typically we set it in the main ``CMakeLists.txt`` file at the root of the project.

The Doxygen component has to be found using ``find_package( Doxygen )``

``Brainvisa-cmake`` provides a function :ref:`brainvisa_generate_doxygen_doc` to build Doxygen doc:

  set( DOXYFILE_PREDEFINED "${SOMA-IO_DEFINITIONS}")
  set( _doxyheaders ${_headers} "config/config.h" ) # add config.h file
    _doxyheaders
    INPUT_PREFIX "${CMAKE_BINARY_DIR}/include/cartobase"
    COMPONENT "cartobase" )
endif()

  set( DOXYFILE_HTML_HEADER "\"${CMAKE_CURRENT_SOURCE_DIR}/head_anatomist.html\"" )
  set( _doxygenInput ${HEADERS} )
  set( DOXYFILE_PREDEFINED ${ANATOMIST_DEFINITIONS} ${AIMS-FREE_DEFINITIONS}
    ${SOMA-IO_DEFINITIONS} CARTO_USE_BLITZ )
  set(aims-free_version
    "${aims-free_VERSION_MAJOR}.${aims-free_VERSION_MINOR}")
  set(_somaio_version "${soma-io_VERSION_MAJOR}.${soma-io_VERSION_MINOR}")
  set( DOXYFILE_TAGFILES
    "${CMAKE_BINARY_DIR}/share/doc/aimsgui-${aims-free_version}/doxygen/aimsgui.tag=../../aimsgui-${aims-free_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/aimsdata-${aims-free_version}/doxygen/aimsdata.tag=../../aimsdata-${aims-free_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/graph-${aims-free_version}/doxygen/graph.tag=../../graph-${aims-free_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/cartobase-${_somaio_version}/doxygen/cartobase.tag=../../cartobase-${_somaio_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/soma-io-${_somaio_version}/doxygen/soma-io.tag=../../cartobase-${_somaio_version}/doxygen ${CMAKE_BINARY_DIR}/share/doc/cartodata-${aims-free_version}/doxygen/cartodata.tag=../../cartodata-${aims-free_version}/doxygen")
    _doxygenInput
    head_anatomist.html anatomist.png anatomist.gif
    INPUT_PREFIX "${CMAKE_BINARY_DIR}/include/anatomist"
    COMPONENT "anatomist" )
  add_dependencies( anatomist-doxygen aimsgui-doxygen aimsdata-doxygen graph-doxygen soma-io-doxygen cartobase-doxygen cartodata-doxygen )
endif()

`Sphinx <http://sphinx-doc.org>`_ is used to build HTML documentation pages. It can be used to make general documentation, and can also make API documentation for Python classes and modules.

 is used to build HTML documentation pages. It can be used to make general documentation, and can also make API documentation for Python classes and modules.

``brainvisa-cmake`` provides a function to build sphinx documentation for a project: :ref:`brainvisa_generate_sphinx_doc`.

 provides a function to build sphinx documentation for a project: 

find_package( Sphinx )
BRAINVISA_GENERATE_SPHINX_DOC( "sphinxdoc/user_doc"
  "share/doc/axon-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}/user_doc" USER )
BRAINVISA_GENERATE_SPHINX_DOC( "sphinxdoc/dev_doc"
  "share/doc/axon-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}/dev_doc" )

In pure python projects, the CMake configuration file is not present in the sources, and is generated by bv_maker. If the project sources contain a directory tree ``doc/sources``, then bv_maker will consider it as a Sphinx source directory and configure it to generate sphinx development docs, as in the CMake case.

In pure python projects, the CMake configuration file is not present in the sources, and is generated by bv_maker. If the project sources contain a directory tree 

, then bv_maker will consider it as a Sphinx source directory and configure it to generate sphinx development docs, as in the CMake case.

Sphinx sources should be located in a subdirectory of the project sources tree. The directory should contain the ``conf.py`` file expected by sphinx.

Sphinx sources should be located in a subdirectory of the project sources tree. The directory should contain the 

For new developers, in a few words, Sphinx sources are text files using a markup language, `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ which is fairly simple and mostly human readable.

For new developers, in a few words, Sphinx sources are text files using a markup language, 

The entry point is generally a ``index.rst`` file which may include other ones.

Using CMake commands, it is possible to mix Doxygen or Sphinx docs with other processings, for instance generation of commandline help, or pre-building of HTML tables etc. All kinds of scripts can be triggered by CMake when generating docs, and the Sphinx builds, especially, may use a part of sources which could be generated by other scripts.

In BrainVisa, we use it for instance to build the complete web site http://brainvisa.info

In BrainVisa, we use it for instance to build the complete web site 

It handles all CMake does (compilation for compiled languages, build directopry preparation, test, installation), plus:

Multi-project handling: builds in a single build directory tree a set of projects

:doc:`How to compile a new project with brainvisa-cmake <new_project>`

:doc:`Testing and monitoring infrastructure <testing_monitoring>`

**project_info.cmake**: describes the name and version of the project.

  * Alternatively, for a Python project, this file can be replaced by a python file, **info.py** located in a python subdirectory.

See also the section `How to create version files with brainvisa-cmake`_.

* Alternatively, for a Python project, this file can be replaced by a python file, **info.py** located in a python subdirectory.

Alternatively, for a Python project, this file can be replaced by a python file, **info.py** located in a python subdirectory.

Alternatively, for a Python project, this file can be replaced by a python file, 

**CMakeLists.txt**: describes the elements which will be generated when the project will be built.

: describes the elements which will be generated when the project will be built.

Moreover, the new project must be declared in bv_maker.cfg to enable its compilation with bv_maker.

**Example:** project_info file for ``anatomist-free`` component of anatomist project.

The following file is in ``anatomist/anatomist-free/tags/4.5/project_info.cmake``.

set( BRAINVISA_PACKAGE_NAME anatomist-free )
set( BRAINVISA_PACKAGE_MAIN_PROJECT anatomist )
set( BRAINVISA_PACKAGE_MAINTAINER "CEA - IFR 49" )
set( BRAINVISA_PACKAGE_VERSION_MAJOR 4 )
set( BRAINVISA_PACKAGE_VERSION_MINOR 5 )
set( BRAINVISA_PACKAGE_VERSION_PATCH 0 )
set( BRAINVISA_PACKAGE_LICENCES "CeCill-B" )

set( BRAINVISA_PACKAGE_NAME axon )
set( BRAINVISA_PACKAGE_MAIN_PROJECT axon )
set( BRAINVISA_PACKAGE_MAINTAINER "IFR 49" )
set( BRAINVISA_PACKAGE_VERSION_MINOR 6 )
set( BRAINVISA_PACKAGE_LICENCES "CeCill-V2" )

A few additional optional variables may be set in project_info.cmake:

If your project is only using the Python language, you may like to use a python file to describe this information, because it would also be usable in the project code as a python module.

Thus, alternatively to the ``project_info.cmake`` file, *brainvisa-cmake* will look for an ``info.py`` file, located:
* in a ``<modules>`` subdirectory of the project directory.
* or in a ``python/<modules>`` subdirectory of the project directory.

or in a ``python/<modules>`` subdirectory of the project directory.

This file contains basically the same information as ``project_info.cmake`` but in pyton language:

NAME = 'soma-base'
PROJECT = 'soma'      # optional, taken as NAME if omitted
MAINTAINER = "CEA"    # optional
LICENSE = "CeCILL-B"
version_major = 4
version_minor = 5
version_micro = 8

Other variables are of course allowed, it is a standard python files. The variables above will be translated to those of ``project_infi.cmake`` and will be available under the latter names in ``CMakeLists.txt`` files:

Other variables are of course allowed, it is a standard python files. The variables above will be translated to those of 

PROJECT -> BRAINVISA_PACKAGE_MAIN_PROJECT
NAME -> BRAINVISA_PACKAGE_NAME
MAINTAINER -> BRAINVISA_PACKAGE_MAINTAINER
LICENSE -> BRAINVISA_PACKAGE_LICENCES
version_major -> BRAINVISA_PACKAGE_VERSION_MAJOR
version_minor -> BRAINVISA_PACKAGE_VERSION_MINOR
version_micro -> BRAINVISA_PACKAGE_VERSION_PATCH

It is possible to use *brainvisa-cmake* to generate source code containing the version stored in ``project_info.cmake``. Here is an example from old_connectomist project. There are two template files, one for C++ and one for Python:

. Here is an example from old_connectomist project. There are two template files, one for C++ and one for Python:

#ifndef COMIST_VERSION_H
#define COMIST_VERSION_H

#define connectomist_version "@connectomist_VERSION@"

#endif // ifndef COMIST_VERSION_H

These config files are used in ``CMaleLists.txt`` to generate the matching ``config.h`` and ``config.py`` at configure step:

configure_file( "${CMAKE_CURRENT_SOURCE_DIR}/config/config.py.in" "${CMAKE_BINARY_DIR}/python/connectomist/config.py" @ONLY )
BRAINVISA_INSTALL( FILES "${CMAKE_BINARY_DIR}/python/connectomist/config.py"
                  DESTINATION "python/connectomist"
                  COMPONENT ${PROJECT_NAME} )
configure_file( "${CMAKE_CURRENT_SOURCE_DIR}/config/config.h.in" "${CMAKE_BINARY_DIR}/include/connectomist/config.h" @ONLY )
BRAINVISA_INSTALL( FILES "${CMAKE_BINARY_DIR}/include/connectomist/config.h"
                  DESTINATION "include/connectomist"
                  COMPONENT ${PROJECT_NAME}-dev )

This file is used by `CMake <http://www.cmake.org>`_ to generate the ``Makefiles`` that will be used to build the project.

This file is written in the CMake specific language. See `CMake documentation <https://cmake.org/documentation>`_ for more information.

On top of the classic CMake functions, we defined functions in *brainvisa-cmake* that help defining ``CMakeLists`` files for Brainvisa projects. These functions names start with ``BRAINVISA_`` and are defined in the file ``brainvisa-cmake-config.cmake.in`` in *brainvisa-cmake* project.

 files for Brainvisa projects. These functions names start with 

**Example:** ``CMakeLists.txt`` of *morphologist-gpl* component of the *morphologist* project.

cmake_minimum_required( VERSION 3.10 )
find_package( brainvisa-cmake REQUIRED )
BRAINVISA_PROJECT()

BRAINVISA_COPY_PYTHON_DIRECTORY( "${CMAKE_CURRENT_SOURCE_DIR}/brainvisa"
                                 ${PROJECT_NAME} )

BRAINVISA_COPY_DIRECTORY( "${CMAKE_CURRENT_SOURCE_DIR}/doc"
                          "share/doc/t1mri-${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_VERSION_MINOR}"
                          ${PROJECT_NAME}-usrdoc )

BRAINVISA_CREATE_CMAKE_CONFIG_FILES()

The first 3 lines are mandatory, they check the version of cmake, search for brainvisa_cmake project and initialize the current project information reading the project_info.cmake file.

The rest of the file depends on the content of the component. In the previous example, t1mri-gpl only contains a Brainvisa toolbox (python files) and some documentation. The Brainvisa toolbox files and the documentation will be linked in the build directory.

The last line is useful only if the component is a dependency of another one. If so, you need to write 2 more files in a cmake directory: ``<component>-config.cmake.in`` and ``<component>-use.cmake.in``.

The last line is useful only if the component is a dependency of another one. If so, you need to write 2 more files in a cmake directory: 

Here is a glimpse of the *brainvisa-cmake* helper functions which can be used in the ``CMakeLists.txt`` files.

BRAINVISA_GET_FILE_LIST_FROM_PRO( proFilename <pro variable> <cmake variable> [<pro variable> <cmake variable>...] )

This function was useful when we switched from our home made tool *build-config* to cmake because build-config used ``.pro`` files (similar to Qt's Qmake) containing the list of headers and sources files needed to build a target. With this function, existing ``.pro`` files can be reused in ``CMakeLists`` files.

This function was useful when we switched from our home made tool 

 files (similar to Qt’s Qmake) containing the list of headers and sources files needed to build a target. With this function, existing 

BRAINVISA_GET_FILE_LIST_FROM_PRO( "${_pro}"
                                  TARGET _target
                                  SOURCES _proSources )

*_target* variable contains the name of the lib or executable target.

BRAINVISA_COPY_AND_INSTALL_HEADERS( <headers list> <include directory> <target_variable> [NO_SYMLINKS] )

Copies or creates symlinks on the header files in the include directory of the build directory.

BRAINVISA_GET_FILE_LIST_FROM_PRO( project.pro "HEADERS" _headers "SOURCES" _sources )
BRAINVISA_COPY_AND_INSTALL_HEADERS( _headers anatomist headersTarget )
add_library( anatomist SHARED ${_sources} )
add_dependencies( anatomist ${headersTarget} )

The list of header and source files is extracted from the ``project.pro`` file. The headers are linked in ``<build_directory>/include/anatomist``. The anatomist shared library is created from the source files. A dependency is added between the creation of the library and the copy of the headers.

. The anatomist shared library is created from the source files. A dependency is added between the creation of the library and the copy of the headers.

BRAINVISA_COPY_PYTHON_DIRECTORY ( <python directory&gt <component> [<destination directory>] [NO_SYMLINKS] )

Create targets to copy, byte compile and install all Python code contained in a directory. If the destination directory is not set, the right most directory name in the python directory is used.

BRAINVISA_COPY_PYTHON_DIRECTORY( "${CMAKE_CURRENT_SOURCE_DIR}/python"

The ``python`` directory in source directory will be linked in the ``python`` directory of the build directory.

The ``brainvisa`` directory in source directory will be linked in the ``brainvisa`` directory of the build directory.

BRAINVISA_ADD_SIP_PYTHON_MODULE( <module> <directory> <mainSipFile> [ SIP_SOURCES <file> ... ] [ SIP_INCLUDE <directory> ... ] [ SIP_INSTALL <directory> ] )

BRAINVISA_ADD_SIP_PYTHON_MODULE( anatomistsip
    anatomist/cpp
    "${CMAKE_BINARY_DIR}/${ANATOMIST_RELATIVE_SIP_DIRECTORY}/anatomist_VOID.sip"
    SIP_SOURCES ${_generatedSipFileList} ${_sipSources}
    SIP_INCLUDE "${CMAKE_BINARY_DIR}/${ANATOMIST_RELATIVE_SIP_DIRECTORY}"
      "${AIMS-FREE_SIP_DIRECTORY}" "${PYQT${DESIRED_QT_VERSION}_SIP_DIR}"
    SIP_INSTALL "${ANATOMIST_RELATIVE_SIP_DIRECTORY}" )

A library named *anatomistsip* will be created in ``python/anatomist/cpp`` directory in build directory from the sources files indicated.

Creates a makefile target to generate the C++ code needed to replace ``Q_OBJECT`` macro. It uses the Qt Meta-Object compiler (moc).

Creates a makefile target to generate the C++ code needed to replace 

BRAINVISA_ADD_MOC_FILES( _sources ${_headers} )

The files generated by moc will be added to the source files used to generate anatomist library.

BRAINVISA_ADD_TRANSLATION <source_share_dir> <dest_share_dir> <component>

Searches recursively qt linguist source files (``*.ts``) in the source share directory and generates the commands to create the associated ``*.qm`` files in the build share directory and creates associated install rules.

) in the source share directory and generates the commands to create the associated 

 files in the build share directory and creates associated install rules.

BRAINVISA_COPY_FILES( <component> <source files> [SOURCE_DIRECTORY <directory>] DESTINATION <destination directory> [IMMEDIATE] [GET_TARGET <target variable>][GET_OUTPUT_FILES <target variable>] [NO_SYMLINKS] )

Copies a list of files from the source directory to a directory in the build directory.

BRAINVISA_COPY_FILES(${PROJECT_NAME}-devdoc ${CMAKE_CURRENT_SOURCE_DIR}/changelog.html
    DESTINATION share/doc/cartodata-${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_VERSION_MINOR}/doxygen )

BRAINVISA_COPY_DIRECTORY( <source directory> <destination directory> <component> [IMMEDIATE] [GET_TARGET <target variable>] [NO_SYMLINKS] )

Recursively copies and installs all files in ``<source directory>`` except files named ``CMakeLists.txt``, ``*~``, ``*/.svn/*``, ``*.odt``, ``*.odp``, ``*.doc``, ``*.sdw``, ``*.sxw``.

BRAINVISA_COPY_DIRECTORY( "${CMAKE_CURRENT_SOURCE_DIR}/share"
                          "share/${PROJECT_NAME}-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}"
                          ${PROJECT_NAME} )
                          "share/doc/${PROJECT_NAME}-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}"
BRAINVISA_COPY_DIRECTORY( "${CMAKE_CURRENT_SOURCE_DIR}/bin"
                          bin
BRAINVISA_COPY_DIRECTORY( "${CMAKE_CURRENT_SOURCE_DIR}/scripts"
                          scripts

BRAINVISA_GENERATE_DOXYGEN_DOC( <input_variable> [<file to copy> ...] [INPUT_PREFIX <path>] [COMPONENT <name>] )

Adds rules to generate doxygen documentation (documentation of C++ source files) with "make doc" or "make devdoc".

Adds rules to generate doxygen documentation (documentation of C++ source files) with “make doc” or “make devdoc”.

``<input_variable>``: variable containing a string or a list of input sources.

``<file to copy>``: file (relative to ``${CMAKE_CURRENT_SOURCE_DIR}``) to copy in the build tree. Files are copied in ``${DOXYGEN_BINARY_DIR}`` if defined, otherwise they are copied in ``${PROJECT_BINARY_DIR}/doxygen``. The doxygen configuration file is generated in the same directory.

. The doxygen configuration file is generated in the same directory.

``<component>``: component name for this doxygen documentation. it is used to create the output directory and the tag file name. By default it is the ``PROJECT_NAME``. But it is useful to give an alternative name when there are several libraries documented with doxygen in the same project.

: component name for this doxygen documentation. it is used to create the output directory and the tag file name. By default it is the 

. But it is useful to give an alternative name when there are several libraries documented with doxygen in the same project.

Before calling this function, it is possible to specify values that are going to be written in doxygen configuration file by setting variable names ``DOXYFILE_<doxyfile variable name>``. For instance, in order to set project name in Doxygen, one should use:

Before calling this function, it is possible to specify values that are going to be written in doxygen configuration file by setting variable names 

FIND_PACKAGE( Doxygen )
IF ( DOXYGEN_FOUND )
    SET(component_name "cartodata")
    set( DOXYFILE_PREDEFINED "${AIMS_DEFINITIONS}")
    set(aims_version "${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_VERSION_MINOR}")
    set( DOXYFILE_TAGFILES "${CMAKE_BINARY_DIR}/share/doc/cartobase-${aims_version}/doxygen/cartobase.tag=../../cartobase-${aims_version}/doxygen")
    BRAINVISA_GENERATE_DOXYGEN_DOC( _headers
                                    INPUT_PREFIX "${CMAKE_BINARY_DIR}/include/${component_name}"
                                    COMPONENT "${component_name}")
    add_dependencies( ${component_name}-doxygen cartobase-doxygen )
ENDIF ( DOXYGEN_FOUND )

BRAINVISA_GENERATE_EPYDOC_DOC( <source directory> [ <source directory> ... ] <output directory> [ EXCLUDE <exclude list> ] )

Generates documentation for python source files with Epydoc. No longer used, we write sphinx doc now.

BRAINVISA_GENERATE_SPHINX_DOC( <source directory> <output directory> [TARGET <target_name>] )

BRAINVISA_GENERATE_SPHINX_DOC( "sphinxdoc/sphinx"
    "share/doc/axon-${BRAINVISA_PACKAGE_VERSION_MAJOR}.${BRAINVISA_PACKAGE_VERSION_MINOR}/sphinx" )

BRAINVISA_GENERATE_DOCBOOK_DOC( [EXCLUDE <docbook_project_name>] )

Generates docbook documentation. No longer used either, we are using sphinx.

BRAINVISA_DEPENDENCY( <pack_type> <dependency_type> <component> <component_pack_type> [ <version ranges> ] [BINARY_INDEPENDENT] )

This function enables to declare that the current brainvisa component has a dependency on another component. That other component can be a Brainvisa component or a thirdparty dependency.

``<pack_type>``: type of package which have this dependency. Indeed, the compilation and runtime dependencies are not necessary the same. Can be ``RUN`` for runtime package, ``DEV`` for development package or ``DOC`` for documenation package.

: type of package which have this dependency. Indeed, the compilation and runtime dependencies are not necessary the same. Can be 

``<dependency_type>``: indicates if the dependency is mandatory or not. Can be ``DEPENDS`` or ``RECOMMENDS``.

``<component_pack_type>``: type of package for the dependency package: ``RUN``, ``DEV`` or ``DOC``.

``<version ranges>``: required version of the dependency package.

``BINARY_INDEPENDENT`` can be added to indicate that the component and its dependency are binary independent (dependency between python modules for example) but this information is not used currently.

 can be added to indicate that the component and its dependency are binary independent (dependency between python modules for example) but this information is not used currently.

At configuration time, the information declared in this function will be written in a file named ``compilation_info.py`` in the directory ``<build_directory>/python/brainvisa``. This file was used by the :doc:`bv_packaging` script to create Brainvisa packages with the needed dependencies.

At configuration time, the information declared in this function will be written in a file named 

 script to create Brainvisa packages with the needed dependencies.

BRAINVISA_DEPENDENCY( RUN DEPENDS aims-gpl RUN "= ${aims-gpl_VERSION}" )
BRAINVISA_DEPENDENCY( DEV DEPENDS aims-gpl DEV )
BRAINVISA_DEPENDENCY( RUN DEPENDS libqtcore4 RUN ">= ${QT_VERSION}" )
BRAINVISA_DEPENDENCY( DEV DEPENDS libqtcore4 DEV )
BRAINVISA_DEPENDENCY( RUN DEPENDS libqwt5-qt4 RUN)

Be careful, if you want to use directly the ``make install`` command to install files of the build directory in another location, you'll have to specify the variable ``BRAINVISA_INSTALL_PREFIX`` in the make install command. The historical justification is that in order to be able to specify an install location when using :doc:`bv_packaging` script, we had to use a variable that have to be defined at installation step instead of the ``CMAKE_INSTALL_PREFIX`` which is defined at configuration step.

 command to install files of the build directory in another location, you’ll have to specify the variable 

 in the make install command. The historical justification is that in order to be able to specify an install location when using 

 script, we had to use a variable that have to be defined at installation step instead of the 

bv_maker allows to run tests, notify, and log the results of build, tests, and packaging operations.

Basically, tests can be run through the :doc:`bv_maker` command:

Of course options may be added to restrict to some build directories for instance using the ``-d`` option (see :doc:`bv_maker options <bv_maker>` for details).

Of course options may be added to restrict to some build directories for instance using the 

``bv_maker`` also has :ref:`options specific to the test step <test_step>`, namely the ``-t`` option which may be used to run only a part of tests. For instance:

 option which may be used to run only a part of tests. For instance:

will run tests in verbose mode, and run only tests whth names starting with ``carto``.

will run tests in verbose mode, and run only tests whth names starting with 

Basically, this ``bv_maker`` command runs `ctest <https://cmake.org/cmake/help/v3.0/manual/ctest.1.html>`_ so it is also possible to go into a build directory, and run ``ctest``, or ``make test``, by hand:

These commands will do almost the same as the bv_maker variant, except that notification and logging will not take place.

Similarly, bv_maker allows to test installed packages, after bv_maker steps :ref:`pack <pack_step>` and :ref:`install_pack <install_pack_step>` have been successfully done. This is the :ref:`test_pack <test_pack_step>` step.

Similarly, bv_maker allows to test installed packages, after bv_maker steps 

In this situation, tests are performed as configured in the corresponding build tree, but are running programs in an installed binary package.

Tests may be run in a different environment: on a different machine (through ``ssh``), or via a `docker container <http://www.docker.com>`_ for instance, or both, as configured in the ``bv_maker.cfg`` file: see `Configuring installed packages tests`_. This way, tests can be run in a realistic situation as if the software is installed on a different (and minimal) client machine.

Tests may be run in a different environment: on a different machine (through 

. This way, tests can be run in a realistic situation as if the software is installed on a different (and minimal) client machine.

Here again, options are allowed to restrict to specific package directories, part of tests etc. Note that the ``-d`` option here must refer to a :ref:`package directory <package_directory>`, which may admit some fancy wildcards, and must be specified the same way. As an example, for our build system for BrainVisa, we may use:

Here again, options are allowed to restrict to specific package directories, part of tests etc. Note that the 

, which may admit some fancy wildcards, and must be specified the same way. As an example, for our build system for BrainVisa, we may use:

bv_maker -d '/neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/packages' test_pack -t '-VV -R carto*'

Contrarily to build directories tests, the ``test_pack`` step cannot be run through a ``ctest`` or ``make`` command equivalent, because ``bv_maker`` has to setup tesing into the installed package before running tests, in a way that is not recorded in cmake/make configuration.

 has to setup tesing into the installed package before running tests, in a way that is not recorded in cmake/make configuration.

Some tests will work fine using internal tests or by generating tempory synthetic data to test its processing. But in some other cases, additional data will be needed. Typically:

input data may be needed to feed processing tests which should run with "real" data. Such data may be quite large, so the test system may download data from a remote URL or get it from a given read-only directory.

input data may be needed to feed processing tests which should run with “real” data. Such data may be quite large, so the test system may download data from a remote URL or get it from a given read-only directory.

reference data: many tests will generate output (processed) data from input data. To check if the output data are OK, some reference data must be compared to tests results. Reference data can be generated through bv_maker by running tests in a special mode: :ref:`testref <testref_step>` or :ref:`testref_pack <testref_pack_step>` for package tests.

reference data: many tests will generate output (processed) data from input data. To check if the output data are OK, some reference data must be compared to tests results. Reference data can be generated through bv_maker by running tests in a special mode: 

test data: these data will be produced during regular tests. Normally they could be just temporary files which can be deleted after testing, but it is useful to store them for manual checking and debugging when tests fail.

Hence two additional :doc:`bv_maker` steps can be used to generate reference data:

:ref:`testref <testref_step>` will run tests and write reference results for later comparison during :ref:`test <test_step>` steps

 will run tests and write reference results for later comparison during 

:ref:`testref_pack <testref_pack_step>` will run tests from installed packages and write reference results for later comparison during :ref:`test_pack <test_pack_step>` steps

 will run tests from installed packages and write reference results for later comparison during 

Data directoryes are passed to test programs through environment variables, with values that can be specified in :doc:`configuration` variables:

Data directoryes are passed to test programs through environment variables, with values that can be specified in 

reference data: the ``bv_maker.cfg`` config file may contain in its build and package directories sections a ``test_ref_data_dir`` variable, which will specify where reference data will be written (in :ref:`testref <testref_step>`  and :ref:`test_pack <test_pack_step>` steps). The value here may contain environment variables and "python-style" variables substitution to differentiate data directories across configurations or systems. When tests are actually running, the value here will be passed to test programs through the ``BRAINVISA_TEST_REF_DATA_DIR`` environment variable.

 config file may contain in its build and package directories sections a 

 variable, which will specify where reference data will be written (in 

 steps). The value here may contain environment variables and “python-style” variables substitution to differentiate data directories across configurations or systems. When tests are actually running, the value here will be passed to test programs through the 

run test data: the ``bv_maker.cfg`` config file may contain in its build and package directories sections a ``test_run_data_dir`` variable, which will specify where reference data will be written (in :ref:`test <test_step>`  and :ref:`test_pack <test_pack_step>` steps). The value here may contain environment variables and "python-style" variables substitution to differentiate data directories across configurations or systems. When tests are actually running, the value here will be passed to test programs through the ``BRAINVISA_TEST_RUN_DATA_DIR`` environment variable. If this variable is not defined, then a temporary directory may be used for tests.

 environment variable. If this variable is not defined, then a temporary directory may be used for tests.

``bv_maker`` may use several kinds of notification  when its different steps finish, or when they fail.

 may use several kinds of notification  when its different steps finish, or when they fail.

If any step fails, the :doc:`bv_maker` commend will exit with a non-null exit code, and print a summary of steps status for each build or package directory.

 commend will exit with a non-null exit code, and print a summary of steps status for each build or package directory.

Emails can be sent when a bv_maker step finishes, or only in case of failure.

Such notification and logging have to be setup in the :doc:`bv_maker.cfg configuration file <configuration>`, more precisely in the :ref:`general section <general_section>` of it:

[ general ]
email_notification_by_default = ON
failure_email = myname@myserver.com
success_email = myname@myserver.com
smtp_server = mail.myserver.com
from_email = myself@myserver.com
reply_to_email = support@myserver.com

Note that if ``email_notification_by_default`` is not set to ``ON``, bv_maker will need to be invoked with the ``--email`` option to actually send email notification.

If ``success_email`` is not filled, notificatioon will only occur upon error.

Additionally it can also maintain a file of past ``bv_maker`` executions and the status of all steps. These tools are useful for automatic build and testing, continuous integration etc.

 executions and the status of all steps. These tools are useful for automatic build and testing, continuous integration etc.

This is setup in the :doc:`configuration` option ``global_status_file`` in the :ref:`general section <general_section>`:

See :ref:`displaying_build_status` below for how to use the log file.

:doc:`bv_maker` can connect to a `Jenkins <https://jenkins.io/>`_ server to log step results, so as to allow displaying them on a server. This is not the usual way to use Jenkins, which normally operates builds and tests from the server, but here bv_maker runs in its own (typically from a unix crontab), and connects to the Jenkins server to store jobs results (using "external jobs" in Jenkins dialect). This way, builds and tests running on a private network can still log results to a server visible from the internet.

 server to log step results, so as to allow displaying them on a server. This is not the usual way to use Jenkins, which normally operates builds and tests from the server, but here bv_maker runs in its own (typically from a unix crontab), and connects to the Jenkins server to store jobs results (using “external jobs” in Jenkins dialect). This way, builds and tests running on a private network can still log results to a server visible from the internet.

[ general ]
jenkins_build_name = brainvisa-$HOSTNAME-%(version)s-%(directory_id)s-%(project)s-%(step)s
jenkins_server_url = http://myserver.org/builds
jenkins_token = something_to_get_from_jenkins_server
jenkins_username = test_login

When ``bv_maker`` is running, each step execution status may be logged in a single file: a line is appended to it when a step finishes. This is enabled if the ``bv_maker.cfg`` file has the :ref:`global_status_file option <general_section>` in its general section:

 is running, each step execution status may be logged in a single file: a line is appended to it when a step finishes. This is enabled if the 

This file is a simple text file, containing just one line per bv_maker step execution, its status, run date, and system name. For instance:

OK          step test: /neurospin/brainvisa/build/Mandriva-2008.0-x86_64/bug_fix, started: 2017/01/25 06:05, stopped: 2017/01/25 07:31 on i2bm-mdv-64 (linux64-glibc-2.6)
OK          step test: /neurospin/brainvisa/build/Mandriva-2008.0-x86_64/latest_release, started: 2017/01/25 07:31, stopped: 2017/01/25 07:58 on i2bm-mdv-64 (linux64-glibc-2.6)
OK          step test: /neurospin/brainvisa/build/Mandriva-2008.0-x86_64/trunk, started: 2017/01/25 07:58, stopped: 2017/01/25 09:21 on i2bm-mdv-64 (linux64-glibc-2.6)
FAILED      step pack: /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/packages, started: 2017/01/25 09:21, stopped: 2017/01/25 10:21 on i2bm-mdv-64 (linux64-glibc-2.6)
UNMET DEP   step install_pack: /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/packages on i2bm-mdv-64 (linux64-glibc-2.6)
UNMET DEP   step test_pack: /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/packages on i2bm-mdv-64 (linux64-glibc-2.6)
OK          step pack: /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/data-%(os)s/packages, started: 2017/01/25 10:21, stopped: 2017/01/25 10:34 on i2bm-mdv-64 (linux64-glibc-2.6)
OK          step test: /mnt/neurospin/sel-poivre/brainvisa/build/CentOS-5.11-x86_64/latest_release, started: 2017/01/25 07:13, stopped: 2017/01/25 07:42 on michael (linux64-glibc-2.5)
OK          step test: /mnt/neurospin/sel-poivre/brainvisa/build/CentOS-5.11-x86_64/bug_fix, started: 2017/01/25 07:42, stopped: 2017/01/25 09:15 on michael (linux64-glibc-2.5)
OK          step test: /mnt/neurospin/sel-poivre/brainvisa/build/CentOS-5.11-x86_64/trunk, started: 2017/01/25 09:15, stopped: 2017/01/25 11:07 on michael (linux64-glibc-2.5)

Tests are "just" a series of commands that are run to use the software and check if it works as expected.

Tests are “just” a series of commands that are run to use the software and check if it works as expected.

``brainvisa-cmake`` relies on `cmake <http://cmake.org>`_, and on `ctest <https://cmake.org/cmake/help/v3.0/manual/ctest.1.html>`_ for testing. Adding a new test if hence a matter of specifying it in the ``CMakeLists.txt`` file of the software project sources, using the `add_test <https://cmake.org/cmake/help/v3.0/command/add_test.html>`_ command.

 for testing. Adding a new test if hence a matter of specifying it in the 

However ``brainvisa-cmake`` offers a light wrapper for it: :ref:`brainvisa_add_test`, which handles the runtime test environment (build tree paths, or installed package testing), and also handles invoking python in a potentially cross-compilation environment.

, which handles the runtime test environment (build tree paths, or installed package testing), and also handles invoking python in a potentially cross-compilation environment.

Some projects managed by ``brainvisa-cmake`` are "pure python" and do not conrtain explicit CMake instructions in a ``CMakeLists.txt`` file. Instead, they should provide a python ``info`` module in the project (loaded generally as ``import project_name.info``). This info module may provide tests, which are a list of commands to be executed and are specified in the ``test_commands`` variable. For instance, in the `CAPSUL <http://brainvisa.info/capsul/>`_ project, we have in the sources a file:

 are “pure python” and do not conrtain explicit CMake instructions in a 

). This info module may provide tests, which are a list of commands to be executed and are specified in the 

# tests to run
test_commands = ['%s -m capsul.test.test_capsul' % sys.executable]

This ``test_commands`` variable will be interpreted by ``brainvisa-make`` to generate the appropriate ``CMakeLists.txt`` file for the project, which will integrate with ``ctest`` and ``bv_maker``.

Each test command is free to do whatever it likes, and it is a standard practice in python to use tests based on `the python unittest <https://docs.python.org/2/library/unittest.html>`_ module.

Each test command is free to do whatever it likes, and it is a standard practice in python to use tests based on 

`the python unittest <https://docs.python.org/2/library/unittest.html>`_

``bv_maker`` can run tests of installed packages (after successful ``pack`` and ``install_pack`` steps), within the ``testref_pack`` and ``test_pack`` steps. Such tests can make use of remote or virtual machines to perform tests in a "clean", controlled, test environment, different from the build machine. Actually, to be precise, the ``install_pack`` step also uses the same mechanism and can also take place on a remote or virtual machine, in the same manner as running the tests themselves.

 steps. Such tests can make use of remote or virtual machines to perform tests in a “clean”, controlled, test environment, different from the build machine. Actually, to be precise, the 

 step also uses the same mechanism and can also take place on a remote or virtual machine, in the same manner as running the tests themselves.

However tests are always triggered from the build machine, which will in turn, connect to remote or virtual test machines.

Tests configuration is part of a :ref:`package directory <package_directory>` specification of the :doc:`bv_maker.cfg configuration file <configuration>`. They are mainly controlled via the ``remote_test_host_cmd`` variable. The contents of this variable is prepended to test commands, so they can make the connection and indirection trick. For instance:

 variable. The contents of this variable is prepended to test commands, so they can make the connection and indirection trick. For instance:

[ package /home/brutus/tests/packages ]
build_directory = /home/brutus/build
installer_filename = /home/brutus/tests/brainvisa_installer
data_repos_dir = /home/brutus/tests/data/packages
test_install_dir = /home/brutus/tests/test_install
remote_test_host_cmd = ssh -t -X test_machine BRAINVISA_TEST_RUN_DATA_DIR="$BRAINVISA_TEST_RUN_DATA_DIR" BRAINVISA_TEST_REF_DATA_DIR="$BRAINVISA_TEST_REF_DATA_DIR"

Note that test data directories have to be handled manually in remote machines access: bv_maker will setup **locally** the environment variables ``BRAINVISA_TEST_RUN_DATA_DIR`` and ``$BRAINVISA_TEST_REF_DATA_DIR``, but passing them through a ssh connection or to a docker machine is the responsibility of the ``remote_test_host_cmd`` configuration.

Note that test data directories have to be handled manually in remote machines access: bv_maker will setup 

, but passing them through a ssh connection or to a docker machine is the responsibility of the 

Here, the ``ssh -t -X test_machine`` command will be prepended to tests, so that all tests will connect through ``ssh`` to the machine named ``test_machine``, and use the software installed in the directory ``/home/brutus/tests/test_install``.

 command will be prepended to tests, so that all tests will connect through 

Another example using `docker <http://docker.com>`_ would look the following:

remote_test_host_cmd = docker run --rm -u "$(id -u):$(id -g)" -e USER=$USER -e TMPDIR=/home/brutus/tmp:/home/brutus/tmp -v "$HOME":"$HOME" -e HOME="$HOME" -v /tmp/.X11-unix:/tmp/.X11-unix --net=host -e DISPLAY=$DISPLAY -e BRAINVISA_TEST_REF_DATA_DIR="$BRAINVISA_TEST_REF_DATA_DIR" -e BRAINVISA_TEST_RUN_DATA_DIR="$BRAINVISA_TEST_RUN_DATA_DIR" -v "$BRAINVISA_TEST_REF_DATA_DIR":"$BRAINVISA_TEST_REF_DATA_DIR" -v "$BRAINVISA_TEST_RUN_DATA_DIR":"$BRAINVISA_TEST_RUN_DATA_DIR" cati/brainvisa-test:ubuntu-16.04 xvfb-run --auto-servernum

Thus the appropriate docker command will be prepended to all tests.

Note that here we are running Docker using the same user as the host machine, and we export the home directory and X11 connection from the host machine, allowing to perform graphical display.

In addition here we run commands through `xvfb-run <https://en.wikipedia.org/wiki/Xvfb>`_: XVFB is a virtual X server which does not actually perform graphical display on screen. This is used to perform tests on non-graphical build and test machines. This xvfb indirection should replace the X11 redirection (``DISPLAY`` and ``/tmp/.X11-unix settings``) thus the latter should not be needed, however we prefer to keep them because it's easy then to remove the xvfb indirection and get real interactive graphical display to fix some tests when needed.

: XVFB is a virtual X server which does not actually perform graphical display on screen. This is used to perform tests on non-graphical build and test machines. This xvfb indirection should replace the X11 redirection (

) thus the latter should not be needed, however we prefer to keep them because it’s easy then to remove the xvfb indirection and get real interactive graphical display to fix some tests when needed.

Last, the docker image we are using here is: ``cati/brainvisa-test:ubuntu-16.04``. This is a docker image of an Ununtu 16.04 system. It should work as is, the image is found on `dockerhub <https://hub.docker.com/>`_ so docker should find it directly and download it if it is not already installed.

. This is a docker image of an Ununtu 16.04 system. It should work as is, the image is found on 

 so docker should find it directly and download it if it is not already installed.

This docker image is a minimal system, with minimal software installation: it contains only the libraries required to run the `Qt installer <http://doc.qt.io/qtinstallerframework/>`_ which binary installations are using, a X11 server and XVFB. Using this "smallest possible" system allows to find out missing thirdparty software dependencies in the tested software packages. The image and docker container will normally not be modified by the tests, so can be reused for later tests.

This docker image is a minimal system, with minimal software installation: it contains only the libraries required to run the 

 which binary installations are using, a X11 server and XVFB. Using this “smallest possible” system allows to find out missing thirdparty software dependencies in the tested software packages. The image and docker container will normally not be modified by the tests, so can be reused for later tests.

The above example runs tests through Docker, and assumes that docker is installed and available on the host build system. However this will not always be true, since docker itself cannot run on every system:

because it does not work on very old systems: for instance we are still performing builds on a Mandriva 2008 system, which is not compatible with Docker.

To fix this situation, we can mix the ``ssh`` and ``docker`` approaches, to make a remote machine run Docker and perform tests in it. Ex:

 approaches, to make a remote machine run Docker and perform tests in it. Ex:

remote_test_host_cmd = ssh -t -X test_machine docker run --rm -u "$(id -u):$(id -g)" -e USER=$USER -e TMPDIR=/home/brutus/tmp:/home/brutus/tmp -v "$HOME":"$HOME" -e HOME="$HOME" -v /tmp/.X11-unix:/tmp/.X11-unix --net=host -e DISPLAY=$DISPLAY -e BRAINVISA_TEST_REF_DATA_DIR="$BRAINVISA_TEST_REF_DATA_DIR" -e BRAINVISA_TEST_RUN_DATA_DIR="$BRAINVISA_TEST_RUN_DATA_DIR" -v "$BRAINVISA_TEST_REF_DATA_DIR":"$BRAINVISA_TEST_REF_DATA_DIR" -v "$BRAINVISA_TEST_RUN_DATA_DIR":"$BRAINVISA_TEST_RUN_DATA_DIR" cati/brainvisa-test:ubuntu-16.04 xvfb-run --auto-servernum

which essentially concatenates the config lines of the ssh and the docker variants.

In this ssh + docker situation, the X11 redirection does not work so easily because ssh tunnels the X11 connection and simply assigning the ``DISPLAY`` variable is not enough. There should be ways to make it work, however the xvfb option is OK.

In this ssh + docker situation, the X11 redirection does not work so easily because ssh tunnels the X11 connection and simply assigning the 

 variable is not enough. There should be ways to make it work, however the xvfb option is OK.

Here is a more complete example of a full ``bv_maker.cfg`` file from our build systems. Only the email addresses have been changed from our actual configuration (to avoid spams).

 file from our build systems. Only the email addresses have been changed from our actual configuration (to avoid spams).

[ general ]
  global_status_file = /neurospin/brainvisa/build/builds.log
  failure_email = brainvisa-build-notification@cea.fr
  smtp_server = mx.intra.cea.fr
  from_email = brainvisa-build-notification@cea.fr
  reply_to_email = brainvisa-build-notification@cea.fr

[ source /neurospin/brainvisa/sources ]
  build_condition = gethostname() == 'is220756'
  + all trunk
  + all bug_fix
  + all tag
  + catidb trunk
  + catidb bug_fix
  - ptk:* trunk
  + brainvisa/development/build-config/trunk development/build-config/trunk
  - qualicati trunk
  + brainvisa/casa casa

[ build /neurospin/brainvisa/build/$I2BM_OSID/bug_fix ]
  default_steps = configure build doc test
  clean_config = ON
  clean_build = ON
  all bug_fix /neurospin/brainvisa/sources
  - nuclear_processing:*
  - longitudinal_pipelines
  - sandbox
  - famis
  - ptk:*
  - axon_web

# data packages and repository (no installer)
[ package /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/data-%(os)s/packages ]
  build_directory = /neurospin/brainvisa/build/$I2BM_OSID/bug_fix
  packaging_options = --data --repository-only
  init_components_from_build_dir = OFF
  build_condition = (gethostname() != 'michael') or os.environ.get('BRAINVISA_FORCE_PACKAGING', 'OFF') == 'ON'
  default_steps = pack
  brainvisa-share bug_fix /neurospin/brainvisa/sources
  sulci-models bug_fix /neurospin/brainvisa/sources

# software packages and repository (with installer and testing)
[ package /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/packages ]
  packaging_options = --online-only
  installer_filename = /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/brainvisa-installer/brainvisa_installer-%(version)s-%(os)s-%(online)s
  data_repos_dir = /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/data-%(os)s/packages
  test_install_dir = /neurospin/tmp/brainvisa/tests/repositories/public/%(version)s-%(date)s/%(os)s/test_install
  # build every 5 days, and not on michael (Qt installer is not installed on michael)
#  build_condition = gethostname() != 'michael' and (time.localtime()[2] % 5 == 1 or os.environ.get('BRAINVISA_FORCE_PACKAGING', 'OFF') == 'ON')
  build_condition = gethostname() != 'michael'
  default_steps = pack install_pack test_pack
  [ if gethostname() in ('is208611.intra.cea.fr', 'is220756') ]
    # tests need fixing
    default_steps = pack install_pack
  [ endif ]
  [ if gethostname() == 'i2bm-fdr4-32' ]
    # needs fixing
  [ endif ]
    # run in docker, on same host
    remote_test_host_cmd = docker run --rm -v /neurospin/brainvisa:/neurospin/brainvisa -v /neurospin/tmp/brainvisa:/neurospin/tmp/brainvisa -u "$(id -u):$(id -g)" -e USER=$USER -v /volatile/a-sac-ns-brainvisa:/volatile/a-sac-ns-brainvisa -e TMPDIR=/volatile/a-sac-ns-brainvisa/tmp -v "$HOME":"$HOME" -e HOME="$HOME" -v /tmp/.X11-unix:/tmp/.X11-unix --net=host -e DISPLAY=$DISPLAY -e BRAINVISA_TESTS_DIR="$BRAINVISA_TESTS_DIR" -e BRAINVISA_TEST_REF_DATA_DIR="$BRAINVISA_TEST_REF_DATA_DIR" -e BRAINVISA_TEST_RUN_DATA_DIR="$BRAINVISA_TEST_RUN_DATA_DIR" -e QT_X11_NO_MITSHM=1 --privileged cati/brainvisa-test:ubuntu-16.04 xvfb-run --auto-servernum
  [ endif ]
  [ if gethostname() in ('i2bm-mdv-64', 'michael', 'i2bm-ub1204') ]
    # run in docker, through a ssh connection to is220756,
    # reference for tests: ubuntu 14 (host machine)
    remote_test_host_cmd = ssh -t -X is220756 docker run --rm -v /neurospin/brainvisa:/neurospin/brainvisa -v /neurospin/tmp/brainvisa:/neurospin/tmp/brainvisa -u "$(id -u):$(id -g)" -e USER=$USER -v /volatile/a-sac-ns-brainvisa:/volatile/a-sac-ns-brainvisa -e TMPDIR=/volatile/a-sac-ns-brainvisa/tmp -v "$HOME":"$HOME" -e HOME="$HOME" -v /tmp/.X11-unix:/tmp/.X11-unix -e BRAINVISA_TESTS_DIR="$BRAINVISA_TESTS_DIR"-test_pack -e BRAINVISA_TEST_REF_DATA_DIR="$BRAINVISA_TEST_REF_DATA_DIR" -e BRAINVISA_TEST_RUN_DATA_DIR="$BRAINVISA_TEST_RUN_DATA_DIR" --net=host -e DISPLAY=$DISPLAY -e QT_X11_NO_MITSHM=1 --privileged cati/brainvisa-test:ubuntu-16.04 xvfb-run --auto-servernum
  [ endif ]
  # remaining hosts (i2bm-fdr4-32) insall/test on themselves
  [ if gethostname() == 'is144451' ]
    # run via ssh on the other Mac: wake the VM and ssh to the VM inside the mac
  #  remote_test_host_cmd = ssh -t is229812 /i2bm/brainvisa/wake_vm && ssh -t -X macvm BRAINVISA_TESTS_DIR="$BRAINVISA_TESTS_DIR"-test_pack
  remote_test_host_cmd = ssh -t -X is229812 BRAINVISA_TESTS_DIR="$BRAINVISA_TESTS_DIR"-test_pack BRAINVISA_TEST_RUN_DATA_DIR="$BRAINVISA_TEST_RUN_DATA_DIR" BRAINVISA_TEST_REF_DATA_DIR="$BRAINVISA_TEST_REF_DATA_DIR"
  - preclinical_imaging_iam
  [ endif ]
  test_ref_data_dir = /neurospin/brainvisa/tests/$I2BM_OSID/ref/bug_fix-test-pack
  test_run_data_dir = /neurospin/brainvisa/tests/$I2BM_OSID/test/bug_fix-test-pack
  - sulci-data
  - brainvisa-share
  - brain_segmentation_comparison-private
  - brain_segmentation_comparison-gpl
  - highres-cortex