README.install

Executive Summary
=================

Installation of the core version of NEMO is roughly follows (your yapp selection may vary):

      git clone https://github.com/teuben/nemo
      cd nemo
      ./configure --with-yapp=pgplot
      make build check bench5
      source nemo_start.sh

many more details can be found below. The biggest caveat on this scheme is the use of the pgplot
driver for the yapp plotting interface. By default it would install a safe but fairly useless
postscript-only driver. The pgplot driver is probably the most functional, but We also have (fairly)
functional plplot and giza drivers. 

The configure line can be complex, for example for a Mac it could be:

      CC=gcc-10 CXX=g++-10 F77=gfortran-10 ./configure --disable-shared --with-yapp=pgplot

A simple test to create and plot a 1911 Plummer sphere is the following:

      mkplummer p10.dat 10
      snapprint p10.dat
      snapplot p10.dat
      tsf p10.dat



Failing pgplot
--------------

One of the more common installation problems is with pgplot: didn't compile or link. Usually
you can find out with the command

      mknemo tabplot

what is wrong/missing.   Sometimes it's the X libraries, sometimes the PNG library, or something  with PGPLOT alltogether.
We keep a version of pgplot for manual compilation, which might work well on a mac. Here's an example
to try in that case:

      mknemo pgplot
      #   this needs to work, otherwise the next steps make no sense
      #   it will have deposited a number of pgplot things in $NEMOLIB
      
      ./configure --with-yapp=pgplot --enable-png --with-pgplot-prefix=$NEMOLIB
      source nemo_start.sh
      make build check
      mknemo tabplot
      tabgen - | tabplot - point=2,0.5

If this still fails, and you just want a non-graphical NEMO to work, use the PS driver instead:

      ./configure --with-yapp=ps
      source nemo_start.sh
      make build check
      mknemo tabplot
      tabgen - | tabplot - point=2,0.5
      open yapp.ps

there should be a file "yapp.ps" which you might be able to open or xdg-open.


Preconditions for Installation
==============================

To build the basics of NEMO you need compilers (C/C++/Fortran).  C is essential,
C++ and Fortran highly recommended.  You will also need the usual build tools

C		essential
C++		highly recommended (essential for gyrfalcON)
Fortran    	highly recommended
tcsh		essential (some scripts are still in csh)
make 		essential
cmake		highly recommended
pgplot    	recommended for yapp_pgplot (we also have a "mknemo pgplot" builtin option)
cfitsio		recommended for some tools
hdf4     	recommended for some tools
hdf5		recommended for some tools
netcdf          recommended for some tools
python3		recommended (a builtin anaconda3 is one option)
boost           recommended (for uns_projects)
swig            recommended (for unsio)
x11, cairo      essential, but depending on the selected yapp graphics driver


For debian and redhat based systems, one of these may help to install packages:

    make install_apt
or
    make install_dnf

based on a package requirements style file in $NEMO/src/scripts/requirements.




Depending on your packaging tools (apt, yum, dnf, brew, port, ....) these are hidden under
various package names

   dpkg -L pgplot5
   dpkg -S /usr/include/cpgplot.h
   dpkg -l

   rpm -ql pgplot
   rpm -qf /usr/lib64/libpgplot.so.5.2.2
   rpm -qa

or your system manager has hidden them in a module

   module avail

See examples of package names in $NEMO/src/scripts/linux and $NEMO/src/scripts/brew (for Mac too)


-gfortran
-libx11-dev
-libxt-dev
-libxext-dev
-libcairo2-dev
-build-essential
-cmake
-csh
-pgplot5
-libhdf4-dev
-libhdf5-dev
-hdf5-tools


DOWNLOAD and INSTALLATION: two examples 
=======================================

Perhaps the easiest way to install nemo is using the docs/install_nemo
script. The following example shows how to bootstrap this:

    wget https://teuben.github.io/nemo/install_nemo
    csh -f install_nemo nemo=nemo
    source nemo/nemo_start.sh


if you prefer the more classic approach, we do use configure under the hood

    git clone https://github.com/teuben/nemo
    cd nemo
    ./configure ...
    make build
    source nemo_start.sh


The configure script has many options, use --help to review them. The
install_nemo script has a number of key=val type command line options that
will aid in using some of the configure options.


MANUAL INSTALLATION BACKGROUND:
===============================

The remainder of this document gives some more examples and background
information in case the more automated script(s) to install NEMO have
failed you.

