Obit Astronomy Software

This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

   Note: binary distributions are available for Linux from the Obit
web page (http://www.cv.nrao.edu/~bcotton/Obit.html); for most users
this is preferable to a build from source.  The build from source is
necessary if you need to add, modify or debug Obit c software or want
Obit on a Mac. 

   This distribution allows the installation of Obit software for
processing astronomical (primarily radio) data.  The Obit package
relies on third party software and consists of a number of components.
The bulk of the third party software is included here and is built and
installed by included scripts. 
   The components of the Obit system are 1) the Obit libraries and
tasks (in c), 2) ObitView image display and ObitMess message server, 
3) ObitTalk an interactive python interface, and 4) ObitSD for single
dish (GBT) processing.  Obit and friends use AIPS and FITS files as
native data  types and is highly interoperable with AIPS. 
   Necessary software not included are X-windows and gmake.  Optional
software not included are pgplot (licensing restrictions) and
wxPython.  Software distributed here will be installed privately and
should not interfere with existing versions of packages (except
possibly as a side effect of setting $LD_LIBRARY_PATH or $PATH).

   The first step of installation is obtain a version of the software
from the subversion server, e.g.:

 > svn checkout https://github.com/bill-cotton/Obit

This will leave the installation under subdirectory ObitInstall
The installation scripts are in, and should be run from subdirectory 
ObitInstall.

   Third party and Obit software are built and installed using the
InstallObit.sh script.  If you already have some of the distributed
third party packages installed, the reinstallation can be omitted
using command line -without options to InstallObit.sh;  -help gives:
    Build Obit software
    Third party software may be deselected with -without and any of
    the  following to use a version of the package installed in a
    standard place 
	    CFITSIO - FITS library
	    GLIB    - GNU extensions to c
	    FFTW    - Fourier transform package (version 2 (float) or 3)
	    GSL     - GNU Scientific Library
	    ZLIB    - Compression library
	    MOTIF   - Motif graphics library
	    PYTHON  - Python
	    CURL    - Internet URL library
	    XMLRPC  - XMLRPC network protocol library
            BOOST   - headers to make c++ into a usable language (for WVR)
            WVR     - Bojan Nikolic's ALMA WVR library"
  
	    Select Obit options
	    THIRD - don't (re) install third party software
	    Obit  - don't (re) install Obit
	    ObitSD- don't (re) install ObitSD (single dish)
	    ObitView - don't (re) install ObitView
	    ObitTalk - don't (re) install ObitTalk

   For example, to install without using the included version of
Motif, python and GNU Scientific library:
 > InstallObit.sh -without MOTIF PYTHON GSL

   If you cannot get the InstallObit.sh script to work, the fallback is to 
install the needed third party manually (if not done by InstallObit.sh)
and run the configure script in the subdirectories under ObitSystem
Obit, ObitView, ObitTalk and ObitSD (If single dish package needed).
These configure scripts allow a great deal of flexibility; 
the see the details, use:
> ./configure --help
After running configure, run make to build the software in each of 
these subdirectories.

   Interprocess communications in Obit uses the xmlrpc protocol.  In
the c implementation, this uses the xmlrpc-c library which in turn,
depends on other packages for the actual communications. Xmlrpc-c can
use the curl package which is distributed here.

   To use the installed software, you have to tell your system where
to look for it.  If you've installed it under a directory whose path is
given by $OBITINSTALL (the ObitInstall directory), then you need to append 
$OBITINSTALL/other/lib to your $LD_LIBRARY PATH, e.g.
for csh
 > setenv LD_LIBRARY_PATH "$LD_LIBRARY PATH:$OBITINSTALL/other/lib"
for sh
 % LD_LIBRARY_PATH="$LD_LIBRARY PATH:$OBITINSTALL/other/lib"; export LD_LIBRARY_PATH
If this order picks up an incompatible library, prepend the 
ObitInstall/other/lib but  beware of potential problems with other software.

Similarly, you need to add $OBITINSTALL/bin to your $PATH
for csh
 > setenv PATH "$PATH:$OBITINSTALL/bin"
