AMC13CppSoftwareBuildNotes < BUCMSPublic

The following procedures describe the installation process for xDAQ releases for the HCAL Upgrade project.  *NOTE* that the code has been migrated to SVN (instead of CVS) as of 02/07/2013, hence these instructions have since then been updated.

Though these processes are presented as specific to BU's machine, the steps can easily be generalized to any other SLC5 machine with a =daqowner= account and a xDAQ installation.  

*NOTE!!!*  These examples show how to install release 11_8_1, but the process can be generalized to any xDAQ release xx_x_x.

| *Contents* |
| [[#InstallAsDaqowner][Install a Release as daqowner]] |
| [[#InstallInOwnSourceTree][Install a release in your own source tree]] |
| [[#CheckCodeIntoSVN][Check edited code back into SVN]] |
| [[#SubscribeHyperNews][Subscribe to HCAL Online Software HyperNews]] |

#InstallAsDaqowner
---++ Install a Release as daqowner
Before any other =cms2= users can run the release software, it must be installed by =daqowner@cms2.bu.edu=.  Check to make sure the release isn't already installed before following this procedure!

   1. Log in as =daqowner=:
   <verbatim>
   ssh daqowner@cms2.bu.edu
   </verbatim>
   1. Get the installation script from the =cmshcalweb= database:
   <verbatim>
   wget http://cmshcalweb01.cern.ch/hcalsw/release/installDAQ_11_8_1.perl
   </verbatim>
   1. Run the installation script:
   <verbatim>
   perl installDAQ_11_8_1.perl --mode=teststand
   </verbatim>
   1. Once the installation script has finished, pick the correct release:
   <verbatim>
~daqowner/common/bin/pickRelease.sh
Available installed releases
   1 )   11.0.7
   2 )   11.2.3
   3 )   11.3.1
   4 )   11.4.0
   5 )   11.4.2
   6 )   11.4.3
   7 )   11.5.0
   8 )   11.5.1
   9 )   11.5.2
   10 )   11.5.3
   11 )   11.5.5
   12 )   11.5.6
   13 )   11.6.0
   14 )   11.6.2
   15 )   11.6.3
   16 )   11.6.4
   17 )   11.6.5
   18 )   11.7.0
   19 )   11.7.1
   20 )   11.7.2
   21 )   11.7.3
   22 )   11.7.7
   23 )   11.8.1
Pick release to use:   23
   </verbatim>

   1. Set the environment for this release:
   <verbatim>
~daqowner/dist/etc/env/env.sh
   </verbatim>
   or, if you are using the tc-shell:
   <verbatim>
~daqowner/dist/etc/env/env.csh
   </verbatim>

You are now ready to run the executables!  See the [[AMC13ToolGettingStarted][AMC13 Tool: Getting Started]] section to learn about the primary AMC13 executable.

#InstallInOwnSourceTree
---++ Install a release in your own source tree
If you want to *edit* the xDAQ code without interfering with others, then you will need to check out a copy of the release into your own source tree.  From there you can check any changes back into CVS.

