***************************************************************************

                  IMAGER   Installation guidelines
                       
Acknowledgement: This guide is derived from the GILDAS Intallation guide
(see https://www.iram.fr/IRAMFR/GILDAS/), modified for the specificities
of IMAGER.

***************************************************************************

 Table of contents:

    I - ABOUT

    II - DOWNLOAD
      1) Retrieving sources from IMAGER homepage
      2) Retrieving binaries from IMAGER homepage
      3) Retrieving documentation from IMAGER homepage

    III - REQUIREMENTS
      1) Material
      2) Needed tools to build executables
      3) Needed tools to build the documentation

    IV - INSTALL UNDER MAC OSX
      1) MacPorts package
      2) Installation from sources
      3) Troubleshooting

    V - INSTALL UNDER LINUX
      1) Dependencies
      2) Compile and install (binaries)
      3) Post-installation (binaries)
      4) Compile and/or install (documentation)
      5) Troubleshooting

    VI - INSTALL UNDER MS WINDOWS
      1) MicroSoft Installer (binary distribution)
      2) Installation from sources under Cygwin

    VII - UNINSTALL
      1) Under Linux
      2) Under MacPorts

***************************************************************************

I - ABOUT
----------

  Please use the "Contact" item from the IMAGE Web page
    https://imager.oasu.u-bordeaux.fr 
  for any question, remark, suggestion.

***************************************************************************

II - DOWNLOAD
--------------

  1) Retrieving binaries from IMAGER homepage:

     Linux:  A Linux container, using the "Apptainer" tool, is distributed
     from the Web page, item Support.
     
     MacOS-X
     IMAGER is distributed using MacPorts.
     
  2) Retrieving sources from IMAGER homepage:

     Sources for each released version are available in a Compressed Tarball.
     An installation script is provided
     
  3) Retrieving documentation from IMAGER and GILDAS homepage:

     The IMAGER documentation is packaged with the binaries, but
     also available on the Web site (item Documentation),
     and directly accessible through https: from within the code.
     
     Other GILDAS compiled documentation are distributed as tarballs at the address:
       https://www.iram.fr/~gildas/dist/
     You have to pick a tarball named gildas-doc-mmmyy.tar.gz

***************************************************************************

III - REQUIREMENTS
-------------------

  1) Material:

     - Building the IMAGER binaries under Linux or MacOS-X requires
       about 300 MB of temporary disk space (compilation) and 100 MB of
       permanent disk space (installation).
     - The gfortran compiler might require up to 5-6 GB of RAM when
       compiling IMAGER sources. At run time, IMAGER requires
       about 12 MB at startup, but then consumes as much memory as data
       created or loaded in memory.

  2) Needed tools to build executables:

     Successful building of IMAGER binaries on a UNIX/Linux/OSX system
     minimally requires:
     - Bourne compatible shell (sh, ksh, bash, etc...) for build purpose
       only. The end-users can then use Imager from csh-like or
       Bourne-like shells.
     - NROFF for on-line help building.
     - Perl for automatic interface extraction during compilation process.
     - A C compiler (either GCC or the native C compiler).
     - GNU make:
       The current building system is using the GNU make facility which has
       some some desirable but non-portable features (i.e. including
       makefiles, conditions). This does not seem a strong limitation as it is
       easy to install GNU make for your system. In fact, GNU make is the
       default for linux boxes. For others OS, just try to type gmake instead
       of make: it is probably already installed.
     - A FORTRAN 2003/2008 compiler:
       Latest GNU Fortran (gfortran >= 13.) 
     - GTK 2 development tools for graphic and widget support.
     - Python (3.12 or later). Imager will use the Python version as found 
       from the "python" executable in the environment.

  3) Needed tools to build the documentation:

     Successful building of PDF/HTML documentation minimally requires
     recent versions of:
     - ps2epsi
     - epstopdf
     - latex (version 2e with makeidx, graphicx and html package)
     - latex2html
     - pdflatex
     For your convenience, we distribute compiled PDF/HTML
     documentation in case you do not have those tools. 
      See II.3) above
     
***************************************************************************

