THIS PAGE IS DEPRECATED! See CASA build notes

CASA build instructions

on the supported platforms

on a non-supported platform, with required dependency packages

Some creativity may be needed when you install dependency packages. CASA has been seen to compile and run on the following non-supported platforms:

on a non-supported platform, without required dependency packages

CASA is very easy to build. One basically needs to do the following:

FAQ:

Basic usage

Q: How do I use CMake to build CASA?

Most of what most developers will ever need to know is

<literal>mkdir code/build<br></br>cd code/build<br></br>cmake ..<br></br>make</literal>

(You can substitute "make" with "gmake" if you like, and use make's -j option to speed up your builds on multiprocessor systems.

The name of the build directory is purely conventional. If you do not like to clutter up your source code with build products, go ahead and create your build directory somewhere else.)

Q: How do I increase the verbosity of make?

Run

make VERBOSE=on 

Q: How do I increase the verbosity of cmake?

Run

cmake --debug-output ..

or even

cmake --trace ..

Q: How does CMake work?
CMake generates makefiles from the CMakeLists.txt files. CMake first checks that your system is correctly setup: that dependency libraries exist in the correct versions, that they compile etc. If everything is okay, makefiles are generated, which are then processed by make. The philosophy is that after the initial configuration step has passed, the build itself should complete without errors.

Q: When should I run make, and when cmake? If I choose the wrong option, will I get in trouble?

No, nothing can go wrong in this respect. If cmake needs to be run (i.e. if there was a change to a CMakeLists.txt file), then make will automatically trigger a cmake rerun. Just run make.

Q: How do I run the unit tests?

The python unit test suite is run with

casapy -c code/xmlcasa/scripts/regressions/admin/runUnitTest.py

A single python unit test suite is run with (for example)

casapy -c code/xmlcasa/scripts/regressions/admin/runUnitTest.py test_clean

The full C++ test suite is built and executed with

make check

(refer to 'man ctest' for further information). A single C++ unit test is executed with (for example)

make tVisSet && msvis/tVisSet


Q: How do I build the documentation?

Use

make doc_doxy

to create the class library HTML documentation.
Use
make taskref_html
make taskref_pdf
make casaref_html
make casaref_pdf

to generate either the task or tool documentation in HTML or PDF formats, respectively. The target
make doc

does all of the above.

In order to build the documentation of a single tool, do (for example for the measures tool)

make measures_tool_latex
make measures_tool_html
make measures_tool_pdf

In order to build the documentation of a single task, do (for example for the plotms task)

make plotms_task_latex
make plotms_task_html
make plotms_task_pdf

Q: It was necessary for me to "make clean" in order to force things to get rebuilt correctly. Wtf?
You should not be using the clean target on a regular basis. The build system should know when to rebuild what. Please submit a bug report.

In the exceptional case you where you really want to run "make clean" anyway, you can target the cleaning operation to a single module like this

cd code/build/flagging/
make clean

or you can remove individual files manually, for example
rm -rf code/build/flagging/

Q: I added a source file but it is ignored by the build system?
You need to edit the nearest CMakeLists.txt correspondingly, if you add or remove source files.

Q: I needed to make a local modification to a CMakeLists.txt file in order to do XYZ.

The CMakeLists.txt should be changed only when there are changes to the build procedure, not as a way to configure your local environment. These are not makedefs files. If you find that XYZ is actually a reasonable thing to do, then please submit a bug report or a change request.

Q: How do I rebuild just a single subdirectory?
Do

cd build
make synthesis

which will (re)build (for example) the synthesis library, and any other executables in the synthesis directory.

Q: Ok, but when I run "make synthesis", it is goes through my entire code tree and checks that all other modules which synthesis depends on, are also up to date. I have not changed any other modules. I don't want to wait for that.

If you want to skip dependency checking of synthesis' dependencies, do

make synthesis_fast

(that is "synthesis_fast", not "synthesis/fast"). This is at your own risk, of course; if there was a change and any of the dependent targets were not really up to date, you may get an inconsistent build.

Q: How do I create a debug build?

Use cmake -DCMAKE_BUILD_TYPE=Debug .. .

You can create several builds from the same source tree, by putting each build in a separate build directory. Example

cd code/build
cmake .. 
cd ../code/build_debug
cmake -DCMAKE_BUILD_TYPE=Debug ..

Note however that the final location of the binary executables and libraries, the installation directory, is fixed to code/../linux_gnu/ (on 32 bit Linux) and this installation directory is shared between the different builds.

