installation.tex

\chapter{Installation} \label{ch:installation}

The release of \verb'OpenCAL', here presented, is a collection of four
different software libraries. Under the name \verb'OpenCAL' we
identify the serial version of the library. It comes together with two
different parallel implementations based on OpenMP and OpenCL, namely
OpenCAL-OMP and OpenCAL-CL, respectively. Eventually, OpenCAL-GL
identifies an OpenGL/GLUT-based visualization library.

The library can be currently obtained only as source code to be
compiled from GitHub. Some dependencies must be satisfied, depending
on which libraries must be compiled. Eventually, headers and libraries
can be installed and, eventually, uninstalled if no longer needed. In
the following Sections we will see all the steps needed to obtain the
software and make it working.

\section{Requirements and dependencies}

In order to build the different libraries, you need a quite recent
ANSI C compiler (e.g. gcc under Linux/Unix systems or Microsoft Visual
C++ under Windows\footnote{The clang C compiler can also be used,
  taking in mind that it still does not fully support Open-MP
  natively.}), and CMake (to generate the makefiles, or even project
files for several IDEs like Eclipse). An OpenCL implementation
(e.g. by AMD, Intel or NVIDIA) is also needed to build OpenCAL-CL, as
well as GLUT (e.g. freeglut) is needed to build OpenCAL-GL. Some
dependencies must also be satisfied, depending on the library to be
built:

%% Moreover, still to compile OpenCAL-CL, at least the 3.1 version of
%% CMake is required. Eventually, a GLUT development library is needed to
%% compile OpenCAL-GL. The following is a dependencies list for each of
%% the above software libraries:

\begin{description}
\item[OpenCAL: ] A quite recent ANSI C compiler, and CMake version 2.8
  or greater.