IV - INSTALL UNDER MAC OSX
---------------------------

  Imager and its dependencies can be installed with the MacPorts
  package manager (www.macports.org).

  0) Prerequisites:

     Both installation methods 1 and 2 below require the installation
     of:
     - Xcode, needed by MacPorts. Get it from
       https://developer.apple.com/xcode/ with an Apple identifier
       (more than 1 GB to be downloaded from the app store). See
       e.g. the Xcode installation guidelines suited for MacPorts at
       www.macports.org/install.php
     - Xquartz, needed for Gildas plots (www.xquartz.org). XQuartz is
       successfully installed if the command "xclock" is available and
       opens a clock in a small graphical window. If not, start
       Xquartz from Applications > Utilities > XQuartz.
     - MacPorts, a package manager, is needed retrieve and install
       transparently Gildas and its dependencies. Follow MacPorts
       installation guidelines at www.macports.org/install.php
       MacPorts is successfully installed when e.g. the command "port
       help" is available.
     - A Python 3 version available (recent Mac OS-X system default)

  1) MacPorts package:

     This is the recommended way to install IMAGER under Mac OS-X
     Once MacPorts and XQuartz are installed, IMAGER installation 
     is straightforward. Type:
        sudo port install imager
        sudo port -f activate imager
     
     Updating to the newest release is done with the command:
        sudo port upgrade imager
     You might need to update MacPorts itself first:
        sudo port selfupdate
        
  2) Installation from sources:

     As an alternate solution, it is possible to compile IMAGER by
     yourself. You have to use MacPorts to install first the 
     dependencies. Please use the latest version of gcc 
     (currently gcc14, but this may evolve with time...)
     - Installing the dependencies:
          shell> sudo port install gcc14
          shell> sudo port select gcc # show available arguments
          shell> sudo port select gcc mp-gcc14  # Choose the desired one
          shell> sudo port install gtk2
          shell> sudo port install pkgconfig
     - Optionally, you can install the FFTW3 libraries. However, by
       default, MacPorts does not install the Fortran entry points to
       these libraries. You have to ask for them explicitly by
       requesting the appropriate "variant". Have a look at:
          shell> sudo port variants fftw-3-single
       Choose the one which matches the gcc/gfortran version selected
       above, e.g.
          shell> sudo port install fftw-3-single +gcc14
     - Finally you can follow the standard Linux steps to compile
       IMAGER from the sources (see Section V below).

  3) Troubleshooting:

     - If you have problem with rsync when running 
        "sudo port selfupdate", 
      you can modify the file
       /opt/local/etc/macports/sources.conf by replacing the line:
          rsync://rsync.macports.org/release/ports/ [default]
       with:
          #rsync://rsync.macports.org/release/ports/ [default]
          https://www.macports.org/files/ports.tar.gz [default]
       and run "sudo port sync" instead of "sudo port selfupdate".
       
     - If the IMAGER installation fails and the log file shows the
       following error:
         :info:build FATAL:/opt/local/bin/../libexec/as/x86_64/as:
         I don't understand 'm' flag!
       This problem is described here:
         https://trac.macports.org/ticket/56919
       In short, the assembler program ('as') which is used is not the
       correct one. Type
         sudo port install cctools +xcode
       to switch to the correct version. Then resume the installation.
       
     - If the installation fails and the log file shows the
       following error:
         :info:build ld: unexpected token: !tapi-tbd-v3 file
         '/System/Library/Frameworks//CoreFoundation.framework/CoreFoundation.tbd'
         for architecture x86_64
       This problem is described here:
         http://mac-os-forge.2317878.n4.nabble.com/linker-errors-ld-unexpected-token-tapi-tbd-v3-file-td363061.html#a363073
       In short, you should type:
         sudo port install ld64 +ld64_xcode
       Then you should retry the IMAGER installation. You should clean the
       previous attempt first:
         sudo port clean imager
       Then proceed:
         sudo port install imager
         
     - If the program won't open any graphical window and shows this
       warning instead:
         Gtk-WARNING **: xx:xx:xx.xxx: cannot open display
       check that XQuartz server is installed and running (see
       Prerequisites section above).
       
     - If you observe this message when opening IMAGER,
       please see the same TROUBLESHOOTING section for Linux:
        Gtk-WARNING **: Locale not supported by C library.
                        Using the fallback 'C' locale.
                        
     - Graphic hardcopies to PDF are ensured through system utilities ps2pdf
       and epstopdf. They can be installed thanks to the following ports:
          shell> sudo port install texlive-basic      # provides ps2pdf
          shell> sudo port install texlive-fontutils  # provides epstopdf

***************************************************************************

