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:
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?
Q: How do I increase the verbosity of cmake?
cmake --debug-output ..
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
(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?
to create the class library HTML documentation.
to generate either the task or tool documentation in HTML or PDF formats, respectively. The target
does all of the above.
In order to build the documentation of a single tool, do (for example for the measures tool)
In order to build the documentation of a single task, do (for example for the plotms task)
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
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.
.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?
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
(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
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.
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)
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
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
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
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
Q: I want to skip the detection of some package, how?
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.
The "make" command may fail if you have outdated, generated header files lying around in the source directory, such as
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.)