\item[OpenCAL-OMP: ] A C compiler supporting at least Open-MP version
  2.0\footnote{For a list of OpenMP compliant compilers see the
    following link: \url{http://openmp.org/wp/openmp-compilers/}.},
  and CMake version 2.8 or greater.
\item[Open-CL: ] A quite recent ANSI C compiler, CMake version 3.1 or
  greater, and OpenCL version 1.2 or greater}.
\item[OpenCAL-GL: ] A quite recent ANSI C compiler, CMake version 2.8
  or grater, OpenGL/GLUT headers and libraries \footnote{For
  example \texttt{freeglut-devel} or \texttt{freeglut3-dev} packages
  on \texttt{yum/dnf}- and \texttt{apt}-based systems,
  respectively.}. Moreover, POSIX Threads are required.
\end{description}

\noindent Eventually, Doxygen and Graphviz are required to build the
software documentation, which provides specific information about
implemented data structures and functions.

Note that Visual Studio users under Microsoft Windows have to use the
the freeglut and pthreads provided with OpenCAL. In this case,
please copy the libs directory, containing both freeglut and pthreads
for Microsoft Visual Studio, in the desired path on the local disk
(e.g. in \verb'C:\'). Moreover, paths containing DLLs
(e.g. \verb'C:\libs\pthreads\bin' and \verb'C:\libs\freeglut\bin')
have to be added to the Windows PATH environment variable, in order to
be found by the loader.

\section{Obtaining OpenCAL}

The stable releases of libraries and examples can be downloaded as source code at the
following GitHub urls:

\begin{table}[h]
  \centering
  \begin{tabularx}{\textwidth}{lX}
    \textbf{opencal-1.0} & \url{https://github.com/OpenCALTeam/opencal/archive/1.0.zip}\\
    \textbf{opencal-examples-1.0} & \url{https://github.com/OpenCALTeam/opencal-examples/archive/1.0.zip}\\
  \end{tabularx}
\end{table}

\noindent Development releases of libraries and examples can also be
downloaded (for instance into the \verb'~/git' directory, where the
symbol \verb'~' identifies the user's home directory) by cloning the
GitHub repositories:

\begin{lstlisting}[numbers=none,language=bash]
user@machine:-$ cd ~/git
user@machine:-$ git clone https://github.com/OpenCALTeam/opencal
user@machine:-$ git clone https://github.com/OpenCALTeam/opencal-examples
\end{lstlisting}

Note that, Microsoft Windows users have to set their git client such
that it does not convert files from the UTF-8 format towards any other
file format (e.g. ANSI), since OpenCL kernel must currently be of the
former format.

%% \section{Structure of the Distribution Directory}

%% The software distribution contains the following files and
%% directories:

%% \begin{description}
%% \item[AUTHORS - ] OpenCAL Authors list;
%% \item[OpenCAL - ] Core and examples code of the \emph{serial}
%%   implementation;
%% \item[OpenCAL-CL - ] Core and examples code of the Open-CL-based
%%   parallel implementation;
%% \item[OpenCAL-GL - ] Graphic OpenGL/GLUT-based visualization system
%%   library and examples;
%% \item[OpenCAL-OMP - ] Core and examples code of the Open-MP-based
%%   parallel implementation;
%% \item[CMakeLists.txt - ] CMake configuration file;
%% \item[cmake\_uninstall.cmake.in - ] Uninstall script;
%% \item[configure.cmake - ] File needed by (i.e. included in) CMakeLists.txt;
%% \item[LICENSE] The GNU LGPL licence;
%% \item[Other minor files - ] Other minor files can also be included into the distribution.
%% \end{description}

%% \subsection{CMake}
%% \verb'OpenCAL' uses \verb'CMake' to generate Project Files or
%% Makefiles for a particular configuration (development environment and
%% library features). If you are on a Unix-like system, such as a
%% Linux-based distribution or FreeBSD, or have a package system like
%% Fink, MacPorts, Cygwin or Homebrew, you can simply install its CMake
%% package. If this is not the case, you can download the installers for
%% Windows and Mac OS X from the CMake website.

%% CMake only generates Project Files or Makefiles that describe how and
%% which characteristics should be compiled. It does not compile the
%% actual \verb'OpenCAL' library. To compile \verb'OpenCAL', first
%% generate these files for your chosen development environment and then
%% use them to compile the actual \verb'OpenCAL' library.

%% Suppose you want to compile \verb'OpenCAL' and enable support for
%% OpenMP. You will instruct \verb'CMake' to create the correct Makefiles
%% for enabling support for \verb'OpenMP' using the
%% \texttt{-DBUILD\_OPENCAL\_OMP=ON} and
%% \texttt{-DBUILD\_OPENCAL\_OMP\_PARALLEL=ON} arguments.


\section{Build and Install}

\subsection{Generating project files with CMake}

In order to generate the Unix makefiles or project files for Microsoft
Visual Studio (or other IDEs), needed to compile OpenCAL libraries and
examples, the following steps can be carried out:

\begin{enumerate}
\item Enter the OpenCAL source tree root directory (e.g. \verb'~/git/opencal-1.0/');
\item Create a directory for the binaries
  (e.g. \verb'~/git/opencal-1.0/build/') and enter into it;
\item Run CMake using the options listed in Table
  \ref{ch:installation:cmakeoptions} to control which features will be
  enabled in the compiled libraries.
\end{enumerate}

\begin{table}[h]
  \centering
  \caption{List of CMake options, alongside their default values and
    effects}
  \label{ch:installation:cmakeoptions}
  \begin{tabular}{lll}
    \hline
    CMake option &  Default & Effect\\
    \hline
    \texttt{BUILD\_OPENCAL\_SERIAL} & ON  & Build serial version\\
    \texttt{BUILD\_OPENCAL\_OMP}    & ON  & Build OpenMP-based parallel version\\
    \texttt{BUILD\_OPENCAL\_CL}     & OFF & Build OpenCL-based parallel version\\
    \texttt{BUILD\_OPENCAL\_GL}     & OFF & Build OpenCAL-GL visualization library\\
    \texttt{BUILD\_DOCUMENTATION}   & OFF & Build HTML API documentation\\
    %% \texttt{BUILD\_OPENCAL\_PP}  & OFF & Build OpenCAL-C++ version (C++11 compliant compiler Required)    &  OFF\\ \hline
    %% \texttt{ENABLE\_SHARED}      & ON  & Controls whether the library should be compiles as shared object (.so). If OFF, static objects (.a) will be produced & OFF\\ \hline
     \hline
  \end{tabular}
\end{table}

Each CMake option corresponds to a target. If you are not interested
in some of them, simply switch off the corresponding option. If you
omit a CMake option, the default value will be assumed (cf. Table
\ref{ch:installation:cmakeoptions}). If you want to build everything
(serial and parallel libraries, examples and documentation), use the
following commands:

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:simplebuild}]
  user@machine:-$ cd ~git/opencal-1.0/
  user@machine:-$ mkdir build && cd build
  user@machine:-$ cmake ../ -DBUILD_OPENCAL_SERIAL=ON \
                            -DBUILD_OPENCAL_OMP=ON \
                            -DBUILD_OPENCAL_CL=ON \
                            -DBUILD_OPENCAL_GL=ON \
                            -DBUILD_DOCUMENTATION=ON
\end{lstlisting}

%% For instance, if you set the \verb'ENABLE_SHARED' option to \verb'OFF'
%% (that, indeed, is the default value), generated makefiles will be set
%% to build static libraries (.a files under Linux systems) instead of
%% shared objects (.so files).

Under Windows, freeglut and/or pthreads could not be found by CMake
modules, depending on the path where they were installed. In this
case, it is possible to use the CMake GUI and provide the include path
and libraries explicitly. For instance, if the aforementioned
dependencies have been satisfied as suggested, pthreads headers could
be found in \verb'C:\libs\pthreads\include', while the library in
\verb'C:\libs\pthreads\lib\pthread.lib'. The same holds for the
freeglut library.

\subsubsection{Custom installation path}

Another useful CMake option is \texttt{CMAKE\_INSTALL\_PREFIX:PATH},
that allows to change the default installation directory, that is
\verb'/usr/local' under Linux systems and
\verb'C:\Program Files (x86)' under Windows. Therefore, to select
\texttt{/opt} as installation target directory, change the above
invocation of CMake into the one below.

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:simplebuild}]
  user@machine:-$ cd ~git/opencal-1.0/
  user@machine:-$ mkdir build && cd build
  user@machine:-$ cmake ../ -DBUILD_OPENCAL_SERIAL=ON \
                            -DBUILD_OPENCAL_OMP=ON \
                            -DBUILD_OPENCAL_CL=ON \
                            -DBUILD_OPENCAL_GL=ON \
                            -DBUILD_DOCUMENTATION=ON\
                            -DCMAKE_INSTALL_PREFIX:PATH=/opt
\end{lstlisting}

\noindent or, under Microsoft Windows:

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:simplebuild}]
  user@machine:-$ cd C:\git\opencal-1.0\
  user@machine:-$ mkdir build && cd build
  user@machine:-$ cmake ../ -DBUILD_OPENCAL_SERIAL=ON \
                            -DBUILD_OPENCAL_OMP=ON \
                            -DBUILD_OPENCAL_CL=ON \
                            -DBUILD_OPENCAL_GL=ON \
                            -DBUILD_DOCUMENTATION=ON\
                            -DCMAKE_INSTALL_PREFIX:PATH=C:\libs
