\documentclass{article}

% Use the Cactus ThornGuide style file
% (Automatically used from Cactus distribution, if you have a
%  thorn without the Cactus Flesh download this from the Cactus
%  homepage at www.cactuscode.org)
\usepackage{../../../../doc/latex/cactus}

\begin{document}

\title{\tt ExternalLibraries/HDF5}
\author{Yaakoub Y El-Khamra, Thomas Radke,Federico Cipolletta}
\date{2020-07-01}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

\ifx\ThisThorn\undefined
\newcommand{\ThisThorn}{{\it HDF5}}
\else
\renewcommand{\ThisThorn}{{\it HDF5}}
\fi

\begin{abstract}
Thorn \ThisThorn\ provides the following utility programs:
%
\begin{itemize}
  \item {\tt hdf5\_double\_to\_single}\\
    Copies the entire contents of an input HDF5 file to an output HDF5 file,
    converting all double precision datasets to single precision.
  \item {\tt hdf5\_merge}\\
    Merges a list of HDF5 input files into a single HDF5 output file.
    This can be used to concatenate HDF5 output data created as one file per
    timestep.
  \item {\tt hdf5\_extract}\\
    Extracts a given list of named objects (groups or datasets) from an HDF5
    input file and writes them into a new HDF5 output file.
    This is the reverse operation to what {\tt hdf5\_merge.c} does. Useful eg.
    for extracting individual timesteps from a time series HDF5 datafile.
\end{itemize}
%
All utility programs are located in the {\tt src/util/} subdirectory of thorn
\ThisThorn. To build the utilities just do a

\begin{verbatim}
  make <configuration>-utils
\end{verbatim}

in the Cactus toplevel directory. The executables will then be placed in the
{\tt exe/<configuration>/} subdirectory.

All utility programs are self-explaining -- just call them without arguments
to get a short usage info.
If any of these utility programs is called without arguments it will print
a usage message.
\end{abstract}

\section{Using This Thorn}

Refer to the Cactus UserGuide, Sec. B2.2, in order to know how this thorn can be used in a compiled configuration and how to possibly linking another specific version, already installed steparately.

\subsection*{Note on possible ExternalLibraries' location stripping}
\label{stripping}

Each thorn contained in \texttt{Cactus/arrangements/ExternalLibraries} will automatically adopt the library version contained in the \texttt{Cactus/arrangements/<library>/dist} folder. In particular, the tarball in \texttt{Cactus/arrangements/<library>/dist} is only used if either \texttt{THORN\_DIR} is set to \texttt{BUILD} or is left empty and no precompiled copy of the library is found. If another location is specified via the \texttt{THORN\_DIR} variable in the \texttt{<machine>.cfg} file at compilation, then the \texttt{Cactus/lib/sbin/strip-incdirs.sh} script will automatically strip away (for safety reasons) the locations:
\begin{Lentry}
\item [\texttt{/include}]
\item [\texttt{/usr/include}]
\item [\texttt{/usr/local/include}]
\end{Lentry}
from \texttt{THORN\_INC\_DIRS} which default to \texttt{THORN\_DIR/include}. Therefore, if there is any need for using one already installed version of one external library, the aforementioned location should be avoided (e.g. indicating \texttt{/home} as the \texttt{THORN\_DIR} will work with no problems if the required library is installed there) or should be carefully checked, in order to avoid unwanted stripping. The same stripping happens to \texttt{THORN\_LIB\_DIRS} in \texttt{lib/sbin/strip-libdirs.sh} with a larger list of directories:
\begin{Lentry}
\item [\texttt{/lib}]
\item [\texttt{/usr/lib}]
\item [\texttt{/usr/local/lib}]
\item [\texttt{/lib64}]
\item [\texttt{/usr/lib64}]
\item [\texttt{/usr/local/lib64}] 
\end{Lentry}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}