*NOTE!!!* These examples show how to install release 11_8_1, but the process can be generalized to any xDAQ release xx_x_x.

   0. If you are going to be a regular developer, it is a good idea to establish a Kebros SSH ticket (at Jeremy's strong recommendation) as discussed [[http://svn.web.cern.ch/svn/howto.php#accessing-sshlinux][here]].  If I may quite Jeremy: "This will make your life _much_better_."
   1. First, ensure that the release you want to work with is the current one, as such:
   <verbatim>
   ls -l /home/daqowner/dist
   lrwxrwxrwx 1 daqowner daq 25 Jan  5 09:56 /home/daqowner/dist -> /home/daqowner/daq.11.8.1
   </verbatim>
   If the release is not the one you want, use =pickRelease.sh= (instructions shown above) or [[#InstallAsDaqowner][install the desired release]].
   1. Copy the installation script to your login directory (or whatever directory you want to keep your installation scripts):
   <verbatim>
   cp ~daqowner/installDAQ_11_8_1.perl ${HOME}/
   </verbatim>
   1. <em>NOTE:  This is wrong.  It appears that if you simply omit the "--svnuser" argument that it will check out anonymously, but I have no way to check this right how.</em>  
If you want to check the xDAQ code out of SVN _anonymously_ (i.e. if you do not have an afs ID or don't care to have access to the repository), edit the script, search for "anonymous", and remove the =#= comment mark.  Otherwise, if you have an afs ID and want access to the repository, skip this step.
   1. Run the installation script, ownsourcing the code to your =${HOME}/src= directory:
   <verbatim>
   perl ~/installDAQ_11_8_1.perl --mode=teststand --ownsource=${HOME}/src/11_8_1 --packages=hcalUpgrade --svnuser=[afsID]
   </verbatim>
      * NOTE that you can put the code into any directory you like; it doesn't have to be =${HOME}/src/11_8_1=.
      * NOTE that you can also install additional packages, if you wish; you're not limited to the hcalUpgrade.  However, ALL of the AMC13 code lies within the hcalUpgrade package!!  If =packages= is not specified, then all packages are installed by default.
      * NOTE that the uHTR code is in the =hcalUHTR= package (e.g. if you wanted both the hcalUpgrade and hcalUHTR packages the option would look like: --packages=hcalUpgrade,hcalUHTR)
      * NOTE that if you removed the "anonymous" comment mark in the previous step, you do not need the =svnuser= argument.
   1. Set the environment for your new ownsource code development area:
   <verbatim>
   source /home/daqowner/dist/etc/env.sh
   export LD_LIBRARY_PATH=${HOME}/src/11_8_1/hcal/hcalUpgrade/amc13/lib/linux/x86_64_slc5/:${LD_LIBRARY_PATH} 
   </verbatim>
   1. If you provided your "svnuser" afs ID (and therefore have access to the repository), update the software to the latest code in SVN (in case changes have been checked in by other parties since this release):
   <verbatim>
   cd ~/src/11_8_1/hcal/hcalUpgrade/
   svn update
   </verbatim>
   1. Build the code in __exactly__ the following order:
   <verbatim>
   cd ~/src/11_8_1/hcal/hcalUpgrade/ipbus/
   make
   cd ../amc13 
   make
   cd ../ 
   make
   </verbatim>
   1. After the code is done building, you have finished!  You are now ready to run the [[AMC13Tool]] executable and edit your private development area!

If you wish to edit the AMC13 code, you can make changes to the source code in =${HOME}/src/11_8_1/hcal/hcalUpgrade/amc13/src/common/= and then go back up to the =/amc13= level to recompile using =make=. 

#CheckCodeIntoSVN
---++ Check edited code back into SVN
If you have edited the AMC13 code and want to make the edits available to other developers (important for bug fixes!), you will need to check your changes back into SVN.  If you are unfamiliar with SVN, it is a good idea to take a quick gander at the [[http://svnbook.red-bean.com/][Subversion Manual]] before proceeding.  For a more succinct look at the basic SVN commands, check out [[http://www.linuxfromscratch.org/blfs/edguide/chapter03.html][this site]].

*IMPORTANT!!!*  It is _imperative_ that you _make sure_ your edited code compiles and runs without breaking before checking changes into SVN.  The HCAL Upgrade does not want to release busted software!

   1. Go to the =hcal/hcalUpgrade= level of the release directory and svn update:
   <verbatim>
   $ cd ~/src/11_8_1/hcal/hcalUpgrade
   $svn update
   </verbatim>
   This makes sure that your code is up to date with all "outside" changes since the release and that your edits do not conflict with others'.
   1. In the =hcal/hcalUpgrade= directory, run an =svn status= command to make to see what you've changed and to make sure everything is ready for a commit. 
   <verbatim>
   $ cd ~/src/11_8_1/hcal/hcalUpgrade
   $ svn status
   </verbatim> 
   1. Be sure that your code compiles and runs properly.  Only after you are confident of your changes being effective and accurate should you proceed.
   1. Update the package's =hcal/hcalUpgrade/include/hcal/upgrade/version.h= file to give the code a new version number.  Generally, very small bug fixes would result in the PATCH digit changing, while larger changes would be MINOR.  MAJOR version changes should mostly be for backward-incompatible changes. When you increment MINOR, you should set PATCH back to zero, and when you increment MAJOR, MINOR and PATCH should go to zero.
   1. In the same way as the previous step, update the version number in the file =hcal/hcalUpgrade/amc13/include/hcal/amc13/version.h=.
   1. _If you are maintaining the AMC13Tool Standalone_, now is the time to sync the standalone to the current version. (If not, skip to next step)
   <verbatim>
   $cd ~/src/11_8_1/hcal/hcalUpgrade/amc13/amc13Standalone/
   ./syncAMC13Standalone.sh
   </verbatim>
   1. Commit your code into the SVN repository, giving a useful commit message which states your changes to the AMC13 code.
   <verbatim>
   $cd ~/src/11_8_1/hcal/hcalUpgrade/
   $ svn commit -m <commit_message>
   </verbatim>
   1. Run the script "hcostag" to tag your code *in the hcalUpgrade package directory*.  This script will determine the appropriate tag name and take the necessary SVN actions.
   <verbatim>
   $ cd ~/src/11_8_1/hcal/hcalUpgrade
   $ ../config/build/hcostag
   </verbatim>
   1. _If you are maintaining the AMC13Tool Standalone_, now you can prep the release and post the compressed files. (If not, skip to the last step).
      * NOTE: You should have a directory for your AMC13 Standalone Releases which contains [[http://ohm.bu.edu/~dzou/prepReleases.sh][prepReleases.sh]] . If you do not, please make one now.
      * Navigate to you AMC13 Standalone Releases directory and run prepReleases.sh
   <verbatim>
   $ ./prepReleases.sh ~/src/11_8_1/hcal/hcalUpgrade/amc13/amc13Standalone/
   </verbatim>
      * Host both the RPM and MAN versions of the release in a publicly accessible location and post links appropriately to AMC13CppSoftware
   1. Lastly, it is a good idea to contact the release managers (currently Jeremy Mans *<Jeremy.Mans@cern.ch>* and Shih-Chuan Kao *<Shih-Chuan.Kao@cern.ch>*) to inform them that a new version should be used in the next software release    

#SubscribeHyperNews
---++ Subscribe to HCAL Online Software !HyperNews
In order to be informed of HCAL Upgrade software releases, you must be registered with the correct CMS HyperNews subscriptions.  Below is the process for getting on the list.

   1. Go the [[https://hypernews.cern.ch/HyperNews/CMS/get/hcalOnlineSW/970.html][HyperNews webpage]] and log in with your afs credentials
   1. Click on the *Subscribe to Forums* link at the top of the screen
   1. Under the *Category: Detector Subsystems* section, select *HCAL Online Software Development*
   1.  While you're here, other useful forums to check include *HCAL Electronics*, *HCAL Discussions*, and *SLHC HCAL Upgrade* 
You will now receive emails whenever a new software package is built with installation instructions and and release notes  

-- Main.EricHazen - 13 Apr 2012
This topic: BUCMSPublic > WebHome > HcalDTC > AMC13CppSoftwareBuildNotes
Topic revision: r20 - 09 Sep 2013 - DavidZou