CASACore

Q: After changing CASACore, how do I ensure that everything gets properly rebuilt?
1. Rebuild CASACore (using the instructions given elsewhere; the cmake build system for CASA does not cover CASACore)

2.

cd code/build
make

The build system in code/ treats CASACore just like any other external package. It keeps track of dependencies to header/template/library files exported from CASACore (like any other package).


Q: I made a parallel change to CASACore and code, what should I do?

If the change is backwards-incompatible, that is if the changed code/ tree will no longer work with the unchanged CASACore (for example if you add a function to CASACore and use it from code/), then you must increment the version number of CASACore:

1. Edit casacore/casa/version.h and increment the version number defined by "CASACORE_VERSION" from, say 0.3.87 to 0.3.88.

2. Change in parallel code/CMakeLists.txt to require this new version of CASACore: "casa_find( CASACORE VERSION 0.3.88 ... )"

This has the effect that if someone else updates code/ without updating casacore/ (or in any other way attempts to use an inappropriate version of CASACore), a cmake configuration error will happen ("Your CASACore is too old, please update!"), as opposed to compile errors.

cmake for casacore

Much of this should eventually be moved to the step-by-step instructions...

cmake for casacore is new, but I already prefer it to scons, mainly because of the progress meter and ctest.

export CASAROOT=/directory/which/casacore/is/in MY_ARCH=linux_64b # linux_gnu for 32 bits. export CASAARCH=$CASAROOT/$MY_ARCH UL=/usr/lib64 # /usr/lib for 32 bits. cd $CASAROOT

# Another advantage is building outside the code tree. You might want to go back and rm -rf build_linux_i386 inside $CASAROOT/casacore. mkdir -p build_core/opt # or debug cd build_core/opt

# EXAMPLES ONLY! Choose and/or adapt one...not all of these options are necessary for everybody. # RHEL5 (Tikanga) cmake -DCMAKE_INSTALL_PREFIX=$CASAARCH -DUSE_FFTW3=ON -DCBLAS_ROOT_DIR=/usr -DCLAPACK_ROOT_DIR=/usr --DLAPACK_LIBRARIES=$UL/liblapack.so DCFITSIO_ROOT_DIR=/usr -DCFITSIO_INCLUDE_DIR=/usr/include/cfitsio -Darch=$MY_ARCH -DWCSLIB_ROOT_DIR=/usr -DFFTW3_ROOT_DIR=/usr -DDATA_DIR=$UL/casapy/data ../../core

# 64b Ubuntu 10.10 cmake -DCMAKE_INSTALL_PREFIX=$CASAARCH -DCBLAS_ROOT_DIR=/usr -DCLAPACK_ROOT_DIR=/usr -DCFITSIO_ROOT_DIR=/usr -DHDF5_ROOT_DIR=/opt -DFFTW3_ROOT_DIR=/usr -DDATA_DIR=$CASAROOT/data -DCMAKE_CPP_FLAGS="-O3 -g -DCASA_USECASAPATH -DCASACORE_NEEDS_RETHROW -DAIPS64_B" ../../core

# If the above was successful... make -j 940854 # Or fewer if you must.

# Don't forget...it's not exactly like cmake for casapy. make install

Adding a unit test or demo

Add the .cc filename at the appropriate place in the CMakeLists.txt file in the same directory (e.g. tables/Tables/test).

Running unit tests

See the "Executing tests" blurb near the bottom of the above googlecode page.

CMake customization

Q: CMake's automatic detection did not find package XYZ. Or I have several versions of package XYZ installed on my system and CMake picked up the wrong one, help!

On supported development platforms, the build system should pick up the right dependency packages. But if you want to customize the locations of dependency packages, you can set the definitions manually. There are several ways to edit the CMake variables:

  • From the command line: cmake -DCFITSIO_INCLUDE_DIRS="/usr/local/include/cfitsio;/usr/include" -DCFITSIO_LIBRARIES=/usr/lib/libcfitsio.so
  • Interactive mode: cmake -i ..
  • A curses GUI: ccmake ..
  • Put your definitions in a configuration file (called, for example, makedefs) and point cmake to it:
    cmake -C ./makedefs ..
    See "man cmake" for more.

Notice: If you specify a custom location, for example

cmake -DQWT_INCLUDE_DIRS=/usr/local/qwt-5.3/include ..

the build system will not trust you blindly but will verify that the required headers really exist at that custom location. If you want to disable this check, do

