INSTALL

LOFAR (LOw Frequency ARray) Software Repository - INSTALL
=========================================================

Installation instructions for LOFAR software.


Supported Systems
-----------------

- Linux      (most in use at ASTRON are Ubuntu, CentOS, and SUSE Linux Enterprise)
- Mac OS X   (reasonably recent should work, also with LLVM/Clang)


Install from Ubuntu Packages
----------------------------

To install LOFAR Offline processing tools the easy way for a specific Ubuntu version, see:

	https://launchpad.net/~radio-astro/+archive/ubuntu/main


Install using Docker Scripts
----------------------------

To create a Docker container with Ubuntu or CentOS and LOFAR Offline processing tools, see:

	https://github.com/lofar-astron/lofar-deploy


Dependencies for Manual Build from Source
-----------------------------------------

Please first try to install as many dependencies as possible using your OS
package manager. For almost all cases, you also need the development packages
('pkgname-dev' for Debian/Ubuntu, or 'pkgname-devel' for CentOS/Fedora).

For Debian/Ubuntu (likely incomplete list, but goes a long way):

	apt-get install subversion cmake make g++ gfortran python-dev python-numpy
	apt-get install libboost-dev libblitz0-dev libfftw3-dev libcfitsio3-dev libxml2-dev liblog4cplus-dev
	apt-get install libpng12-dev                         # or latest version; for AOFlagger
	apt-get install libreadline-dev libpqxx-dev doxygen  # optional
	apt-get install libgsl0-dev                          # optional, for AOFlagger's RayleighFitter
	apt-get install libgtkmm-[2.4|3.0]-dev libsigc++-2.0-dev  # optional, for AOFlagger's rficonsole
	apt-get install libunittest++-dev                    # optional, for tests that use UnitTest++


For CentOS/Fedora (likely incomplete list, but goes a long way):

	yum install subversion cmake make gcc python-devel numpy
	yum install boost-devel fftw-devel cfitsio-devel libxml2-devel libpng-devel

	yum install readline-devel libpqxx-devel doxygen     # optional
	yum install gsl-devel                                # optional, for AOFlagger's RayleighFitter
	yum install gtkmm[24|30]-devel libsigc++20-devel     # optional, for AOFlagger's rficonsole

	The blitz and blitz-devel pkgs are available on some distros, but not on e.g. CentOS 7.
	If required for your build, but not in your repo, take the two RPMs from CentOS 6 (or build from source).
	Idem for log4cplus (LOFAR log4cxx support is dodgy).
	Similar for unittest++ and unitest++-devel (both optional), but take two RPMs from Fedora 22 (or build from source).
	RPMs known to work on CentOS 7 can be found at: https://support.astron.nl/lofar_issuetracker/issues/8161



NOTE (any OS): For manual builds, the most prominent dependency you likely need to build is casacore (+ friends):

	casacore:                  https://github.com/casacore/casacore
	python-casacore ('pyrap'): https://github.com/casacore/python-casacore
	IERS/measures tables:      https://github.com/casacore/casacore-data-update
	casarest:                  https://svn.astron.nl/casarest

	AOFlagger:                 http://sourceforge.net/projects/aoflagger/


Instructions for Manual Build from Source
-----------------------------------------

- SVN checkout build and configuration scripts of a tagged release x.y.z (or the
  trunk) from https://svn.astron.nl/LOFAR/ into e.g. $HOME/src/LOFAR-x.y.z/

	LOFAR_RELEASE=LOFAR-Release-x.y.z  # set to used release version
	svn checkout --depth=files "https://svn.astron.nl/LOFAR/tags/$LOFAR_RELEASE" "$HOME/src/$LOFAR_RELEASE"
	svn update --depth=infinity "$HOME/src/$LOFAR_RELEASE/CMake"

- Auto-checkout and install the usual offline data reduction (imaging) packages
  into e.g. $HOME/local/$LOFAR_RELEASE/
  (Only ends succesfully once CMake can find all required dependencies.)

	mkdir -p $HOME/build/$LOFAR_RELEASE/gnu_opt  # last directory must be {gnu|clang}_{debug|opt}
	cd $HOME/build/$LOFAR_RELEASE/gnu_opt
	cmake -DCMAKE_INSTALL_PREFIX="$HOME/local/$LOFAR_RELEASE" -DBUILD_PACKAGES="DP3 Calibration Imager PyBDSM" -DUSE_OPENMP=ON "$HOME/src/$LOFAR_RELEASE"

- Build and install:

	make -j 4
	make -j 4 install  # with sufficient privileges

- Optionally, run the regression tests:

	ctest -j 4 --timeout 60

  All tests should pass, however, a few packages (not selected above) require
  GPU hardware or a database to pass all tests.

- You may want to add the installation path bin/ to your PATH by sourcing (not executing!) the lofarinit script:

	. "$HOME/local/$LOFAR_RELEASE/lofarinit.sh"  # for Bourne-like shells, or
	. "$HOME/local/$LOFAR_RELEASE/lofarinit.csh" # for C-like shells