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)

- any        See the next section on Docker


Install using a Docker image / script
-------------------------------------

For prepared Docker images, see:

	http://www.lofar.org/wiki/doku.php?id=public:docker


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

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


For a(nother) Docker image, see the next section.


Install from Ubuntu Packages (or a Docker image / script)
---------------------------------------------------------

To install LOFAR Offline processing tools (and many more radio astro packages)
the easy way for Ubuntu LTS 16.04, see:

	KERN: The Radio Astronomy Software Suite
	http://kernsuite.info/


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 python-coverage  # optional
	apt-get install libxml++2.6-dev                      # or newer
        apt-get install libarmadillo-dev                     # optional, for DPPP_DDECal
	apt-get install libunittest++-dev                    # optional, for tests that use UnitTest++
	apt-get install python-xmlrunner                     # for some CEP/Pipeline/ tests
	apt-get install python-pygresql python-psycopg2 python-mysql.connector  # python mysql and postgresql interfaces
	apt-get install python-mock python-django            # for some SAS/ tests
	apt-get install postgresql                           # optional, for some SAS/OTDB_Services/ tests
	apt-get install libhdf5-dev                          # optional, required by casacore-dev from the KERN-2 suite.


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 python-coverage  # optional
	yum install libxml++-devel
        yum install armadillo-devel                          # optional, for DPPP_DDECal
	yum install PyGreSQL python-psycopg2 mysql-connector-python  # python mysql and postgresql interfaces
	yum install python2-mock python-django               # for some SAS/ tests
	yum install postgresql                               # optional, for some SAS/OTDB_Services/ tests

	RPMs for these 3 known to work on CentOS 7 can be found at https://support.astron.nl/lofar_issuetracker/issues/8161
	- blitz, blitz-devel: 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).
	- log4cplus: idem as blitz (LOFAR log4cxx support is dodgy).
	- unittest++, unitest++-devel (optional): idem, but can take two RPMs from Fedora 22 (or build from source).

	- python-xmlrunner: pip install xmlrunner  # possibly with: --target=/your/path/libdir/pythonversion/site-packages



NOTE (any OS): For manual builds, the most prominent dependencies you may need to install are:

	casacore:                  https://github.com/casacore/casacore
	python-casacore ('pyrap'): https://github.com/casacore/python-casacore
	IERS/measures tables:      ftp://ftp.astron.nl/outgoing/Measures/WSRT_Measures.ztar (auto-updated weekly),
	                               also see https://github.com/casacore/casacore-data-update
	casarest:                  https://github.com/casacore/casarest

	AOFlagger:                 https://sourceforge.net/projects/aoflagger/
	    which may need: Debian/Ubuntu: libgsl-dev libgtkmm-[2.4|3.0]-dev libsigc++-2.0-dev
	                    CentOS/Fedora: gsl-devel gtkmm[24|30]-devel libsigc++20-devel

	PyBDSF (blob detector & source finder): https://github.com/lofar-astron/PyBDSF

	python-monetdb (if using GSM inside the LOFAR network): pip install python-monetdb  # possibly with: --target=/your/path/libdir/pythonversion/site-packages


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}[cxx11]_{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 the lofarinit script:

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