cmake -DQWT_INCLUDE_DIRS=/usr/local/qwt-5.3/include -DQWT_FOUND=TRUE .. 

A special case is Python, where you can specify your requested python version using

cmake -DPYTHON_LIBNAME=2.6 ..

(in order to pickup Python 2.6.x on a system with multiple pythons installed.)

Some CMake variables that determine package configuration are
ATM_FOUND
ATM_INCLUDE_DIRS
ATM_LIBRARIES

BLAS_FOUND
BLAS_LIBRARIES

Boost_FOUND
BOOST_ROOT

CASACORE_FOUND
CASACORE_INCLUDE_DIRS
CASACORE_LIBRARIES

CCMTOOLS_ccmtools_EXECUTABLE
CCMTOOLS_FOUND
CCMTOOLS_INCLUDE_DIRS
CCMTOOLS_LIBRARIES

CFITSIO_FOUND
CFITSIO_INCLUDE_DIRS
CFITSIO_LIBRARIES

DBUS_dbusxx-xml2cpp_EXECUTABLE
DBUS_FOUND
DBUS_INCLUDE_DIRS
DBUS_LIBRARIES

Java_FOUND
Java_java_EXECUTABLE

LAPACK_FOUND
LAPACK_LIBRARIES

LIBXML2_FOUND
LIBXML2_INCLUDE_DIRS
LIBXML2_LIBRARIES

PGPLOT_FOUND
PGPLOT_INCLUDE_DIRS
PGPLOT_LIBRARIES

PYTHON_LIBNAME
PYTHON_FOUND
PYTHON_INCLUDE_DIRS
PYTHON_LIBRARIES

QT4_FOUND
QT4_INCLUDE_DIRS
QT4_LIBRARIES

QWT_FOUND
QWT_INCLUDE_DIRS
QWT_LIBRARIES

READLINE_FOUND
READLINE_INCLUDE_DIRS
READLINE_LIBRARIES

RPFITS_FOUND
RPFITS_INCLUDE_DIRS
RPFITS_LIBRARIES

WCSLIB_FOUND
WCSLIB_INCLUDE_DIRS
WCSLIB_LIBRARIES

XERCES_FOUND
XERCES_INCLUDE_DIRS
XERCES_LIBRARIES

Q: How do I force a re-run of CMake's detection of dependency packages?
After CMake has initially detected external packages, it keeps a cache of the derived definitions (include paths, library names etc.). In order to reset CMake's cache, do

rm code/build/CMakeCache.txt

Q: I want CMake to re-detect just a single package

In order to repeat the detection of e.g. Python, do

cmake -U PYTHON* ..

Warning: Any other external packages that depend on Python will not get redetected and their definitions may still refer to the previous Python detection. The safe thing to do is

rm CMakeCache.txt

cmake ..

Q: I want to skip the detection of some package, how?

Run

cmake -DCCMTOOLS_FOUND=True ..

and CMake will mistakingly think that CCMTOOLS was already found, and not search for it (again).

This could be useful if you are interested in building just the part of the source code, which is independent of CCMTOOLS, and you do not want to install CCMTOOLS just in order to satisfy CMake's configuration.

Q: How do I set compiler flags?

If you want to add a compiler flag, do

cmake -DEXTRA_CXX_FLAGS="-DMY_FLAG" ..

If you want to redefine all flags, use
cmake -DCMAKE_CXX_FLAGS="-Wall -Wno-non-template-friend -DMY_FLAG" ..

Q: How do I skip CMake's checking of dependency package version numbers?

Run "cmake -DCASA_IGNORE_VERSION=True .."

but be warned that 1) version checking is disabled for all external packages, and 2) strange compile, link and runtime issues may occur when using unsupported versions of dependency packages.

Q: I used cmake's -G option to generate Eclipse project files, and now I have an issue with XYZ. Help!

You're on your own. The only supported CMake generator is Unix Makefiles. Parts of the dependency generation in xmlcasa is known to work only with Unix Makefiles.

Known issues

The "make" command may fail if you have outdated, generated header files lying around in the source directory, such as

code/casadbus/implement/viewer/ViewerProxy.dbusproxy.h

You must remove such files. They can be identified with
svn status --no-ignore /path/to/your/source/code/ | egrep "^(I|\?).*\.h$"

Or just do a clean svn checkout. (All build products from the cmake build system go to the build/ directory.)

-- JonasLarsen - 2010-02-17
Topic revision: r66 - 2015-01-30, KumarGolap
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback