Latest revision as of 16:02, 16 November 2018

introduction

The JLab Scientific Softwareframework includes GEMC, JANA and all dependencies like CLHEP,Geant4,EVIO,ROOT etc

use environmental variable JLAB_VERSION to control version

refer to https://data.jlab.org/drupal/common-environment to see all available version and default packages come with it

Different versions can be installed under the same directory defined by JLAB_ROOT

refer to "JLab Experimental Nuclear Physics Computing" portal at https://data.jlab.org

requirement before installing and using it

Do following before installation, updating and running the code

• check "echo $SHELL" to check if you are using tcsh shell. If it's not your default shell after login, first open a clean terminal and run "tcsh". In general, bash would work, but tcsh is default at jlab and what the instruction uses.

• clean your env variables. For example, remove your environment variable setup in your login script like .cshrc and .login or disable them temporally by "mv .cshrc cshrc" and "mv .login login". This is to avoid conflict from other software environment variables. Vice versa, don't put our environment variables into your login script either, set it up every time you login a terminal instead

• If you are running it in graphical mode on remote machines, make sure to turn on X11 forwarding by "ssh -X" or "ssh -Y" when connecting to remote machines. If you local computer is windows, you need to turn on X11 forwarding in putty's option and have a Xwindow server like Xming or VcXsrv running. test if "xclock" or "xterm" will work first

pre-compiled installation

on ifarm and any jlab internal machine

(as in 2017/05)

The official installation in jlab ifarm and any jlab internal computers is at /group/solid/apps/jlab_root, you can just use them and no need to install again

(additional requirement for graphic mode)
If you want to run it on ifarm in graphic mode, see help at [graphic mode on ifarm] first. 
If you want to run it on ifarm in batch mode without graphic, simply ssh into ifarm, then go to next step
if you can't access ifarm, ask jlab computer center help@jlab.org to make sure your account is allowed on ifarm

on virtual machine

here is a virtual machine to use (jlab account is needed for download)

The virtual machine file (CentOS 6.8) are
http://www.phy.duke.edu/~zz81/vm/CentOS_x86_64_20161121.tgz (vmware)
http://www.phy.duke.edu/~zz81/vm/CentOS_x86_64_20161121.ova (virtualbox)

The jlab_framework file including JLAB_VERSION=1.0,1.1,1.2,1.3
http://www.phy.duke.edu/~zz81/package/jlab_framework_20160608.tgz  

• How to use it
  • Get the virtual machine file first. It's about 5GB and will become about 11GB uncompressed. Your host system need to have at least 2GB mem and be a 64 bit system. vmware is recommended as it is used to build the virtual machine and you can download free vmplayer [1] to run the virtual machine on linux or windows. If you are on Mac or you just prefer it, you can use virtualbox [2] to import the ova file to run the virtual machine. (the ova file is created by ovftool [3] and by "ovftool name.vmx name.ova")
  • The guest system is CentOS x86_64. both "root" and user "jlab" password are "111111".
  • Enter the virtual machine, login as user "jlab", then "cd /home/jlab/", then download the jlab_framework file and extract it at home dir. You can see the framework is installed at /home/jlab/apps/jlab_root

• note
  • If you are using a linux host, sometimes vmplayer doesn't compile on it due to lack of kernel support, try google it and downgrade your kernel to an older working one, or try virtualbox
  • The virtual machine file is relative stable while jlab_framework file will be updated once new release is available.
  • If you have downloaded the virtual machine before, just update the OS to latest one by using yumex (be careful when updating kernel as new kernels may make vmware-tool stops working and you lose fast graphic,so don't update kernel unless you have special reasons), then download the framework again.
  • If the framework is outdated either send a request to zwzhao at jlab.org, or you can do a clean installation according to Installation_of_framework#local_installation_from_source.

on Mac

Download gemc dmg image here https://gemc.jlab.org/gemc/html/downloads.html, then install like an app

Then you need get existing detector file or build your own

run gemc like this "/Applications/gemc-version.app/gemc.app/Contents/MacOs/gemc.command [options] [gcard]" after replace version with your downloaded version number

local installation from source

A local installation uses full power of 3D rendering and is best for the interactive mode

• support version and default operating system
  • Even though it has been tested on different operating system, due to limited manpower, only the default systems following jlab ifarm are fully supported
    • 1.0, CentOS6.2_x86_64, use system pre-installed qt4
    • 1.1, CentOS6.2_x86_64, use system pre-installed qt4
    • 1.2, CentOS6.5_x86_64, uses download binary qt5 (doesn't work on CentOS6.2_x86_64 any more)
    • 1.3, CentOS6.5_x86_64, uses download binary qt5
    • 2.0, CentOS7.2.1511_x86_64, uses download binary qt5 (doesn't work on CentOS6.5_x86_64 any more)
    • devel, CentOS7.2.1511_x86_64, uses download binary qt5 (doesn't work on CentOS6.5_x86_64 any more)
  • Other clone systems like RHEL and Scientific Linux should work without no problem. Similar system like Fedora may work also, but need some tweaking, Ubuntu would need more tweaking

• prepare for installation
  • check your system version by "more /etc/redhat-release"
  • on RHEL/CentOS/SL, turn on EPEL repo by following instruction here and then rpmfusion repo by following instruction here because some packages are only available from this repo. (Warning: DON'T update package "cfengine" after you turn on this repo on a jlab level 2 system, it will replace a customized jlab version)
  • on Fedora, turn on rpmfusion repo by following instruction here
  • check if all general required packages are installed, use "yum install scons gcc-c++ gcc-gfortran mysql mysql-devel libX11-devel mesa-libGLU-devel libXt-devel libXmu-devel libXrender-devel expat-devel libXpm-devel libXft-devel libAfterImage libAfterImage-devel" as root, it will check and install any missing ones.
  • (only need for 1.0 and 1.1) check if all required QT packages are installed, use "yum install qt qt-devel qtwebkit qtwebkit-devel qt-x11 qt-mysql" as root
  • (for JLAB_VERSION <=1.3) use "cmake --version" to check if cmake version >= 2.8, if not, update it with yum. If your system doesn't have a default cmake 2.8 version, try to install "cmake28" and "ln -s /usr/bin/cmake28 /usr/local/bin/cmake" to use it as default. On ifarm, do this "setenv PATH /apps/cmake/bin/:{$PATH}" to use a existing one.
  • (for JLAB_VERSION >=2.0) use "cmake --version" to check if cmake version >= 3.3, if not, update it with yum. If your system doesn't have a default cmake 3.3 version, try to install "cmake3" and "ln -s /usr/bin/cmake3 /usr/local/bin/cmake" to use it as default. On ifarm, do this "setenv PATH /apps/cmake/bin/:{$PATH}" to use a existing one.

• installation command and comment

mkdir your_installation_path               (for example $your_work_dir/apps/jlab_root)
setenv JLAB_ROOT your_installation_path      
setenv JLAB_VERSION version_of_your_choice
cd $JLAB_ROOT
wget http://www.jlab.org/12gev_phys/packages/sources/ceInstall/ceInstall_$JLAB_VERSION.tar.gz
tar -zxpvf ceInstall_$JLAB_VERSION.tar.gz
source $JLAB_ROOT/$JLAB_VERSION/ce/jlab.csh (this will initializes the env and shows package installation status)
cd $JLAB_VERSION/install
edit file "get_coptions" to replace "http://www.jlab.org/12gev_phys/packages/sources" with "https://www.jlab.org/12gev_phys/packages/sources" (for JLAB_VERSION <=1.1)
(run the go* below in the right order to install, each step can repeated if any interruption or failure happens) 
./go_mysql
./go_qt4                (for JLAB_VERSION <=1.1, it uses system qt4)
./go_qt                 (for JLAB_VERSION >=1.2, it will download binary qt5 and you need to install it manually by following instruction)
./go_clhep
./go_xercesc
./go_geant4     
./go_sconsscript
./go_evio
./go_ccdb                (for JLAB_VERSION >= 1.2)
./go_mlibrary            (for JLAB_VERSION >= 2.0)
./go_gemc
./go_root
./go_gemc_evio2root      (for JLAB_VERSION = 1.0)
./go_banks               (for JLAB_VERSION >= 1.1)
./go_jana                (for JLAB_VERSION >= 1.1)

(All packages should install without manual input except qt, so install qt first,then modify and use "go_all" to install all other packages at once if you are confident they won't fail)

• Reference
  • the general installation instruction https://www.jlab.org/12gev_phys/packages/sources/ceInstall
  • the CLAS note [4]

expert info

• go_* script use web download and require access to http://www.jlab.org/12gev_phys/packages/sources/ (/site/www/html/12gev_phys/packages/sources)
• the version of all software is listed at $JLAB_ROOT/$JLAB_VERSION/ce/versions.env
• location for package source repository
  • ceInstall https://github.com/JeffersonLab/ceInstall (private), (https://phys12svn.jlab.org/repos/ceInstall old location)
  • scons_bm svn https://github.com/maureeungaro/scons_bm
  • gemc 2.3 and beyond https://github.com/gemc
  • gemc new releases https://github.com/gemc/releases
  • gemc old releases 2.0-2.2 https://phys12svn.jlab.org/repos/gemc
  • gemc 1.x https://clas12svn.jlab.org/repos/clas12/gemc/tags/
  • banks https://github.com/maureeungaro/banks

• how to use "devel" version

You can just install devel version like a regular version after "setenv JLAB_VERSION devel"
But packages in devel version can change often, (not like a production version which will be kept unchanged once released)
If only a sub-packages changed, you can just use its relevant go_* script to update it. If it's dependence gets updated also, you need to update all of them in  the right order.
In installation steps, the packages are installed in the order of their dependence.
For example, when a new gemc based on a new geant4 version is updated, you source the environment and do go_geant4, then go_gemc.
Another example, after updating gemc, you need to update (which can be simple recompile) banks by go_banks
If you missed a few round of update, just do go_all_devel to update all.
Before updating anything, it's better to go to $JLAB_SOFTWARE and move the old version into a backup copy, just in case the new version has problem.

• test devel GEMC by dropping into an existing installation of the framework

 some time you want to test a devel GEMC version with an existing installation of the framework and it may work if this GEMC is not very different from installed version.
 >>>>>> source your env script for the framework
 >>>>>> cd $GEMC/../
 >>>>>> mkdir devel
 >>>>>> cd devel
 >>>>>> git clone https://github.com/gemc/source
 >>>>>> git clone https://github.com/gemc/api
 >>>>>> ln -s api/perl io
 >>>>>> cd ../
 >>>>>> mv $GEMC_VERSION $GEMC_VERSION\_old
 >>>>>> ln -s devel $GEMC_VERSION   
 >>>>>> cd $GEMC_VERSION/source
 >>>>>> scons OPT=1 LIBRARY="shared"
 >>>>>> Then recompile your own code to use the new libgemc.so if you use GEMC as lib like "eic_gemc" or "solid_gemc"

test after installation

After installation, go to a new and clean terminal, setup environment variable to prepare to run the framework

setenv JLAB_ROOT your_installation_path
setenv JLAB_VERSION version_of_your_choice
source $JLAB_ROOT/$JLAB_VERSION/ce/jlab.csh (this will show you all packages are installed)

Then verify your installation of GEMC

gemc     (this will open its graphic mode to thus verify your installation)