\end{lstlisting}


\subsection{Compiling}
Once makefiles have been produced, everything is set up and ready for
compiling. To compile under Linux, use the following command:

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:ebuild}]
  user@machine:-$ make -j n
\end{lstlisting}
where \verb'n' is the number of cores of your machine you want to use
for speeding up the compilation process.

Under Windows it is sufficient to open the OpenCAL-1.0.sln Visual
Studio solution and press the F7 key to build the libraries.

\subsection{Install}

You can install the compiled libraries, headers and API documentation
using the following Linux command:

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:sudoinstall}]
  user@machine:-$ sudo make install
\end{lstlisting}

\noindent or equivalently, if the user is not in the \texttt{sudoers} list:

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:install}]
  user@machine:-$ sudo -
  root@machine:-$ make install
\end{lstlisting}

\noindent Under Linux systems, files are installed by default in
\texttt{/usr/local/}. See Table \ref{ch:ddefault_paths} for major
details.

\begin{table}[h]
  \centering
  \caption{Default installation paths for OpenCAL files under Linux systems}
  \label{ch:ddefault_paths}
  \begin{tabularx}{\textwidth}{ll}
    \hline
    \textbf{Installation path} & \textbf{Installed objects}\\
    \hline
    \verb'/usr/local/opencal-1.0/lib/'                   & Shared objects \\
    \verb'/usr/local/opencal-1.0/include/'                & Header files \\
    \verb'/usr/local/opencal-1.0/include/OpenCAL-CL/kernel' & OpenCL kernels \\
    \verb'/usr/local/opencal-1.0/doc/'                   & API documentation \\
    \hline
  \end{tabularx}