Installation of NEMO V4.x roughly follows that of most open source
packages, except that NEMO does not install its products in an
external prefix like /usr/local, but keeps them "in-place" and
bootstraps a special NEMO shell environment by sourcing an "rc" file 
where things like your search path are modified for your shell.  Hence
the basic scheme is more one of (except commands are different and
detailed below!!!):

	configure   
	make build
	source nemo_start.sh

It may be handy to pre-install a few libraries and packages on your
system, if they do not exist yet. For a few common ones (e.g. pgplot,
cfitsio, gsl, hdf, hdf5) we also do have some support to install them
within the NEMO tree before the NEMO is installed.  Typically you can
then use the commonly used sequence

      configure --prefix=$NEMO/opt
      make
      make install
or
      mkdir build
      cd build
      cmake
      -DCMAKE_INSTALL_PREFIX=$NEMO/opt ..
      make
      make install

We generally now support this via the mknemo script, e.g.

      mknemo cfitsio

would compile cfitsio under $NEMO/opt, which all Makefiles when building
NEMO programs use to compile and link.

Preconditions for INSTALLATION
==============================

a1) Installing PGPLOT - native Linux/MacOSX-brew distribution

   Some distributions now keep pgplot in their package list. For example
   in Ubuntu you can use
      	     sudo apt install pgplot5
   (but see below for the giza version).  In this case you can use

   	configure --with-yapp=pgplot --with-pgplot-prefix=/usr/lib

   In Centos PGPLOT is also available

             sudo yum install pgplot-devel pgplot

   On MacOSX, with brew, you can
             brew install pgplot

   If you are lucky, you can also find the proper paths via pkg-config, but
   you will need to know the package name and they can vary. 

a2) Installing PGPLOT (native CALTECH version)

   It is recommended to install PGPLOT before you install NEMO. 
   We do have a simple procedure to install PGPLOT during the NEMO
   install itself.  You can also decide to use another plotting (YAPP) 
   device though, e.g. plplot (a pure C plotting library similar to PGPLOT) 
   is gaining in popularity.

   Unless it finds the PGPLOT library in a reasonably location, or as dictated
   by the PGPLOT_DIR environment variable, or via the --with-pgplot-dir= option
   to configure, as a fallback NEMO would install itself with a very simple 
   postscript-only graphics library (a.k.a. yapp_ps), 

   If none of these options work, you can also try to install PGPLOT in
   for example the following way

	cd $NEMO/local
	$NEMO/src/scripts/pgplot.install
	(you may need to get the pgplot522.tar.gz, or newer, file from
        Caltech (http://astro.caltech.edu/~tjp/pgplot/) or a local repository)

   or the newer command in a current NEMO:

        mknemo pgplot

   On some older linux systems may need to create the following symbolic link
		 ln -s /usr/X11R6 /usr/X11


a3) Installing PGPLOT - MIRIAD pgplot git release

   You can also place the pgplot source code in $NEMO/local (the default git install
   uses this method), and use something like

   	make pgplot png=1 gif=1


a4) Install PGPLOT (giza github installation) -

	The giza package is now primarily maintained on the developer's github account
	(https://github.com/danieljprice/giza).  The giza implementation of PGPLOT can be installed
	by adding an extra parameter to the ./install_nemo script: "./install_nemo giza=1"

	It can also be cloned from price's repository using git clone https://github.com/danieljprice/giza.git.
	Then it can be installed using the same instructions as the sourceforge download.  Here is an example

	git clone https://github.com/danieljprice/giza.git
	cd giza
	./configure --prefix=$NEMO
	make
	make install

	(OLD) Install PGPLOT (giza sourceforge) - 

    The giza package (http://giza.sourceforge.net) has its own implementation of PGPLOT,
    which is compatible with cairo. Here is an example that seems to work with NEMO

    cd $NEMO/local
    svn co http://svn.code.sf.net/p/giza/code/ giza
    cd giza
    ./configure --prefix=$NEMO
    make
    make install

    After this you can use the regular

    cd $NEMO
    configure --with-yapp=pgplot --with-pgplot-prefix=$NEMO/lib

    My experience with this version of pgplot is not ideal yet.

b1) Installing HDF4


   Preferred command:    mknemo hdf4
    
   You only need the HDF library if you plan to work with the ZEUS or CMHOG
   hydrocodes.
	
   This requires:
	libdf.a
	libz.a	(often comes with the system)
	df.h    -- and many others belonging to HDF4
   A newer version of HDF (HDF5) is also supported, they used hdf5.h, see below.

   The install package for hdf4 can be found at https://support.hdfgroup.org/products/hdf4/.
   You will need to extract the package. The next command assumes you are already in HDF4 directory
   One way to install this package is 

   configure --prefix=$NEMO
   make
   make install

   examples:

   https://support.hdfgroup.org/ftp/HDF/releases/HDF4.2.14/src/CMake-hdf-4.2.14.tar.gz
   https://support.hdfgroup.org/ftp/HDF/releases/HDF4.2.14/src/hdf-4.2.14.tar.gz

b2) Installing HDF5

   Preferred command:    mknemo hdf5

   https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.10/hdf5-1.10.6/src/hdf5-1.10.6.tar.gz

   This version of HDF may either be installed via the system, or in $NEMO/opt.


