CodingPractices.tex

% Coding practices

\subsection{Installation of Pixel Online Software}
Instructions from {\tt https://twiki.cern.ch/twiki/bin/view/CMS/PixelOnlineSoftwareInstallation}

\subsubsection{General setup}
Installation of the software should conventionally be done in a 
directory called {\tt TriDAS}, in which the pixel software is 
located in a directory called {\tt pixel}.  Create this directory 
and change to it:

\begin{verbatim}
mkdir -p TriDAS/pixel
cd TriDAS/pixel
\end{verbatim}

The Pixel Online Software consists of a number of packages which are 
collected in a so-called POSRelease in SVN.
\begin{itemize}
\item CMS Pixel DAQ SVN repository: {\tt https://svnweb.cern.ch/trac/cmspxldaq/browser}
\item POS releases: {\tt https://svnweb.cern.ch/trac/cmspxldaq/browser/POSRelease/tags}
\item POS development release (trunk): {\tt https://svnweb.cern.ch/trac/cmspxldaq/browser/POSRelease/trunk}
\end{itemize}

\textbf{Currently recommended POSRelease: \textit{trunk}}

Check-out the release (use either a tag \textbf{or} trunk 
\textbf{or} branch).  The password it will ask you for is the one of 
your CERN (lxplus) account:

\begin{verbatim}
export CERNUSER=YourUserNameAtCERN
svn co --username $CERNUSER https://svn.cern.ch/reps/cmspxldaq/POSRelease/trunk POSRelease #for trunk
svn co --username $CERNUSER https://svn.cern.ch/reps/cmspxldaq/POSRelease/tags/POS_4_3_1 POSRelease #for tag POS_4_3_1
\end{verbatim}

This will provide you with a couple of scripts that will help with 
the following.

\subsubsection{Setting up the environment}
The environment can be set up using a script called {\tt setenv.sh}, 
which can be automatically generated by a script contained in the 
POSRelease to which you need to provide the location of ROOT:

\begin{verbatim}
cd POSRelease
./create_setenv.sh -r $ROOTSYS
\end{verbatim}

The script will automatically detect all other required information 
such as your SLC release and machine architecture.  In case of 
problems follow the output of the script and use the flags printed 
out to adjust.  Then set up the environment doing:

\begin{verbatim}
source setenv.sh
\end{verbatim}

The environment needs to be sourced each time you want to use POS 
(in a new terminal).

\subsubsection{Installation of external software}
The software packages described below are developed externally, 
mostly by the strips tracker community.  Therefore, they don't 
reside in the POS SVN repository.  The packages need to be installed 
into the {\tt TriDAS} directory.

\textbf{Note:} For a user installation in a .CMS online home 
directory, the corresponding directories can (and should) be 
directly linked from the pixelpro user space due to quota 
restrictions - you should \textbf{not} install it yourself.  The 
DiagSystem is not needed anymore in XDAQ12:

\begin{verbatim}
cd $BUILD_HOME
ln -s /nfshome0/pixelpro/TriDAS/DiagSystem DiagSystem #XDAQ11 only
ln -s /nfshome0/pixelpro/TriDAS/FecSoftwareV3_0 FecSoftwareV3_0
ln -s DiagSystem/LogReaderWithFileServer pixel/LogReaderWithFileServer #XDAQ11 only
\end{verbatim}

\subsubsection{Installation of pixel software}
The pixel software can be installed using a script from the 
POSRelease package.  It will check out the packages from the SVN 
repository based on the {\tt packages.txt} file.  In case you 
checked out the {\tt trunk} version of POSRelease, the 
{\tt packages.txt} file will point to the latest tags of the POS 
packages.  To check out the trunk, you can replace the 
{\tt packages.txt} file by {\tt packages\_trunk.txt}.

To make sure the script works, please set the option 
{\tt store-plaintext-passwords} in {\tt \$USER/.subversion/servers} 
to {\tt no}.

\begin{verbatim}
cd $BUILD_HOME/pixel/POSRelease
./checkout.py
\end{verbatim}

In case of problems, have a look at the {\tt log} directory.

\subsubsection{Compiling pixel online software}
Now everything's ready for compilation:

\begin{verbatim}
cd $BUILD_HOME/pixel
make install
make Set=pixel
\end{verbatim}

Compilation problems observed in the past are related to missing 
{\tt curlpp} libraries.  This can be resolved by installing

\begin{verbatim}
yum install curlpp
yum install curlpp-devel.x86_64
\end{verbatim}

If the compiler then complains about a {\tt config.h} file not 
found, go to the directory and see what the file is actually called 
(e.g. {\tt config.h.in}) and change the line in the code in 
{\tt global.h}.

\subsection{Makefile}

The pixel online software is built with a
Makefile located in each (sub)package. The
Makefile builds on the xdaq tools. This
file should ideally be as short as possible
and use the functionallity in the xdaq package.
You invoke the Makefile in each package by 
doing a 'make'. There is also a {\tt clean} target.

In addition to the package level makefiles 
this is a toplevel makefile in the pixel
directory. This makefile allow you to build 
all the xdaq packages using {\tt make Set=pixel}.
You can also clean all packages using 
{\tt make Set=pixel clean}.

\subsection{Include files}

Include statements should include the file path 
starting from the project. For example you should do

\begin{verbatim}
#include "PixelCalibrations/include/PixelAOHBiasCalibration.h"
#include "CalibFormats/SiPixelObjects/interface/PixelCalibConfiguration.h"
\end{verbatim}

\subsection{CVS tags}

We create 'official' tags of the form 'POS\_X\_Y\_Z',
e.g. 'POS\_2\_4\_5'. For every tag created, starting
with POS\_2\_5\_0, an entry should be made in the
file pixel/README that describes briefly the new
features in the tag.

\subsection{Building RPMs}

The building of RPMs should be straightforward. The
following steps are required.
\begin{itemize}
\item Prepare the code, update the README file, and VERSION file and
      commit and tag the code. The VERSION file contains the version
      of the RPM to build.
\item Invoke 'make Set=pixel rpm' to build RPMs for all pixel online software 
      packages.
\item In the {\tt PixelUtilities} directory, invoke 'buildExternalRPMs.sh'
      to build RPMs for DiagSystem, TTCSoftware, and FecSoftwareV3\_0.
      At the end of building the external RPMs this script copies
      all RPMs to \$BUILD\_HOME/RPM\_X.Y.Z-V, where X, Y, Z, and V are
      the major version, minor version, patch, and build version, 
      respectively.
\end{itemize}
The set of RPMs built can be tested (in the online environment) for
consistency by invoking the command 'rpm --test -Uvh *.rpm' in the directly
where all the RPMs are located.

Old RPMs can be cleaned out of the build area using the command 'make Set=pixel cleanrpm'.

\clearpage