\end{table}


Under Windows, it is sufficient to compile the INSTALL project, that
can be found under the Visual Studio solution. Note that, in order to
install files in the default path, Visual Studio has to be run as
Administator. In the case the installation path was set to
\verb'C:\libs', as we suggest, files will be installed as described in
Table \ref{ch:win_custom_install_paths}. Note that, as for
dependencies, also the directory containing OpenCAL DLLs
(e.g. \verb'C:\libs\opencal-1.0\bin') have to be added to the Windows
PATH environment variable.

\begin{table}[h]
  \centering
  \caption{Installation paths for OpenCAL files under Windows systems.}
  \label{ch:win_custom_install_paths}
  \begin{tabularx}{\textwidth}{ll}
    \hline
    \textbf{Installation path} & \textbf{Installed objects}\\
    \hline
    \verb'C:\libs\opencal-1.0\bin'                    & DLLs\\
    \verb'C:\libs\opencal-1.0\lib'                   & .lib archives\\
    \verb'C:\libs\opencal-1.0\include'                & Header files \\
    \verb'C:\libs\opencal-1.0\include\OpenCAL-CL\kernel' & OpenCL kernels \\
    \verb'C:\libs\opencal-1.0\doc'                   & API documentation \\
    \hline
  \end{tabularx}
\end{table}


%% \subsection{Configuring the environment}
%% After installation, you need to set you environment up in order to use
%% OpenCAL libraries. In particular, you need to update the
%% \verb'LD_LIBRARY_PATH' environment variable and regenerate the loader
%% cache file. For instance, if you installed the software in
%% \verb'/usr/local/opencal-1.0', you need to add the path
%% \verb'/usr/local/opencal-1.0/lib' to \verb'LD_LIBRARY_PATH' and then
%% run the command \verb'ldconfig' as root. To do this you can add the
%% following lines to your \verb'.bash_profile' configuration file in
%% your home direcory
%% \begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:.bash_profile}]
%% LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/opencal-1.0/lib
%% export LD_LIBRARY_PATH
%% \end{lstlisting}
%% and then type the following commands:
%% \begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:source}]
%% user@machine:-$ source .bash_profile
%% user@machine:-$ sudo ldconfig
%% \end{lstlisting}
%% The first command executes the content of the file argument
%% (i.e. \verb'.bash_profile'), while the second updates the loader's
%% cache, so that openCAL shared objects can be loaded at run time.

%% The above procedure is only valid for the current user. If you want to
%% allow all the other users to use OpenCAL you can create a new file in
%% \verb'/etc/ld.so.conf.d/', for instance \verb'opencal.conf',
%% containing the \verb'/usr/local/opencal-1.0/lib' path, and then call
%% \verb'ldconfig' as root.

One more operation is necessary if you want use CMake to compile your
own OpenCAL-based applications, i.e. copy the
\verb'FindOpenCAL.cmake', located in \verb'~/git/opencal/cmake', into
the directory containing the other CMake modules. Under Linux systems,
such a directory is usually
\verb'/usr/share/cmake/Modules'. Therefore, you can simply use the
following command to copy the OpenCAL find module into the appropiate
directory:

\begin{lstlisting}[numbers=none,language=bash]
  user@machine:-$ sudo cp ~/git/opencal/cmake/FindOpenCAL.cmake /usr/share/cmake/Modules
\end{lstlisting}

Under Windows, CMake modules can be generally found in the following  
\verb'C:\Program Files (x86)\CMake\share\cmake-3.5\Modules' directory (or a
similar path, depending on CMake version).

%% Please, note that even in the case you chose the default installation
%% path, that locates shared objects in \verb'/usr/local/lib' under Linux
%% systems, you need to update the loader path and cache by putting the
%% string \verb'/usr/local/lib' in \verb'/etc/ld.so.conf.d/opencal.conf'
%% and then calling \verb'sudo ldconfig'.

\subsection{Test the installation}\label{sec:installation:test_installation}