c) Installing CFITSIO  (pending work on configure.in)
 
   NEMO has two internal routines (fits.c and fitsio.c) that handle various
   types of fits I/O. Optionally the CFITSIO library can also be used, e.g.
   fitsio_nemo.c implements the fitsio.c file by providing a wrapper
   that actually calls the CFITSIO library (courtesy Bill Pence)

   wget ftp://heasarc.gsfc.nasa.gov/software/fitsio/c/cfitsio3390.tar.gz
   (see https://heasarc.gsfc.nasa.gov/fitsio/fitsio.html)
 
   One way is to embed it into NEMO, so when you configure cfitsio

	configure --prefix=$NEMO
	make
	make install

   If your system has FTOOLS installed, possibly via the LHEASOFT package,
   you can use their prefix, e.g.

	configure --with-cfitsio-prefix=/opt/lheasoft/SunOS_5.6_sparc


d) If you are on a system where you need to install NEMO and other packages,
   but don't have root access to places like /usr/local, 
   but plenty of disk-space, you can also host these packages inside of NEMO.

   For this a directory $NEMO/opt has also been created during the installation
   process, 
   Under $NEMO/opt you will then find the usual /usr/local hierarchy:
	bin	
	include	
	info		
	lib	
	man	
	share
   Packages that NEMO can use can then be installed under this hierarchy
   easiest with the "mknemo" command:

	gsl		configure --prefix=$NEMO
	cfitsio		configure --prefix=$NEMO
	plplot
	netcdf4
	
   NEMO can then use these packages as follows:

	configure --with-gsl-prefix=$NEMO/opt
	configure --enable-gsl
	configure --disable-gsl		(the default)

Peer Installations
==================

Here is a list of peer (astronomy) packages install instructions that could
well be useful in case of issues with the instructions listed above:

* cloudy:  https://gitlab.nublado.org/cloudy/cloudy/-/wikis/CompilingCloudyNext



Some old notes
==============


*) pieces of configure out of date?  Encountering a new machine?

	1) you can update the config.guess and config.sub

		wget ftp://ftp.gnu.org/pub/gnu/config/config.guess
		wget ftp://ftp.gnu.org/pub/gnu/config/config.sub
		chmod a+x config.guess config.sub

	2) regenerate configure from configure.in

		autoconf

	3) replace some *.m4 files

	4) replace aclocal.m4:		aclocal



*) Configuration options known to work:

	--with-pgplot-prefix=$NEMOLIB

		expects grfont.dat and friends to be in the named directory
		($NEMO/src/scripts/pgplot.install will help you
		installing pgplot in $NEMOLIB if you need)

	--with-hdf-prefix=PFX

		expects hdf.h to be found somewhere in an {include,hdf} 
		subdirectory and will link with 'df', 'jpeg' and 'z' library.
		Doesn't work with HDF5 yet, assumes HDF4 for ow.

	--with-miriad-prefix=PFX
		if $MIR is present, it will use this variable, else you need 
		to set it.

	--disable-fortran
		if you don't have a working fortran compiler (actually doesn't work)

	--with-ccmalloc
		use CCMALLOC to debug malloc usage

	--with-yapp=ps
		use a PS based yapp, on systems where you cannot get pgplot to work,
		or really don't have a working fortran compiler

	--with-cfitsio-prefix=PFX
		--disable-cfitsio		explicitly disable it 
		--enable-cfitsio		explicitly enable it  (the default)

	--with-gsl-prefix=PFX
		--enable-gsl
		--disable-gsl		(the default)