\documentclass[11pt]{article}
%\usepackage[utf8]{inputenc}
\usepackage[titles]{tocloft}
\usepackage{natbib}
\usepackage{xcolor}
\usepackage{verbatim}
\input{imager-def.tex} %  IMAGER specific definitions
%
\pdfminorversion=7

% \newcommand{\lang}[1]{\texttt{\MakeUppercase{#1}$\backslash$}}
\newcommand{\IRAM}{\mbox{IRAM}}

\newcommand{\lmv}{\texttt{lmv}}
\newcommand{\clean}{\texttt{CLEAN}}
\newcommand{\uv}{\textit{uv}}
\newcommand{\emm}[1]{\ensuremath{#1}}   % Ensures math mode.
\newcommand{\emr}[1]{\emm{\mathrm{#1}}} % Uses math roman fonts.
\newcommand{\nds}[1]{\emm{\displaystyle#1}} % Normal display size for array and tabular environment.
\newcommand{\paren}[1]  {\nds{\left(  #1 \right) }} % Parenthesis. 
\newcommand{\cbrace}[1] {\nds{\left\{ #1 \right\}}} % Curly Braces.
\newcommand{\abs}[1]{\emm{\left| #1 \right|}} % Absolute value.
%\newcommand{\sicvar}[1] {\mbox {\tt #1}}
%\newcommand{\sicvar}[1] {\mbox {{\color{magenta}\tt #1}}} % Works with "magenta" only so far
\newcommand{\sicvar}[1] {\mbox {{\color{magenta}{\sc #1}}}} % Works with "magenta" only so far
\newcommand{\file}[1] {\mbox {{\color{magenta}\tt #1}}}
\newcommand{\script}[1] {\mbox {{\color{magenta}\tt #1}}}
\newcommand{\qom}[1] {\mbox {{\color{magenta}\tt #1}}}
\newcommand{\qomm}[2]{\mbox {{\color{magenta}\tt #1 #2}}}
\newcommand{\com}[1] {\index{#1} \qom{#1}}
\newcommand{\comm}[2]{\mbox {{\color{magenta}\tt #1 #2}}\index{#1!#2}}
\newcommand{\mymath}[1]{\mbox {\it #1}}
%
%\newcommand{\lang}[1]{\mbox {\texttt{\MakeUppercase{#1}\textbackslash}}}
%\newcommand{\imager} {\mbox{{{\sc imager}}}}
\newcommand{\imager} {\mbox{{\color[rgb]{1,0,0}{\sc imager}}}}
\newcommand{\lang}[1]{\mbox {\color{magenta}{\texttt{\MakeUppercase{#1}\textbackslash}}}}
\newcommand{\viewer}    {\mbox{{\color{red} \sc viewer}}}
\newcommand{\button}[1] {\mbox{\tt\bf #1}}
%
% Color require some strange tricks to be more or less correct in HTML version !...
\renewcommand{\sic}    {\mbox{{\color{red} \sc sic}}}
\renewcommand{\greg}   {\mbox{{\color{red} \sc greg}}}
\renewcommand{\clic}   {\mbox{{\color{red} \sc clic}}}
\renewcommand{\class}   {\mbox{{\color{red} \sc class}}}
\renewcommand{\mapping}{\mbox{{\color[rgb]{1,0,0}{\sc mapping}}}}
\renewcommand{\sicvar}[1] {\mbox {{\color{blue}\tt #1}}} % Works provided it has been define with "magenta" first in HTML !
\renewcommand{\lang}[1]{\mbox{{\color{blue}{\texttt{\MakeUppercase{#1}\textbackslash}}}}} % TRIAL
%\renewcommand{\file}[1] {\mbox {{\color{cyan}\tt #1}}}
\renewcommand{\file}[1] {\mbox {{\color{olive}\tt #1}}}
\renewcommand{\script}[1] {\mbox {{\color{violet}\tt #1}}}
%
% With the "tocloft" package, to control TOC horizontal spacings
%\renewcommand*\cftchapnumwidth{2em}
\renewcommand*\cftsecnumwidth{3em}
\renewcommand*\cftsubsecnumwidth{4em}
\renewcommand*\cftsubsubsecnumwidth{5em}
%
% Bugs
%
\newcommand{\added}{\mbox{{\bf Added }}}
\newcommand{\discovered}{\mbox{{\color{red} Discovered }}}
\newcommand{\corrected}{\mbox{{\color{red} Corrected }}}
% also a bug in Latex2Html  -- must re-issue the command to make it work
\renewcommand{\corrected}{\mbox{{\color[rgb]{0.1,0.8,0.1} Corrected }}}

\makeindex{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

% \frontmatter{} % For BOOKS only

\begin{center}
  \huge{
  \textbf{IMAGER Programming Guide} 
  \\[2\bigskipamount]
  \textbf{Reference document to maintain, develop and distribute IMAGER}
  } \\[2\bigskipamount]
\end{center}

%\input{imager-version.tex}

\begin{description}
\item\textbf{Documentation:}\\ 
  Active contributor: S.~Guilloteau (1)
\end{description}
1. Laboratoire d'Astrophysique de Bordeaux, CNRS \& Universit\'e de Bordeaux\\
%2. Observatoire Aquitain des Sciences de l'Univers, CNRS \& Universit\'e de Bordeaux\\
%3. Institut de Radio Astronomie Millimétrique
\clearpage
\newpage 

\centerline{\Large\bf Notations}
\bigskip{} %

Throughout this document, colors are used to highlight the names of categories of entities:
\begin{itemize}
\item \mbox{{\color[rgb]{1,0,0}{\sc program}}} is a GILDAS program name.
\item \lang{Language} is a SIC Language name
\item \qom{NAME} is a command name, keyword or option
\item \sicvar{SICVAR} is a SIC variable
\item \script{ScriptName} is an \imager{} script (external text file) that can be executed by the \com{@} command
\item \file{FileName} is an external file, e.g. a data file.
\end{itemize}

\begin{rawhtml}
  Note: this is the on-line version of the IMAGER Manual.
  A <A HREF="https://imager.oasu.u-bordeaux.fr/wp-content/uploads/doc/imager.pdf"> PDF version</A>
  is also available.
\end{rawhtml}

\bigskip{} %

Related information on \imager{} is available in:
\begin{latexonly}
  \begin{itemize}
  \item{IRAM Plateau de Bure Interferometer: Introduction}
  \item{IRAM Plateau de Bure Interferometer: OBS Users Guide}
  \item{IRAM Plateau de Bure Interferometer: Atmospheric Calibration}
  \item{IRAM Plateau de Bure Interferometer: Calibration Cookbook}
  \item{CLIC: Continuum and Line Interferometric Calibration}
  \item{GREG: Graphical Possibilities}
  \item{SIC:  Command Line Interpretor}
  \end{itemize}
\end{latexonly}
%
\begin{rawhtml}
  <UL>
  <LI> IRAM Plateau de Bure Interferometer: <A HREF="https://www.iram.fr/IRAMFR/GILDAS/doc/html/noema-intro-html/noema-intro.html">
  Introduction</A>
  <LI> IRAM Plateau de Bure Interferometer: <A HREF="https://www.iram.fr/IRAMFR/GILDAS/doc/html/obs-html/obs.html"> 
  OBS Users Guide</A>
  <LI> IRAM Plateau de Bure Interferometer: <A HREF="https://www.iram.fr/IRAMFR/GILDAS/doc/html/pdbi-cookbook-html/pdbi-cookbook.html"> 
  Calibration CookBook</A>
  <LI> <A HREF="https://www.iram.fr/IRAMFR/GILDAS/doc/html/clic-html/clic.html"> CLIC:</A>  
  Continuum and Line Interferometric Calibration 
  <LI> <A HREF="https://www.iram.fr/IRAMFR/GILDAS/doc/html/greg-html/greg.html"> GREG: Graphical Possibilities</A>
  <LI> <A HREF="https://www.iram.fr/IRAMFR/GILDAS/doc/html/sic-html/sic.html">   SIC:  Command Line Interpretor</A>
  </UL>
\end{rawhtml}


\newpage
\tableofcontents{} %

% \mainmatter{} % for BOOKS only

\newpage{}

\section{Overview}

\imager{} (including its associated visualizer \viewer{}) is a software package to produce,
visualize and (to a lesser extent) analyze images from radio interferometers and telescopes, 
such as ALMA, NOEMA, the IRAM 30-m and the JVLA. 

\imager{} uses a \textbf{tailored} version of the \gildas{} kernel infrastructure to interact with the user
(through the \sic{} command interpretor), access to the data (using the Gildas Data Files and FITS format),
and to display the data and resulting images and data cubes (using the \greg{} package). \gildas{} is a
large ensemble of software tools maintained by IRAM to handle the IRAM telescopes, from operation to data
taking and processing.  The tailored kernel use by \imager{} differs though minor  but \textbf{required} changes from the original one. 

\imager{} is intended to replace \mapping{} (a simple imaging software available in \gildas{}), but offers
many more capabilities, such as self-calibration, very wide bandwidth processing, large mosaics, polarization,
advanced deconvolution tools (multi-spectral and multi-spatial scales) and a customizable \qom{PIPELINE}
for automatic processing.

This document presents the software organisation and tools to maintain and distribute it.

\section{Code source organization}

The source code is handled in a GIT repository \\
\texttt{https://forge.oasu.u-bordeaux.fr/ums-porea/projets/imager/alma\_imager}

The top directory structure follows the general \gildas{} architecture, with a few custom-made directories added.
\begin{verbatim}
    addons/
    admin/
    Admin-Source/
    contrib/
    kernel/
    legacy/
    RELEASE/
    utilities/
\end{verbatim}

\begin{enumerate}    
\item{\texttt{addons/}} is a directory containing specific handling tools. Currently, it contains code to use JAX for
mathematical rendering of equations in the LaTeX documentations.
\item{\texttt{admin/}} contains the basic administration tools: \script{imager-env.sh} to setup the build environment
and numerous \script{Makefile.xyz} that are used by \script{make} to build the executables.
\item{\texttt{Admin-Source/}} contains generic versions of some of the \script{Makefile.xyz} and shell scripts
that are used to configure their sibblings in \script{../admin/}.  This is made to simplify porting to MacPorts. 
Script \script{substitute.macport.sh} will prepare the adequate scripts in \script{../admin/} for Linux (or 
direct compilation on MacOS), while \script{substitute.macport.sh} will do it for MacPorts distribution.
\item{\texttt{contrib/}} is the root tree where the imager package is located.
\item{\texttt{kernel/}} contains the \textbf{tailored} \gildas{} kernel code. It contains\\
\begin{tabular}{ll}
      kernel/demo/ &    Demonstration scripts and data \\
      kernel/doc/  &    Documentation and help files \\
      kernel/etc/  &   Specific data files (logical names, graphic fonts, color Look-up-Tables, ...) \\
      kernel/include/ &  Modules containing the definition of the Fortran derived types \\
      kernel/lib/   &    Kernel libraries (see Section \ref{sec:kernel} \\
      kernel/main/  &    Main programs (SIC and GreG) \\
      kernel/pro/   &   SIC scripts for programs \\
      kernel/python/ &  SIC -- Python interface support \\
      kernel/tasks/  &   Generic data processing tasks, unused by \imager{} \\
      kernel/vsop87/ &  Earth and Planetary ephemeris, plus telescope specific data files. \\
\end{tabular}
\item{\texttt{RELEASE}} contains copies of the releases, and scripts and documentation to generate
them. 
\item{\texttt{legacy/}} contains legacy code, not developped by \gildas{} : atm (Atmospheric transmission
model, developped by J.Pardo), blas, lapack, slatec, and the fftw3 libraries if needed.
\item{\texttt{utilities}}  contains some tools required to build \gildas{} (perl scripts to handle dependencies,
a simple-minded text to latex converter that follows our conventions for Help text files.
\end{enumerate}
An approximate source size is given below:
\begin{verbatim}
$ cloc kernel/
    1388 text files.
     708 unique files.                                          
     696 files ignored.

github.com/AlDanial/cloc v 1.98  T=1.01 s (703.5 files/s, 280324.3 lines/s)
---------------------------------------------------------------------------------------
Language                             files          blank        comment           code
---------------------------------------------------------------------------------------
Fortran 90                             444             36          66474         157913
C                                       73           5054           3864          24130
TeX                                     19           1275            179           8927
Python                                  24           1032           1888           4598
Windows Module Definition               19             51             98           1969
C/C++ Header                            73            487            318           1905
make                                    47            475            511            563
Text                                     1              8              0            194
Pascal                                   2              0              0             79
Windows Resource File                    4              9              5             76
JSON                                     1              0              0             12
Bourne Shell                             1              0              0              6
---------------------------------------------------------------------------------------
SUM:                                   708           8427          73337         200372
---------------------------------------------------------------------------------------
\end{verbatim}


The \script{contrib/imager/} directory follows a similar structure to the \script{kernel/} one.
\begin{verbatim}
      imager/clic/     Some scripts for the CLIC package
      imager/demo/     Demonstration scripts and data
      imager/doc/      Documentation and help files
      imager/etc/      Specific data files (ALMA configurations, spectral catalog, etc...)
      imager/lib/      Library source files
      imager/main/     Main program IMAGER
      imager/pro/      Scripts that support some of the complex commands
      imager/pymod/    casagildas() python script
      imager/libview/  Viewer library code
      imager/viewer/   Main program VIEWER
\end{verbatim}
An approximate size is given below:
\begin{verbatim} 
$ cloc contrib
     486 text files.
     207 unique files.                                          
     309 files ignored.

github.com/AlDanial/cloc v 1.98  T=0.37 s (561.4 files/s, 368333.0 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Fortran 90                     160            613          37068          87087
TeX                             28           1021           1049           7883
Python                           1             52            162            443
make                            11            105            122            139
Text                             1              0              0             28
C                                5             16             12             16
Bourne Shell                     1              0              2              3
-------------------------------------------------------------------------------
SUM:                           207           1807          38415          95599
-------------------------------------------------------------------------------
\end{verbatim}

As seen above, most of the code is Fortran-90, using features from the 2008 standard.
Documentation uses nroff and LaTeX. SIC has a Python binding, allowing it to
call Python (or be called from Python) and offering transparent access to the
recognized SIC variables as Python objects. 

\section{Modified GILDAS Kernel}
\label{sec:kernel}

The kernel differs from the GILDAS in version in several ways, with one major
difference, and several minor (but still required) ones.
\begin{itemize}
 \item{\textbf{Major: }} A modified definition of the \texttt{gildas} derived type.
In addition to the standard sub-types, it includes a \texttt{mosaic\_header} derived type
that contains information to handle mosaics: number of fields, and for each field,
pointing center, phase center, number of visibilities, plus pixel offsets and fractional
phase offsets for map processing.
  \item{Easy:} \texttt{kernel/vsop87/etc} Astro related data moved here to avoid
  any reference to the \texttt{packages} tree.  
  \item{Easy:} \lang{GREG3} language must be avoided. This was done by cloning code from the 
  \texttt{kernel/lib/greg/greg-package.f90} into \texttt{contrib/imager/lib/package.f90} 
  and removing the unneeded line in defining a new \texttt{greglib-pack} SIC package.
  \item{Minor:} \qomm{HEADER}{/EXTREMA} can work on internal Images, not only
  on files, and on ReadOnly files also.
  \item{Minor:} Messaging facility allows better handling of colors (see \qomm{MESSAGE}{/COLOR}).
  \item{Minor:} More tolerant read of UVFITS files to circumvent a bug in Casa
  \item{Minor:} Better message on {\^{}}C at various levels
  \item{Minor:} Improved \qomm{SIC}{FIND}, \qomm{SIC}{WHICH} commands 
  \item{Minor:} \qomm{EXIT}{ABORT} command to end up (nearly) infinite loops that may happen 
  when commands call faulty scripts. 
  \item{Minor:} Small changes in \greg{}: \qom{LEVELS} command to remember level values and
  suppress verbosity.
  \item{Minor:} A patch for an unsolved, unclear bug with \qom{LUT} in STATIC mode in GTV$\backslash$ language.
 \item{Feature+Bug:} In WCS support, extend the \texttt{abs\_to\_rel} and \texttt{rel\_to\_abs} routines
 to handle the null transformation case (for generality), and correct a bug in Sexagesimal handling.
\end{itemize}  
These small changes require some care to follow up GILDAS kernel evolution made at IRAM.

\section{Compilation and Maintenance}

\subsection{Compilation}
The code is reconstructed using \texttt{make}. It has a number of pre-requisite.
\begin{itemize}\itemsep 0pt
 \item  a C compiler (clang or gcc)
 \item  a version of gfortran supporting Fortran 2008 main features
 \item  a recent Python (version 3 only)
 \item  GTK version 2.  This is one of the oldest dependencies, that may require a change in the future.
 \item  basic Linux utilities, such as nroff / groff 
 \item  a LaTeX installation for processing the documentations
 \item  a pdflatex converter
\end{itemize}
The compilation environment is defined by executing the imager-env.sh script:
\script{\textdollar{} source admin/imager-env.sh}. Then

\script{\textdollar{} make} builds the code

\script{\textdollar{} make doc} builds the documentation

\script{\textdollar{} make install} copies the binaries, help files and documentation to an executable
area.
\vspace{0.1cm}
In addition, the \href{https://forddocs.readthedocs.io/en/stable/}{ford} tool 
can be used to generate an html documentation of the \imager{} code,
from the \script{contrib/imager} directory, in two steps:
\begin{verbatim}
  $ source copy_to_src.sh
  $ ford my_project.md
\end{verbatim}
Documentation is then accessible by \texttt{open FORD/index.html} 
\footnote{
Normally, \texttt{my\_project.md} should be configured
to directly access the \script{imager/lib} directory where source files
are located, but I could not make it work, so the intermediate script
is there to make a copy of the relevant sources in the default \texttt{src}
directory for \texttt{ford}.
}.

\subsection{Maintenance}
The code is under version control using \qom{git}. 

In addition to this tool, the coder
must keep up to date the version number in the Fortran source files. The \imager{} commands
are organized in so-called \textbf{Languages} that group in a logical way related commands.
In particular, command from one language may call commands from a more basic one, without
leading to recursive programming. A version number is (manually) kept for each language.
Version numbers are typically changed either upon a global (public) release fo \imager{},
or when a new functionality is implemented (e.g. a new command or option, or a new
control variable), while bug corrections or minor improvements are handled by a revision
sub-number. 

Decision on \qom{git} commit, branches, and push to the main repository is at the
discretion of the coder.  There is currently no specific branch per public release:
this may be a good idea to implement.

\subsection{Documentation and Help files}
The documentation is handled like the code. HELP files are built with the standard
\texttt{make}, while the documentation is build using\texttt{make doc}. 
The maintainer is responsible to update the internal help and user documentation 
whenever functionalities change. 

\subsubsection{Internal HELP files}
The internal \qom{HELP} files are generated from \texttt{.nroff} source files, which must respect
simple conventions because these files are also converted to \texttt{.tex} files by our
\script{nrtex} program for inclusion in the documentation.

The overall format is set by a 4 line trailer
 \begin{verbatim}
    .ec _         ! Escape character definition instead of the default 
    .ll 80        ! Line length 80 chars
    .ad b         ! Adjust both margins
    .in 4         ! Default indent 4 chars
 \end{verbatim}
and the conventions are the following:
\begin{itemize}
 \item{Allowed nroff markers:} only \texttt{.ti, .br, .nf, .fi, .so} and .\textbackslash{} are allowed, except in the
 trailer given above.
 \item{.ti -4} must be used before any sectioning of the Help text.
 \item{.ti +4} should be used after the section name has been given. 
 \item{NO number} must ever appear as first character on a line.
\end{itemize}

There must be one \texttt{.nroff} file per language, named  \texttt{imager-help-language.nroff} where
\texttt{language} is the actual Language name. It can use other \texttt{.nroff} files through the use
of \texttt{.so} directive. 

This per-language file must begin by the trailer, immediately followed by
\begin{verbatim}
.ti -4 
1 Language
One line description of language purpose
.nf
  COMMAND      : Description
  OTHERCOMM    : Description
.fi
\end{verbatim}
with a one line description of every command.

Each command must be then described, starting with the command syntax,
the a general description
\begin{verbatim}
.ti -4 
1 COMMAND
.ti +4
  [Language\]COMMAND [Args...] [/OPTION [Args...]]

Description of command.
\end{verbatim}
Here brackets are used to indicate optional arguments and options. 

Similarly, each option of a given command must then be described after the
command, using
\begin{verbatim}
.ti -4 
2 /OPTION
.ti +4
  [Language\]COMMAND [Args...] /OPTION [Args...]

Description of Option behaviour.
\end{verbatim}
and so on for all recognized options.

In addition, keywords (arguments that must take some specific names) should
be described like options, with their names in upper case.  This keyword
descriptions can be grouped after a \texttt{Keyword:} sequence, as below:
\begin{verbatim}
.ti -4 
2 Keywords:
.ti +4
  [Language\]COMMAND Keyword [Args...] [/OPTION [Args...]]
  
Keyword can be any of ONE, TWO, THREE
.ti -4
2 ONE
.ti +4 
  [Language\]COMMAND ONE  [Args...] [/OPTION [Args...]]

Description of behaviour with Keyword ONE
\end{verbatim}
and so on for all keywords.

Similarly, control variables (program defined or user defined variables that are
intrepreted by the command code to modify its behaviours) can (or rather should)
be defined in a new group started by the \texttt{Variables:} sequence:
\begin{verbatim}
.ti -4 
2 Variables:
.ti +4
  [Language\]COMMAND [Args...] [/OPTION [Args...]]
  
List of control variables (possibly in a .nf .fi  block)
.ti -4
2 VARONE

Description of behaviour of variable VARONE
\end{verbatim}
and so on for all control variables. It is recommended to specify the type and
dimensions of the variable in this help section.

In the same way, output variables could be described in a \texttt{Results:} group.
Commands, options, keywords and variables should not be case sensitive: they must
be given in uppercase in \texttt{.nroff} file. Any other information can be added 
as a subtopic. This should normally be given in with a mixed case subtopic.
For example, the history of the command could be described in a (level 2) subtopic
\texttt{History}, and the algorithm in \texttt{Algorithm}. 


Because groups are ended by new groups or new commands, subtopic groups should be
listed after any other normal subtopic.

Each \texttt{imager-help-language.nroff} file should end with
\begin{verbatim}
 .ti -4
 1 ENDOFHELP 
\end{verbatim}
a convention that allows proper termination of the help of the last command.

\subsubsection{PDF and HTML version}
PDF and HTML documentation use the same source files  in LaTeX format, converted to PDF and
HTML using \texttt{pdflatex} and \texttt{latex2html} respectively. Both use color coding.
To ensure that a proper \texttt{HTML} version can be generated, it is recommended
to avoid using too sophisticated LaTeX constructs. Images  included through
\textbackslash{}\texttt{includegraphics} should be in PNG format.

Some specific commands are re-defined in \texttt{HTML} mode, to provide better
formatting (and ultimately may be add some IA-related information). 

In addition to the \texttt{imager.pdf} file, \texttt{imager-bugs.pdf}


\subsection{Testing}
\imager{} comes with a number of demonstration scripts. These scripts can be used
interactively, but also have a more ``batch'' like operation, with no user interaction
that can be used to verify that the code is performing as expected. In particular 
\begin{verbatim}
    IMAGER> @ gag_demo:verify *
\end{verbatim}
executes in sequence all the demonstrations in stand-alone mode. If it does not go
to a successfull end, it means some functionality of \imager{} is broken, and must be
fixed!

\subsection{Debugging}
\imager{} being a large code,  debugging is not so straightforward.  There are
a number of tools, for example controlling the number of messages dispatched by the
messaging facility. 

Commands may also react to a \sicvar{DEBUG\_COM} variable where \qom{COM} is the
command name. However, no generic mechanism is available yet. 

A new policy is needed. We are currently limited by the number of message types
provided by SIC. It may be extended (which means an even larger deviation from
the original kernel), and/or we may have to generalize the \sicvar{DEBUG\_COM} mechanism.


\section{Distribution}

Distribution is currently handled in 3 different ways.
\begin{itemize}
 \item{\textbf{Apptainer:}} An apptainer binary for Linux is built from source code, and
 made accessible through the Web site.
 
 \item{\textbf{MacPorts}}  \imager{} is also available on Macs through MacPorts:\\
 \texttt{\$ sudo port install imager}
 
 \item{\textbf{Source Code}}  Source code, and a simple compilation-installation script
 is available on the Web.  The script \script{get-and-install.sh}, once downloaded
 will download the source code and perform the compilation. This requires the
 pre-requisite (C compiler, gfortran, Python, gtk2) to be met.  On Mac, these 
 requirements are satisfied if the user has already installed gildas and/or imager 
 through MacPorts. 
 
\end{itemize}
The two first methods are currently handled by the OASU, typically 2 to 3 times a year,
upon request (well in advance...).  We  only have limited information about the details
of this process. However, while the Apptainer version is generated without any issue, the
MacPorts version sometimes (often...) requires tight interactions because of unforeseen 
changes in the way MacPorts works. 

On the contrary, the Source Code version is totally under the developper control. It contains
the source code for the last binary versions (Apptainer \& MacPort) as \texttt{imager-last.tgz},
but also the current best stage of the next version, \texttt{imager-next.tgz}.

As mentionned above, there is currently no specific git branch per public release
(for example, the latest branch to be published is branch "ford", the next is "newgio").

To make a release, a number of (error-prone, unfortunately) manual steps is currently
required.
\begin{enumerate}
\item Ensure the versions of IMAGER are up-to-dates \script{contrib/imager/lib/initclean.f90}
\item Ensure the documentation matches \script{contrib/imager/doc}
\item Update  the \script{VERSION} file (in the top directory). 
    Logout and re-login to ensure update of the environment variables by
    re-executing the \script{source admin/imager-env.sh} script.
\item in \script{in kernel/etc}
\begin{verbatim}
    make clean
    make
    make install
\end{verbatim}
\item in \script{contrib/imager}
\begin{verbatim}
    make clean
    make
    make install
\end{verbatim}
\item Run the \imager{}  test suite.\\
  \texttt{\textdollar{} imager @ gag\_demo:verify *} \\
  if not successful, do not proceed !...
\item Go back to the imager root directory, commit your changes, and 
  push on the OASU Forge \\
  \texttt{\textdollar{} git commit . \\
  \textdollar{} git push}
\item Move to \script{RELEASE} directory
\item Use the \script{release.sh} script\\ 
  \texttt{\textdollar{} source release.sh  mmmYY [Name [Branch]]} \\
  where \texttt{mmm} is the month designation (e.g. apr) and \texttt{YY} the year designation
  (e.g. 25).     This will:\\
  - Create the \script{imager-mmmYY.tgz} file that contains everything to rebuild IMAGER.\\
  - link the \script{imager-\$Name.tgz} file to this new file\\
  - upload it to the OASU shared area\\ 
  \texttt{Branch} is the Git repository branch from which the version should be created.
  It was \texttt{sgdev} prior to Apr 25, \texttt{ford} in Apr-May 2025, and now
  is \texttt{newgio} by default.   
\item Push the documentation on IRIS: Move to \script{contrib/imager/doc} directory and
  execute the following commands:
\begin{verbatim}
  $ make doc
  $ make html
  $ source toiris.sh
\end{verbatim}
\end{enumerate}


Steps 4-5 can be replaced by \texttt{make clean; make} which takes a little longer
but re-compiles the whole code, so ensures an up-to-date version of all parts.

A manual step (performed by Emmanuel di Folco) is required to upload the documentation
to the Web site after step 10.



\end{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
