%
% To start the document, use
%  \chapter{...}
% For lover level, sections use
%  \section{...}
%  \subsection{...}
%
\chapter{The art of developing ARTS}
 \label{sec:development}

%
% Document history, format:
%  \starthistory
%    date1 & text .... \\
%    date2 & text .... \\
%    ....
%  \stophistory
%
\starthistory
  020425 & Stefan Buehler: Put this part back in the AUG. Updated.\\
  000728 & Stefan Buehler: Added stuff about build system and howto cut a release. \\
  000615 & Created by Stefan Buehler.\\
\stophistory

%
% Symbol table, format:
%  \startsymbols
%    ... & \shortcode{...} & text ... \\
%    ... & \shortcode{...} & text ... \\
%    ....
%  \stopsymbols
%
%

%
% Introduction
%
The aim of this section is to describe how the program is organized and to give
detailed instructions how to make extensions. That means, it is addressed to the
ARTS developers, not the users. If you only want to use ARTS, you should not
need to read it. \textbf{But if you want to make changes or additions, you
  should definitely read this carefully, since it can save you a lot of work to
  understand how things are organized.}

\section{Organization}
%====================
\label{sec:development:org}
 
ARTS is written in C++ and uses the cross-platform, open-source build system
CMake (\url{http://www.cmake.org/}). It is organized in a similar manner as most
GNU packages. The top-level ARTS directory is either called \shortcode{arts} or
\shortcode{arts-x.y}, where x.y is the release number. It contains various
sub-directories, notably \shortcode{doc} for documentation, \shortcode{src} for
the C++ source code, The document that you are reading right now, the ARTS
Developer Guide, is located in \shortcode{doc/uguide}.

There are two different versions of the ARTS package: The development version
and the end-user version. Both contain the complete source code, the only
difference is that the developers version is where active development takes
place.

The end-user version contains everything that you need in order to compile and
install ARTS in a fairly automatic manner. The only thing you should need is an
ANSI-C++ compiler, and the CMake utility. Please see files
\fileindex{arts/README} and \fileindex{arts/INSTALL} for installation
instructions. We are aiming to support recent version of the GNU and clang C++
compilers.

\section{The ARTS build system}
%============================

As mentioned above, CMake is used to build the ARTS package. A good introduction
to the CMake system can be found in:
\begin{quote}
  \url{http://www.cmake.org/cmake/project/about.html}
\end{quote}


\subsection{Configure options}
%========================================

For development, it is recommended to build ARTS using the
\shortcode{RelWithDebInfo} configuration (see below), which aims to provide a
reasonable trade-off between debugging capability and performance. To use ARTS
in production, however, it is important to perform a release build, which is
therefore set as the default configuration.

\begin{description}
\item[\shortcode{-DCMAKE\_BUILD\_TYPE=RelWithDebInfo}:] This is the build option
  that should be used for development, as it will make it easier to track down
  errors in the code. It does, however, not disable all compiler optimization,
  so as to still provide reasonable performance.
\item[\shortcode{-DCMAKE\_BUILD\_TYPE=Release}:] Removes '-g' from
the compiler flags and includes \shortcode{\#define NDEBUG 1} in
\fileindex{config.h}. The central switch to turn off all debugging
features (index range checking for vectors, the trace facility,
assertions,...).
\item[\shortcode{-DCMAKE\_BUILD\_TYPE=Debug}:] This switch turns off all
  optimizations. This should only be used if the \shortcode{RelWithDebInfo}
  configuration makes debugging a given problem difficult.
\item[\shortcode{-DNO\_OPENMP=1}:] 
Disables the generation of multi-threaded code. CMake tries to detect if the compiler supports OpenMP and enables it by default.

\end{description}


\section{Coding conventions}
%===================
\label{sec:development:conv}

With the aim of improving quality and consistency of the code, all new code that
is added to ARTS should adhere to naming and formatting conventions from
Google's C++ programming guidelines
(\url{https://google.github.io/styleguide/cppguide.html#Formatting}). Adhering
to a well-defined coding style will make it much easier for your fellow ARTS
developers to understand and work with your code. A brief summary of the most
important programming style and formatting conventions is given below.


\subsection{Naming conventions}

Naming things is one of the two hard problems in computer science. Certainly,
there is no single best way to do it and even with the best names code can still
be bad. Yet still, the consistently naming of objects in your code will make it
much easier for other developers to read and understand your code.

In general, the use descriptive names in all your code is recommended.
Try to avoid abbreviations except when they are very common. Giving proper
names to objects increases the readability of the code and decreases the need
for explanatory comments.

\subsubsection{Variables}
Variable names should use lower-case letters. Words should be separated using
underscores:
  \begin{code}
  Index element_index = 0;
  Numeric t_surface = 0.0; // common abbreviation
  \end{code}

\subsubsection{Classes, structs and type names}
Classes, structs and user-defined type names should start with a capital letter
and use camel case to separate different words.
  \begin{code}
  class CovarianceMatrix {};
  \end{code}

\subsubsection{Class member variables}

Variables that are defined as data members of classes should be suffixed with
a underscore (\shortcode{\_}). This convention has the important advantage
that it allows inferring the scope of variables used inside definitions of
member functions.

  \begin{code}
  class CovarianceMatrix {
   private:
    Numeric *elements_;
  };
  \end{code}

\subsubsection{Constant names}
Names of constants should be prefixed with a lower-case k. Following words
should use camel case starting with a capital letter.
  \begin{code}
  const Numeric kAlmostPi = 3.0;
  \end{code}

\subsubsection{Function names}
Function names should start with a capital letter and words should
be separated using camel case.

  \begin{code}
  void InterpolateTo(const Vector &x_new) {
    ...
  }
  \end{code}

\subsection{Formatting}

The formatting, i.e. the layout of your code, should adhere strictly to the
Google guidelines. Google's indentation style is also supported by the
clang-format tool, which provides functionality for automatic formatting. A
format file for clang-format is provided in ARTS' top-level directory. Most
development environments provide support for clang-format, which makes following
these guidelines extremely easy.

\begin{itemize}
  \item Line length of 80 characters
  \item No tabs, only spaces
  \item 2 spaces per indentation level
  \item Opening brace \texttt{\{} of function/class/struct definition and if/for blocks on the same line
  \item No spaces on the inner side of the parentheses of the conditional
    expressions of if statements.
\end{itemize}

\subsection{ARTS-specific rules}

\subsubsection{Numeric types}

Never use \shortcode{float} or \shortcode{double} explicitly, use the type
\typeindex{Numeric} instead. This is set by CMake (to \shortcode{double} by
default). In the same way, use \typeindex{Index} for all integers. It can take
on positive or negative values and defaults to \shortcode{long}. To change the
default types, run \shortcode{cmake} with the options \shortcode{-DINDEX=long}
or \shortcode{-DNUMERIC=double}:

\begin{code}
cmake -DINDEX=int --DNUMERIC=float ..
\end{code}

Note that changing the numeric type to a lower precision type than
double might have unforseen impacts on the numerical precision and could
lead to wrong results. In a similar way, reducing the index type can
make it impossible to handle larger Vectors, Matrices or Tensors. The
maximum range of the index type determines the maximum number of
elements the container types can handle.

\subsection{Container types} Use \builtindoc{Vector} and
\builtindoc{Matrix} for mathematical vectors and matrices (with elements
of type \builtindoc{Numeric}). Use \shortcode{Array<something>} to
create an array of \shortcode{something}s.
Commonly used Arrays have been predefined, they have names like
\builtindoc{ArrayOfString}, \builtindoc{ArrayOfMatrix}, and so forth.

\subsection{Terminology}
Calculations are carried out in the so called workspace (WS), on
workspace variables (WSVs). A WSV is for example the variable
containing the absorption coefficients. The WSVs are manipulated by 
workspace methods (WSMs). The WSMs to use are specified in the
controlfile in the same order in which they will be
executed. 

\subsection{Global variables}
   Are not visible by default. To use them you have to declare them
   like this:
   \begin{quote}
   \shortcode{extern const Numeric PI;}
   \end{quote}
   which will make the global constant PI=3.14... available. Other important globals are:

   \begin{quote}
   \begin{tabular}{ll}
   \shortcode{full\_name}&         Full name of the program, including version.\\
   \shortcode{parameters}&        All command line parameters.\\
   \shortcode{basename}&          Used to construct output file names.\\
   \shortcode{out\_path}&          Output path.\\
   \shortcode{messages}&          Controls the verbosity level.\\
   \shortcode{wsv\_data}&          WSV lookup data.\\
   \shortcode{wsv\_group\_names}&   Lookup table for the names of \emph{types} of WSVs.\\
   \shortcode{WsvMap}&            The map associated with \shortcode{wsv\_data}. \\
   \shortcode{md\_data}&           WSM lookup data.\\
   \shortcode{MdMap}&             The map associated with \shortcode{md\_data}. \\
   \shortcode{workspace}&         The workspace itself.\\
   \shortcode{species\_data}&      Lookup information for spectroscopic species.\\
   \shortcode{SpeciesMap}&        The map associated with \shortcode{species\_data}.
   \end{tabular}
   \end{quote}
   The only exception from this rule are the output streams \shortcode{out0} to
   \shortcode{out3}, which are visible by default.

\subsection{Files}
Always use the \shortcode{open\_output\_file} and \shortcode{open\_input\_file}
functions to open files. This switches on exceptions, so that any
error occurring later on with this file will result in an
exception. (Currently not really implemented in the GNU compiler,
but please use it anyway.)

\subsection{Version numbers} 
The package version number is set in the \fileindex{VERSION} file in the top
level ARTS directory. It will be incremented by the ARTS maintainers when new
features or bug fixes have been added to ARTS, not on every commit. Never
change this number when working in your own branch. The major and/or minor
version number will be incremented on public releases. The micro version
indicates the addition of new features during development or bugfixes for
stable releases.

\subsection{Header files} 
The global header file \fileindex{arts.h} \emph{must} be included by every
file. Apart from that you have to see yourself what header files you
need. If you use functions from the C or C++ standard library, you
have to also include the appropriate header file.

\subsection{Documentation}
Doxygen is used to generate automatic source code documentation. See
\begin{quote}
  \url{http://www.stack.nl/\~dimitri/doxygen/}
\end{quote}
for information. There is a complete User manual there. At the moment
we only generate the output as HTML, although latex, man-page, and rtf
format is also possible. The HTML version is particularly useful for
source code browsing, since it includes the complete source code! You
should add Doxygen headers to the following:

\begin{enumerate}
\item Files
\item Classes (Including all private and public members)
\item Functions
\item Global Variables
\end{enumerate}

The documentation headers are comment blocks that look like the
examples below. They should be put above the \emph{definition} of a
function, i.e., in the \shortcode{.cc} file.  Some functions are defined in
the \shortcode{.h} file (e.g., inline member functions). In that case the
comment can be put in the \shortcode{.h} file.

There is an Emacs package (Doxymacs) that makes the insertion of
documentation headers particularly easy. You can find documentation of
this on the Doxymacs webpage: \url{http://doxymacs.sourceforge.net/}.
To use it for ARTS (provided you have it), put the following in your
Emacs initialization file:

\begin{code}
(require 'doxymacs)

(setq doxymacs-doxygen-style "Qt")

(defun my-doxymacs-font-lock-hook ()
  (if (or (eq major-mode 'c-mode) (eq major-mode 'c++-mode))
      (progn
        (doxymacs-font-lock)
        (doxymacs-mode))))

(add-hook 'font-lock-mode-hook 'my-doxymacs-font-lock-hook)

(setq doxymacs-doxygen-root "../doc/doxygen/html/")
(setq doxymacs-doxygen-tags "../doc/doxygen/arts.tag")
\end{code}

The only really important lines are the first two, where the second
line is the one selecting the style of documentation. The next block
just turns on syntax highlighting for the Doxygen headers, which looks
nice. The last two lines are needed if you want to use the tag lookup
features (see Doxymacs documentation if you want to find out what this
is).  The package allows you to automatically insert headers. The
standard key-bindings are:
\begin{quote}
\begin{tabularx}{.8\hsize}{@{}lX}
\texttt{C-c d ?} & look up documentation for the symbol under the point.\\
\texttt{C-c d r} & rescan your Doxygen tags file.\\
\texttt{C-c d f} & insert a Doxygen comment for the next function.\\
\texttt{C-c d i} & insert a Doxygen comment for the current file.\\
\texttt{C-c d ;} & insert a Doxygen comment for a member variable on the current line (like M-;).\\
\texttt{C-c d m} & insert a blank multi-line Doxygen comment.\\
\texttt{C-c d s} & insert a blank single-line Doxygen comment.\\
\texttt{C-c d @} & insert grouping comments around the current region.\\
\end{tabularx}
\end{quote}
You can call the macros also by name, e.g., \shortcode{doxymacs-insert-file-comment}.

\subsubsection{File comment}

Generated by \shortcode{doxymacs-insert-file-comment}.

\begin{code}
/*!
\file   dummy.cc
\author John Doe <john.doe (at) example.com>
\date   2011-03-02

\brief  A dummy file.

 This file has no purpose at all,
 it just servers as an example... 
*/
\end{code}

\subsubsection{Function comment}

Generated by \shortcode{doxymacs-insert-function-comment}. If
arguments are modified by the function you should add `[out]' after
the \shortcode{\char`\\ param} command, just like for the parameter
\shortcode{a} in the example below. If a parameter is both input and
output, you should say `[in,out]'. Parameters that are passed by
value or not modified inside the function should carry an `[in]'. The
documentation for each parameter should start with a capital letter and
end with a period, like in the example below.

Author and date tags are not inserted by default, since they would be
overkill if you have many small functions. However, you should include
them for important functions. 

\begin{code}
  //! A dummy function.
  /*! 
  This function has no purpose at all,
  it just serves as an example... 

  \param[out]     a This parameter is initialized by the
  function.
  \param[in,out]  b This parameter is modified by the function.
  \param[in]      c This parameter used but not changed by the function.

  \return   Dummy value computed from a and b.         
  */
  int dummy(int& a, int& b, int c);
\end{code}

\subsubsection{Generic multi-line comment}

Generated by \shortcode{doxymacs-insert-blank-multiline-comment}.

\begin{code}
  //! A dummy comment.
  /*! 
  Some more elaborate description about this variable, 
  class, or whatever. 
  */
\end{code}

\subsubsection{Generic single-line comment}

Generated by \shortcode{doxymacs-insert-blank-singleline-comment}.

\begin{code}
  //! Short comment here.
\end{code}


\section{Extending ARTS}
%======================
\label{sec:development:extending}

\subsection{How to add a workspace variable}
%---------------------------------------

You should read Section \ref{sec:agendas:wsvs} to understand what workspace
variables are. Here is just the practical description how a new
variable can be added.

\begin{enumerate}
\item Create a record entry in file \fileindex{workspace.cc}. (Just add
  another one of the \shortcode{wsv\_data.push\_back} blocks.) Take the
  already existing entries as templates. The ARTS concept works best
  if WSVs are only of a rather limited number of different types, so
  that generic WSMs can be used extensively, for example for IO.
  
  The name must be \emph{exactly} like you use it in the source code,
  because this is used to generate interface functions.
  
  Make sure that the documentation string you give explains the
  variable and its purpose well. \textbf{In particular, state the
    dimensions (in the case of matrices) and the units!} This string
  is used for the online documentation. Please take some time to write
  it carefully. Use the template at the beginning of function
  \shortcode{define\_wsv\_data()} in file \shortcode{workspace.cc} as a
  guideline. 

\item That's it!
\end{enumerate}


\subsection{How to add a workspace variable group}
%--------------------------------------------

You should read Section \ref{sec:agendas:wsvs} to understand what workspace
variable groups are. Here is just the practical description how a new
group can be added.

\begin{enumerate}
\item Add a \shortcode{wsv\_group\_names.push\_back("your\_type")} function to
  the function \shortcode{define\_wsv\_group\_names()} in \fileindex{groups.cc}.
  The name must be \emph{exactly} like you use it in the source code,
  because this is used to generate interface functions.
\item XML reading/writing routines are mandatory for each workspace variable
  group. Two steps are necessary to add xml support for the new group:
  \begin{enumerate}
  \item Implement an \shortcode{xml\_read\_from\_stream}
    and \shortcode{xml\_write\_to\_stream} function. Depending
    on the type of the group the implementation goes into one
    of the three files \fileindex{xml\_io\_basic\_types.cc},
    \fileindex{xml\_io\_compound\_types.cc}, or
    \fileindex{xml\_io\_array\_types.cc}. Basic types are for example Index
    or Numeric. Compound types are structures and classes. And array types are
    arrays of basic or compound types. Also add the function declaration in the
    corresponding \shortcode{.h} file.
  \item Add an explicit instantiation for
    \shortcode{xml\_read\_from\_file<GROUP>} and
    \shortcode{xml\_write\_to\_file<GROUP>} to \fileindex{xml\_io\_instantiation.h}.
  \end{enumerate}
\item If your new group does not implement the output operator
  (\shortcode{operator<<}), you have to add an explicit implementation
  of the \builtindoc{Print} function in \fileindex{m\_general.h} and
  \fileindex{m\_general.cc}.
\item That's it! (But as stated above, use this feature wisely)
\end{enumerate}



\subsection{How to add a workspace method}
%-------------------------------------
\label{sec:development:extending:wsm}

You should read Section \ref{sec:agendas:wsms} to understand what workspace
methods are. Here is just the practical description how a new
method can be added.

\begin{enumerate}
\item Create an entry in the function \funcindex{define\_md\_data} in file
  \fileindex{methods.cc}.  (Make a copy of an existing entry (one of the
  \shortcode{md\_data.push\_back(...)} blocks) and edit it to fit your new
  method.) Don't forget the documentation string! Please refer to the
  example at the beginning of the file to see how to format it.
\item Run:
  \shortcode{make}.
\item Look in \fileindex{auto\_md.h}. There is a new function prototype
  \begin{quote}
    \shortcode{void <YourNewMethod>(...)}
  \end{quote}
\item Add your function to one of the \shortcode{.cc} files which contain method
  functions. Such files must have names starting with \shortcode{m\_}. (See
  separate HowTo if you want to create a new source file.) The header
  of your function must be compatible with the prototype in \shortcode{auto\_md.h}.
\item Check that everything looks nice by running 
  \begin{quote}
    \shortcode{arts -d YourNewMethod}
  \end{quote}
  If necessary, change the documentation string.

\item Thats it!
\end{enumerate}


\subsection{How to add a source code file}
%---------------------------------------
\begin{enumerate}
\item Create your file. Names of files containing workspace methods should
  start with \shortcode{m\_}.
\item You have to register your file in the file
  \fileindex{src/CMakeLists.txt}. This file states which source files
  are needed for arts. In the usual case, you just have to add your
  \shortcode{.cc} file to the list of source files of the artscore
  library. Header files are not added to this list.
\item Go to \shortcode{src} and run: \shortcode{git add <my\_file>} to
  make your file known to git.
\end{enumerate}


\subsection{How to add a test case}
%---------------------------------------
\begin{enumerate}
\item Tests are located in subdirectories in the \fileindex{controlfiles}
  folder. Instrument specific test cases are in the
  \fileindex{controlfiles/instruments} folder, all other cases are
  located in the \fileindex{controlfiles/artscomponents} folder. Create
  a new subdirectory in the appropriate folder. If your test is closely
  related to another test case you can skip this step and instead add it
  to one of the existing subdirectories.
\item Create your own test controlfile. The filename should start
  with \fileindex{Test} followed by the name
  of the subdirectory it is located in, e.g.
  \fileindex{controlfiles/artscomponents/doit/TestDOIT.arts}.

  If the subdirectory contains more than one test controlfile,
  append a short descriptive text to the end of the filename like
  \fileindex{controlfiles/artscomponents/ montecarlo/TestMonteCarloGaussian.arts}.
\item Copy all required input files into the subdirectory. Input data that is
  shared among several test cases should be placed in
  \fileindex{controlfiles/testdata}.
\item Add an entry for your test case in
  \fileindex{controlfiles/CMakeLists.txt}.
\end{enumerate}


\subsection{How to add a particle size distribution}
%---------------------------------------
\begin{enumerate}
\item In \shortcode{cloudbox.cc}, add a non-WS method
  \shortcode{pnd\_fieldPSDNAME}, where \shortcode{PSDNAME} stands for the short
  name or name tag of the new particle size distribution (PSD) parametrization.
  This will be the method called by
  \builtindoc{pnd\_fieldCalcFromscat\_speciesFields}, the WSM that converts the
  particle-related atmospheric fields (typically hydrometeor fields like cloud ice
  mass content, rain rate, etc.) to the internally used \builtindoc{pnd\_field}.
\item Update the built-in documentation of
  \builtindoc{pnd\_fieldCalcFromscat\_speciesFields} in \shortcode{methods.cc}.
  Particularly, add an entry in the table summarizing the implemented PSDs.
\item In \shortcode{m\_cloudbox.cc}, add a WSM \shortcode{dNdD\_PSDNAME} as a
  wrapper to the low-level calculation of the number density size distribution
  function $\mathrm{d}N/\mathrm{d}D$. Also add definition and documentation of
  the WSM to \shortcode{methods.cc} (see
  Section~\ref{sec:development:extending:wsm} for details).
\end{enumerate}

\section{Version control}
%======================
\label{sec:development:cvs}

ARTS uses git for version control. The central or \textit{upstream} repository
is hosted on github (\url{https://github.com/atmtools/arts}). Contributions to
ARTS are handled via pull requests on github. This is the de-facto standard
workflow for open source development, so the time required to get familiar with
it is certainly a worthy investment. Contributing a new feature or bug-fix to
ARTS thus involves the following steps:

\begin{enumerate}
\item Fork the upstream repository
\item Clone the ARTS fork from \textit{your github account} onto your local
  workstation
\item Implement your changes
\item Commit and push your changes to your ARTS fork
\item Issue a pull request to merge your ARTS fork with the central repository
\item One of the ARTS core developers will review your code and help with the
  final integration
\end{enumerate}


The required steps are described below in more detail. Note that all of these
steps are so common to modern software development, that it is very easy to find
tutorials and manuals online that described them in more detail.


\subsection{Forking the central repository}

The forking of the central repository is through the web interface of
\url{github.com}. This will create a copy of the central repository in
\textit{your account}. This repository is your personal version of the ARTS
repository. You can change all you want here without breaking ARTS for anyone
else.

\subsection{Clone your ARTS fork}

So far your fork of ARTS exists only in your github account somewhere in
the \textit{cloud}. To really work with the code, you need to obtain a copy
of the code on your local workstation. This is done by \textit{cloning} the
repository from your account:
\begin{code}
  git clone https://github.com/<your_username>/arts
\end{code}

where \shortcode{your\_username} is the name of your github account. The
important point to note here is that you did not clone the central ARTS
repository from \url{github.com/atmtools} but the one from your account. As
explained above, this is your personal version of the ARTS repository
and you can do anything you want with it.

\subsection{Update your fork}

One consequences of the forking of the central ARTS repository is that the
fork in your own github account will not automatically be updated when
changes are made to the upstream repository. Before checking in your changes
into your repository it is therefore important that you update your repository
with the most recent changes made to the upstream repository. For this two
steps are required:

\begin{enumerate}
\item Register the upstream repository as remote repository for your local clone of your ARTS fork:
  \begin{code}
    git remote --add upstream https://github.com/atmtools/arts
  \end{code}
\item Rebase your code onto the newest changes from the upstream repository:
  \begin{code}
    git fetch upstream master
    git rebase -i upstream/master
  \end{code}
\end{enumerate}

The first step here needs to be performed only the first time you are going
through this process. Afterwards only the second step is required. A detailed
description of the rebase step can be found at \url{https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase}.

\subsection{Commit and push your changes}

After implementing your changes, commit and push them to your ARTS fork. The
changes are now publicly available from your github account. Note that at this
point you can already share your code with others or across different machines.
It has, however, not yet been integrated into the upstream repository. That
means your changes are not yet affecting regular users of the ARTS development
version.

\subsection{Issuing a pull request}

Once your changes have been pushed to the ARTS repository in your github
account, you can issue a pull request. This is done most easily through the
github web interface. This will notify the ARTS core developers that you want to
integrate your changes into the upstream repository. On issuing your pull
request, the ARTS test-suite will be run on your code. If all tests pass, an
ARTS core developer will review your code and finally merge it into the central
repository.

\section{Debugging (use of assert)}
%================================
\label{sec:development:assert}
 
The idea behind assert is simple. Suppose that at a certain point in
your code, you expect two variables to be equal.  If this expectation
is a precondition that must be satisfied in order for the subsequent
code to execute correctly, you must assert it with a statement like
this:
\begin{quote}
\shortcode{assert(var1 == var2);}
\end{quote}

In general assert takes as argument a boolean expression. If the
boolean expression is true, execution continues. Otherwise the
\shortcode{abort} system call is invoked and the program execution is
stopped. If a bug prevents the precondition from being true, then you
can trace the bug at the point where the precondition breaks down
instead of further down in execution or not at all.  The \shortcode{assert} call
is implemented as a C preprocessor macro, so it can be enabled or
disabled at will. 

In ARTS, you don't have to do this manually, as long as your source file
includes \shortcode{arts.h} either directly or indirectly. Instead, assertions
are turned on and off with the global NDEBUG preprocessor macro, which is
set or unset automatically by the \shortcode{cmake} build configuration.
Assertions are enabled in the default \shortcode{cmake} build configuration
(\shortcode{-DCMAKE\_BUILD\_TYPE=RelWithDebInfo}). They are turned off in the
release configuration (\shortcode{-DCMAKE\_BUILD\_TYPE=Release}).

If your program is stopped by an assertion failure, then the first
thing you should do is to find out where the error happens. To do
this, run the program under the GDB debugger. First invoke
the debugger:
\begin{quote}
\shortcode{gdb arts}
\end{quote}
You have to give the full path to the ARTS executable.  Then set a
breakpoint at the assertion failure:
\begin{quote}
  \shortcode{(gdb) break \_\_assert\_fail}
\end{quote}
(Note the two leading underscores!) Now run the program: 
\begin{quote}
  \shortcode{(gdb) run}
\end{quote}

Instead of just exiting, under the debugger the program will be paused
when the assertion fails, and you will get back the debugger prompt.
Now type:
\begin{quote}
  \shortcode{(gdb) where} 
\end{quote}  
to see where the assertion failure happened. You can use the
\shortcode{print} command to look at the contents of variables and you
can use the \shortcode{up} and \shortcode{down} commands to navigate
the stack.  For more information, see the GDB documentation or type
\shortcode{help} at the prompt of GDB.

For ARTS, the assertion failures mostly happen inside the Tensor /
Matrix / Vector package (usually because you triggered a range check
error, i.e., you tried to read or write beyond array bounds). In this
case the \shortcode{up} command of GDB is particularly useful. If you
give this a couple of times you will finally end up in the part of
your code that caused the error.

Recommendation: In Emacs there is a special GDB mode. With this you
can very conveniently step through your code.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "uguide"
%%% End: 
