		      ___________________________

		       BART CMAKE BUILDING GUIDE
		      ___________________________


Table of Contents
_________________

1 Overview
2 Building BART
.. 2.1 Quick building guide
..... 2.1.1 Download and install LAPACKE locally
..... 2.1.2 Building of BART
.. 2.2 Main Build Targets
..... 2.2.1 Default
..... 2.2.2 Testing
..... 2.2.3 Install
..... 2.2.4 Packaging
..... 2.2.5 Cleaning up
.. 2.3 Non-standard locations (libraries, Python, etc.)
3 Build options
.. 3.1 Adding new BART commands
.. 3.2 Compiler
..... 3.2.1 Different compiler
..... 3.2.2 Different compiler flags
.. 3.3 Optional Features





1 Overview
==========

  In addition to the GNU Make build system, BART can also be built using
  CMake which can offer more flexibility and portability when compiling
  on different architectures or platforms.

  Additionally, if you plan on integrating BART into other projects, the
  CMake build provide you with portable ways of installing and exporting
  BART which then allow you to easily add it as a dependency of your own
  project. If your other project is also based on CMake, adding BART as
  a dependency is as simple as writing `find_package(BART)' since all
  the dependencies are automatically taken care of.

  One key difference between the GNU Make and the CMake builds of BART
  is that the latter does not allow you to compile BART commands as
  separate executables. The BART executable is otherwise identical to
  the one generated by GNU Makefiles.


2 Building BART
===============

  At the very minimum, BART depends on a LAPACK/BLAS installation with
  C-bindings (CBLAS). Additionally, BART may profit from an optimized
  installation of LAPACKE (C interface to LAPACK), although you can
  specify an option to use an internal implementation of the necessary
  routines.

  Upon running for the first time, CMake will attempt to automatically
  find a compatible LAPACK/BLAS installation on your system. It will
  specifically look for:
  BLAS
        Only valid if the option `BART_NO_LAPACKE' is set. Will attempt
        to find valid `lapack', `cblas', and `blas' libraries.
  AMD_FLAME
        AMD's libFlame library
  OpenBLAS
        An optimized BLAS library
  ATLAS
        Automatically Tuned Linear Algebra Software
  LAPACKE
        C Interface to LAPACK (with cblas)

  If you have a particular vendor that you would like BART to link
  against, simply define the `LINALG_VENDOR' CMake variable with one of
  the above mentioned names (e.g. `cmake -DLINALG_VENDOR="ATLAS" ..').


2.1 Quick building guide
~~~~~~~~~~~~~~~~~~~~~~~~

  BART depends upon the new lapacke.h and cblas.h interfaces for blas
  and lapack. These new 'C' interfaces are often not packaged robustly
  on many different platforms. Important fixes to lapack distribution
  occured at lapack-3.6.0 and for finding lapack libs robustly with the
  github patch version 7fb63b1cd386b099d7da6eeaafc3e7dce055a7d0.

  List of issues when using default lapack from distributions:
  1) Homebrew provides `lapacke.h', but not `cblas.h'
  2) SUSE provides cblas.h from ATLAS, but `lapacke.h' from lapack
     distro
  3) RHEL6 does not provide `lapacke.h' or `cblas.h'
  4) RHEL7 does not provide `lapacke.h' or `cblas.h'

  Additionally, several 'Vendor' optimized versions provide enhanced
  lapack and blas intefaces with various levels of support for
  `lapacke.h' and `cblas.h'.

  Therefore for this short building guide, we suggest you download and
  compile the latest LAPACKE library and link BART against it. From
  inside the BART root directory issue the following command:
  ,----
  | export ROOT_DIR=$PWD
  `----


2.1.1 Download and install LAPACKE locally
------------------------------------------

  Clone the LAPACK Git repository within the src/ folder of the BART
  root directory:
  ,----
  | git clone https://github.com/Reference-LAPACK/lapack.git ${ROOT_DIR}/src/lapack
  | cd ${ROOT_DIR}/src/lapack
  | mkdir -p build
  | cd build
  | CC=gcc CXX=g++ FC=gfortran cmake -DCBLAS=ON -DLAPACKE=ON -DCMAKE_INSTALL_PREFIX=${ROOT_DIR}/lapack-install ..
  | make -j4
  | make install
  `----