for sh
 % PATH="$PATH:$OBITINSTALL/bin"; export PATH

   In order to run ObitTalk, the environment variables $OBIT and $OBITSD (if installed)
need to be set:
for csh
 > setenv OBIT "$OBITINSTALL/ObitSystem/Obit"
 > setenv OBITSD "$OBITINSTALL/ObitSystem/Obit"
for sh
 % OBIT="$OBITINSTALL/ObitSystem/Obit"; export OBIT
 % OBITSD="$OBITINSTALL/ObitSystem/ObitSD"; export OBITSD

   In order to run Obit software from python without using ObitTalk, 
you need to set PYTHONPATH:
for csh
 > setenv PYTHONPATH "$PYTHONPATH:$OBITSD/python:$OBIT/python:$OBITINSTALL/opt/share/obittalk/python"
for sh
 % PATHPYTHON="$PYTHONPATH:$OBITSD/python:$OBIT/python:$OBITINSTALL/opt/share/obittalk/python"; export PATH

   The InstallObit.sh script creates a pair of setup files with the
commands to set the relevant environment parameters.  These are
setup.sh for sh (or bash) and setup.csh for csh (or tcsh).  The
appropriate file should be sourced before running Obit software.

   User documentation for ObitTalk can be found in
ObitSystem/doc/ObitTalk.pdf.  The most recent documentation is available
from the Obit home page http://www.cv.nrao.edu/~bcotton/Obit.html.

   Updates can be obtained using the Obit anonymous svn server.  
To update Obit, cd to the ObitSystem top directory 
($OBITINSTALL/ObitSystem as defined in the setup scripts created by 
the installation) and :
 % svn update

64 bit Notes
------------
   The distributed (most recent) version of zlib doesn't build a shared
library or generate code that can be linked with.  If your systen has
a libz - then use it and specify -without ZLIB to InstallObit.sh
   The distributed Motif doesn't appear to build correctly on a 64 bit 
system.  The distributed glib works but all messages are repeated and 
possibly has some modes of failure as well.

UBUNTU Notes:
------------
Glib, Motif
   The distributed versions of glib and openmotif do to seem to build correctly,
These need to be installed separately.  You'll need the development
versions (gthread also with glib). If you don't have the development
version of the basic X windows, you'll need that as well.

Python readline
   If readline is not installed on your system, when you start
ObitTalk you'll get a message like 
.Traceback (most recent call last):
  File "/export/users/bcotton/ObitInstall/opt/share/obittalk/python/ObitTalk.py", line 36, in <module>
    import readline, otcompleter
ImportError: No module named readline
You can install it; if you can find a readline.so, copy or link it to
 $OBITINSTALL/other/lib/python2.5/site-packages/.
Otherwise, grit your teeth and try to live without this,  edit the file 
/export/users/bcotton/ObitInstall/opt/share/obittalk/python/ObitTalk.py 
(using its name on your system) to comment out the readline lines:

# Use our own, somewhat restricted rlcompleter.
#import readline, otcompleter
#readline.parse_and_bind("tab: complete")

Unfortunately, this means you don't have command line editing.

Packages loaded to make a virgin UBUNTU system working::
	aptitude install libmotif-dev
	aptitude install libglib-dev
	aptitude install libglib2.0-dev
	aptitude install libmotif3
	aptitude install libreadline-dev
	aptitude install libx11-dev
	aptitude install libxt-dev
	aptitude install libxext-dev
	aptitude install libxext6
	aptitude install x11proto-print-dev

ObitTalk Documentation
   If your system doesn't have latex, the install of ObitTalk will not build the 
documentation,  Install latex and then in $OBITINSTALL/ObitSystem/ObitTalk/doc
issue "make all install"

Red Hat 6 notes:
----------------
Many of the distributed third party packages don't build, especially xmlrpc.
Get as many of them installed from RPMs as possible.  The configure scripts 
in Obit, ObitTalk, ObitView and ObitSD  need substutions for libraries:
-lxmlrpc_xmlparse =>  -lxmlrpc_server
-lxmlrpc_xmltok   =>  -lxmlrpc_server_abyss


Bill Cotton (bcotton@nrao.edu)