In order to test software installation you can compile and run the
\verb'life' example program in
\verb'~/git/opencal-examples/OpenCAL/cal_life'. You can use CMake, as
we did before, or compile it directly.

If you want to use CMake, follow the steps below:

\begin{lstlisting}[numbers=none,language=bash]
  user@machine:-$ cd ~/git/opencal-examples/OpenCAL/cal_life
  user@machine:-$ mkdir build && cd build
  user@machine:-$ cmake ..
  user@machine:-$ cd ..
  user@machine:-$ ./bin/cal_life  
\end{lstlisting}

%% In the latter case, if you chose the default installation, it is
%% sufficient to type the following command:
%% \begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:gcc}]
%%   user@machine:-$ gcc life.c -o life -lopencal
%% \end{lstlisting}
%% while, if you chose a custom installation path, e.g. \verb'/usr/local/OpenCAL-1.0',

In the latter case you need to specify where include files and shared objects are located
and link the required library, as in the following example:
\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:gcc-full}]
  user@machine:-$ cd ~/git/opencal-examples/OpenCAL/cal_life
  user@machine:-$ gcc source/life.c -o life -I/usr/local/opencal-1.0/include \
                                            -L/usr/local/opencal-1.0/lib \
                                            -lopencal
  user@machine:-$ ./life
\end{lstlisting}

In both cases, the \verb'life_0000.txt' and \verb'life_LAST.txt' files
should be generated. If this is the case, congratulations, you
installed OpenCAL properly.

Under Windows, the same steps have to be performed, by exploiting the
CMake GUI application in case.

\section{Compiling the examples}

The examples can be easily compiled using CMake, all together or one
at a time. To compile all the examples at once, follow the steps below
(cf. Table \ref{ch:installation:cmakeoptions-example} for available
options and their default values):

\begin{lstlisting}[numbers=none,language=bash]
  user@machine:-$ cd ~/git/opencal-examples
  user@machine:-$ mkdir build
  user@machine:-$ cd build
  user@machine:-$ cmake .. -DBUILD_OPENCAL_CL=ON -DBUILD_OPENCAL_GL=ON
\end{lstlisting}


\begin{table}[h]
  \centering
  \caption{List of OpenCAL examples CMake options, alongside their default values and
    effects}
  \label{ch:installation:cmakeoptions-example}
  \begin{tabular}{lll}
    \hline
    CMake option &  Default & Effect\\
    \hline
    \verb'BUILD_OPENCAL_SERIAL' & ON  & Build OpenCAL serial examples\\
    \verb'BUILD_OPENCAL_OMP'    & ON  & Build OpenCAL-OMP examples\\
    \verb'BUILD_OPENCAL_CL'     & OFF & Build OpenCAL-CL examples\\
    \verb'BUILD_OPENCAL_GL'     & OFF & Build OpenCAL-GL examples\\
     \hline
  \end{tabular}
\end{table}

Windows users have to refer the opencal-examples-1.0 solution and
compile the examples within the Visual Studio environment.

To compile a particular example, please follow the steps described in
Section \ref{sec:installation:test_installation}.

\section{Uninstall}

If you want to uninstall OpenCAL, you can call \verb'make' with the
uninstall target, remove the installation direcory and, if installed,
remove the FindOpenCAL.cmake module, as in the following example:

\begin{lstlisting}[numbers=none,language=bash,label={ch:quickstart:sudouninstall}]
  user@machine:-$ sudo make uninstall && 
                       rm -rf /usr/local/opencal-1.0 && \
                       rm /usr/share/cmake/Modules/FindOpenCAL.cmake
\end{lstlisting}

Under Visual Studio it is sufficient to compile the UNINSTALL project.

\section{Web Page and Bug Reporting}

The Web page for OpenCAL is at \url{http://opencal.telesio.unical.it} and
contains up-to-date news and a list of bug reports. \ocal GitHub
homepage is at \url{https://github.com/OpenCALTeam/opencal}. For
further information or bug reports contact
\url{mailto:opencal@telesio.unical.it} or use the submit an issue at the
following url \url{https://github.com/OpenCALTeam/opencal/issues}.

When reporting a bug, please include as much information and
documentation as possible. Helpful information would include OpenCAL
version, OpenMP/OpenCL implementation and version used,
configuration options, type of computer system, problem description,
and error message output.