2.1.2 Building of BART
----------------------

  Now simply run CMake with the following variables:
  - `LINALG_VENDOR=LAPACKE'
  - `LAPACKE_ROOT=${ROOT_DIR}/lapack-install'

  For example, on UNIX from within the BART root directory:
  ,----
  | mkdir -p ${ROOT_DIR}/bart-LAPACKE-bld
  | cd ${ROOT_DIR}/bart-LAPACKE-bld
  | rm -rf *;
  | CC=gcc CXX=g++ cmake -DCMAKE_Fortran_COMPILER=${FC} -DLINALG_VENDOR=LAPACKE -DLAPACKE_DIR=${ROOT_DIR}/lapack-install ..
  | make -j8
  `----


2.2 Main Build Targets
~~~~~~~~~~~~~~~~~~~~~~

2.2.1 Default
-------------

  By default, the main BART executable, as well as the BARTmain library
  are built when no specific target are required (e.g. when issuing
  `make' on UNIX systems). Individual components may be built by
  choosing on of the following targets:
  bart
        Main BART executable
  bartmain
        BARTmain library with identical functionality as the main
        executable, but intended for embedding
  bartsupport
        BART library of support functions
  pyBART
        If enabled, will build the pyBART Python module


2.2.2 Testing
-------------

  The CMake build provides multiple targets for testing purposes:
  test
        Run all unit tests (NB: the `BUILD_TESTING' option must be
        turned `ON' and all targets must be built)
  integration
        Run all integration tests
  integration_XXX
        Run only the `XXX' tests (where `XXX' is for e.g. `cc', `fft',
        `pics', etc.)


2.2.3 Install
-------------

  The CMake build provides two installation targets:
  install
        Install everything that was built
  install_for_embedding
        Only install the BARTmain library and its related targets
  uninstall
        Remove all files installed during the last installation run


2.2.4 Packaging
---------------

  CPack is configured to produce self-installing archives on most
  platforms. These can be created by building the following target:
  package
        Create packaged archives of BART (platform dependent)


2.2.5 Cleaning up
-----------------

  To clean up the building directory, simply build the `clean' target
  (e.g. issuing `make clean' on UNIX)


2.3 Non-standard locations (libraries, Python, etc.)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  If you have some of your libraries installed in some non-standard
  locations (e.g. on UNIX outside of `/usr' or `/usr/local'), you can
  ask CMake to look for the requested libraries in other locations by
  defining either some environment variables or some CMake variables.

  Here is an exhaustive list of variables that may influence the
  building of BART:

   Variable name           Type        Description                    
  --------------------------------------------------------------------
   CMAKE_PREFIX_PATH       env./CMake  Define good defaults for       
                                       searching for packages         
                                                                    
   ATLAS_ROOT              env./CMake  Preferred installation prefix  
   ATLAS_DIR                           for the ATLAS libraries        
                                                                    
   CUDA_ROOT               env./CMake  Preferred installation prefix  
   CUDA_TOOLKIT_ROOT_DIR               for the CUDA toolkit and       
                                       libraries                      
                                                                    
   FFTW_ROOT               env./CMake  Preferred installation prefix  
   FFTW_DIR                            for the FFTW libraries         
                                                                    
   LAPACKE_ROOT            env./CMake  Preferred installation prefix  
   LAPACKE_DIR                         for the LAPACKE libraries      
                                                                    
   libFlame_ROOT           env./CMake  Preferred installation prefix  
   libFlame_DIR                        for the AMD libFlame libraries 
                                                                    
   OpenBLAS_ROOT           env./CMake  Preferred installation prefix  
   OpenBLAS_DIR                        for the OpenBLAS libraries     
                                                                    
   Python_ROOT_DIR         env./CMake  Define the root directory of a 
                                       Python installation.           
                                                                    
   Python_USE_STATIC_LIBS  CMake only  If not defined, search for     
                                       shared libraries and static    
                                       libraries in that order.       
                                       If set to TRUE, search *only*  
                                       for static libraries.          
                                       If set to FALSE, search *only* 
                                       for shared libraries.          
                                                                    
   PYBART_NUMPY_ROOT       env./CMake  Define directory containing    
   PYBART_NUMPY_DIR                    NumPy's arrayobject.h          

  These variables would typicaly be used either as environment
  variables:
  ,----
  | OpenBLAS_ROOT=/home/user/my_openblas Python_ROOT_DIR=/opt/anaconda/ cmake ..
  `----
  or directly as CMake variables:
  ,----
  | cmake .. -DOpenBLAS_ROOT=/home/user/my_openblas -DPython_ROOT_DIR=/opt/anaconda/ 
  `----


3 Build options
===============

  The CMake build can be configured by using a number of options
  provided in the main CMakeLists.txt file or by specifying them
  directly on the command line.


3.1 Adding new BART commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  In order to register a new BART command, you need to copy the file
  containing its main function to `src' folder. Then either add its name
  somewhere inside the `build_targets.mk' file or define the
  `BART_EXTRA_PROGS' CMake variable with the name of your command. You
  then need to re-run the CMake configure step in order for the build
  system to properly register the new source file.


3.2 Compiler
~~~~~~~~~~~~

3.2.1 Different compiler
------------------------

  In order to specify a different compiler, either specify the
  controller you want on the command line when executing CMake:
  ,----
  | CC=clang CXX=clang++ cmake [...]
  `----
  or change the `CMAKE_C_COMPILER' and `CMAKE_CXX_COMPILER' variables in
  the CMake cache.


3.2.2 Different compiler flags
------------------------------

  Compiler flags can be modified by modifying the `CMAKE_C_FLAGS' and
  `CMAKE_CXX_FLAGS' CMake variables, either from the command line when
  running CMake
  ,----
  | cmake -DCMAKE_C_FLAGS=-Wall -DCMAKE_CXX_FLAGS=-Wall [...]
  `----
  or by modifying their values in the CMake cache.


3.3 Optional Features
~~~~~~~~~~~~~~~~~~~~~

  Some BART features are optional, either because they depend on
  libraries or features not available everywhere. All of them are
  controlled by CMake options that can be turned on or off:

  BART_CREATE_PYTHON_MODULE     
        Turn on/off building of the `pyBART' Python module

  BART_DISABLE_PNG              
        If `ON', disables building of the `toimg' BART command

  BART_ENABLE_MEM_CFL           
        Turn on/off supports for in-memory CFL files

  BART_FFTWTHREADS              
        Turn on/off support for threaded FFTW libraries

  BART_FPIC                     
        Turn on/off compilation using position independent code for all
        targets

  BART_GENERATE_DOC             
        Turn on/off automatic generation of the documentation after
        building succeeds

  BART_ISMRMRD                  
        Turn on/off support for the ISMRM raw data format and its
        related command (`ismrmrd')

  BART_LOG_BACKEND              
        Turn on/off support for external backends in the BARTmain
        library. Mainly intended for embedding purposes (e.g. with
        Gadgetron)

        BART_LOG_GADGETRON_BACKEND  
              Turn on/off the Gadgetron logging backend (only displayed
              if BART_LOG_BACKEND is `ON')
        BART_LOG_ORCHESTRA_BACKEND  
              Turn on/off the GE Orchestra logging backend (only
              displayed if BART_LOG_BACKEND is `ON')
        BART_LOG_SIEMENS_BACKEND    
              Turn on/off the Siemens UTrace logging backend (only
              displayed if BART_LOG_BACKEND is `ON')

  BART_MATLAB                   
        Turn on/off building MATLAB-related tools (`mat2cfl')

  BART_MEMONLY_CFL              
        Turn on/off enabling only in-memory CFL files. Note if `ON',
        BART will not be able to write files to the disk.

  BART_NO_LAPACKE               
        If `ON', BART will use its internal implementation of the
        LAPACKE functions instead of relying on the ones installed on
        your system

  BART_REDEFINE_PRINTF_FOR_TRACE
        If `ON', `debug_print*' functions are re-defined as macros and
        that will forward their calls to their `debug_print*_trace'
        counterparts, thus providing more context information for error
        messages. Particularly useful in combination with external
        logging backends.

  BART_STATIC_ANALYSIS
        Turn on/off static analysis while building BART

        BART_SA_CLANG_TIDY
              Turn on/off running `clang-tidy' when compiling each file

        BART_SA_CPPCHECK
              Turn on/off running `cppcheck' during each compilation
              step

        BART_SA_IWYU
              Turn on/off running `include-what-you-use' for each file
              being compiled

  BUILD_TESTING                 
        Turn on/off building of unit test programs

  USE_CUDA                      
        Turn on/off support for CUDA (`OFF' by default). Detection of
        the location of the CUDA installation should work without
        modifications for standard installation prefixes. In the case
        where this automatic fails, you can set the
        `CUDA_TOOLKIT_ROOT_DIR' variable to the root directory of your
        CUDA installation (e.g. `/usr/local/cuda-9.2').

  USE_CUDA_NATIVE               
        This option is only shown if the `USE_CUDA' option is set. Turn
        on/off native CUDA support from CMake. Starting from CMake 3.8,
        support for CUDA as a separate language similar to C or C++ is
        possible. However, when integrating BART as a library in other
        projects it might be necessary to revert to the old behaviour of
        using the `FindCUDA' module.

  USE_OPENMP                    
        Support for OpenMP (`ON' by default), can be disabled by simply
        turning off this option.