V - INSTALL UNDER LINUX
------------------------

  1) Dependencies:

     In addition to the standard developper tools (make, gcc, nroff,
     etc), the following dependencies must be installed. Root
     priviledges are required here.

     - Fedora 28 (or redhat-like distributions):
        Required:    dnf install gcc-gfortran gcc-c++ gtk2-devel
        Recommended: dnf install python-devel numpy libpng-devel texlive-epstopdf
        Optional:    dnf install fftw-devel cfitsio-devel
        Pre-install: export GAG_SEARCH_PATH="/usr/lib"
        Install:     follow installation steps at paragraph 2

     - Ubuntu 20.04 (or debian-like distributions):
        Required:    sudo apt install gfortran g++ libgtk2.0-dev
        Recommended: sudo apt install python-is-python3 python3-dev python3-numpy texlive-font-utils
        Optional:    sudo apt install libfftw3-dev 
        Pre-install: export GAG_SEARCH_PATH="/usr/lib:/usr/lib/x86_64-linux-gnu",
        Install:     follow installation steps at paragraph 2

  2) Compile and install (binaries):

     Building the binaries should just need the following sequence of
     commands. IMAGER itself does not need root priviledges for
     installation and execution: it can be restored anywhere and
     installed by any user for its own needs.

     Read carefully the messages and warnings returned by the command. 
     You can safely ignore CFITSIO warnings.
     If everything seems correct, then compile and install Gildas:
        shell-prompt> make
        shell-prompt> make install
     Finally, follow the instructions at the end of the make install
     process. Installation is successful if you can start the programs
     'greg', 'imager' or 'viewer' from a new terminal.

  3) Post-installation (binaries):

     After the installation is successful, you can optionally remove
     the sources and compilation directory (gildas-src-mmmyy). This is
     useful only to save disk space. 

  4) Compile and/or install (documentation):

     - From the tarball archive (easiest):
          shell-prompt> mv gildas-doc-mmmyya.tar.xz gildas-exe-mmmyya/
          shell-prompt> cd gildas-exe-mmmyya/
          shell-prompt> tar -xf gildas-doc-mmmyya.tar.xz
     - Directly from the sources:
       Compilation of documentation is not done by default when
       compiling executables because: i) it requires special tools
       (see requirements) and ii) it takes time.
       To compile and install the PDF documentation, type:
          shell-prompt> make doc
          shell-prompt> make install-doc
       To compile and install the HTML documentation, please type:
          shell-prompt> make html
          shell-prompt> make install-html

  5) Troubleshooting:

     - This message can be displayed when starting a Gildas program:
        Gtk-WARNING **: Locale not supported by C library.
                        Using the fallback 'C' locale
       This is not an IMAGER issue. This means that your locale
       settings (type "locale" in a terminal) indicate one or more
       locales that are not installed on your system (type "locale -a"
       in a terminal for the full list). You should fix your
       environment variables in order to use an installed locale
       (e.g. export LANG=en_US.utf8, beware this may change your
       programs behavior regarding language), or install the missing
       locale(s).
       
     - Conflict with Anaconda: when installed from the downloadable
       installer, Anaconda comes with a lot of development tools and
       libraries which override the default system ones, but not in a
       consistent way. This has been proven to break software compilation and/or
       execution (Image, Gildas and others). For example:
         astro: /home/user/anaconda/lib/libstdc++.so.6: version 
                `GLIBCXX_3.4.21' not found (required by /home/user/
                gildas-exe-jan17a/x86_64-ubuntu16.04-gfortran/lib/libatm.so)
       This happens because Anaconda gives precedence to its own binaries
       and include files (duplicate but different versions of system ones)
       in the user's environment. There are several ways out of this issue:
         a) Install Anaconda from your OS repositories (instead of custom
            installation in the user account). This way, there should be
            a correct integration of Anaconda within the OS.
         b) Keep Anaconda in the user account, but "hide" it during IMAGER
            installation and execution. In other words, you have to ensure
            that there is no reference to Anaconda installation paths in
            the environment variables $PATH and $LD_LIBRARY_PATH. You most
            likely have to edit your ~/.bashrc. Once this is done
            recompile, install, and try executing Imager. If it runs fine,
            a permanent solution could be to use a shell function which
            loads Anaconda environment only when needed, e.g.
              function anaconda() {
                  export PATH=...
                  export LD_LIBRARY_PATH=...
                  anaconda
              }
         c) The next time you install Anaconda, you should answer "No" to
            the question: "Do you wish the installer to prepend the
            Anaconda<2 or 3>install location to PATH...?". Then use a
            function like the above example to get it working. Reference:
            https://docs.anaconda.com/anaconda/user-guide/faq/#distribution-faq-linux-path

***************************************************************************

VI - INSTALL UNDER MS WINDOWS
------------------------------

    Create a Linux VM machine, and use the Apptainer binary.
     
***************************************************************************

VII - UNINSTALL
---------------

  1) Under Linux

     - Except if you want to save disk space, you have no need to
       uninstall any previous Imager installation. Each version goes
       into its own 'imager-src-XXX' directories. The default version used 
       is ruled by the environment variable $GAG_ROOT_DIR that is set in user's
       ~/.bash_profile. You can modify it as you want to point to the
       desired version.
     - Remember to start a new terminal each time you modify your
       ~/.bash_profile .
     - For a complete uninstall of Imager, just remove the directories
       'imager-src-XXX' and 'imager-exe-XXX', and suppress the lines
       related to Imager in your ~/.bash_profile

  2) Under MacPorts

     - MacPorts keeps older Imager versions when you install a new
       one. At some point you might want to clean all the useless
       versions. You can check for all installed version with
         sudo port installed imager
       You will see a list of versions with a @ name, e.g.
         imager @202309_0+gcc12 (active)
         imager @202410b_0+gcc12
       Uninstalling a single version can be done with e.g.
         sudo port uninstall imager @202410b_0+gcc12
       Uninstalling several versions can be done with
         sudo port uninstall imager
       Answer at the prompt which versions are to be uninstalled.
     - If you wish to completely uninstall MacPorts and Imager, check
       here for the MacPorts recommendations:
         https://guide.macports.org/chunked/installing.macports.uninstalling.html

***************************************************************************
