Getting Started - A guided tour¶
Welcome new user! This page should help you get up to speed and get the core of IceTray software installed, compiled and running on your system. Comments and questions are welcome on #software channel of our Slack instance.
This process involves:
Checking various prerequisites on your machine and verifying that they work
Obtaining the external tools that the code requires to build
Checking out some code
Building the software
Running the software
Prerequisites¶
While several operating system are supported, there are a few minimum requirements needed to install, compile and run IceTray.
Operating System¶
IceCube focuses on just a few supported platforms: RedHat, Ubuntu, and OSX. We welcome commits from collaborators necessary to run on other unsupported platforms, but can’t guarantee test resources will be dedicated to them.
gcc version 5 or higher
Xcode version 6 or higher
clang version 3.6 or higher
We actively test on a number of platforms. We highly recommend Ubuntu, it contains many useful packages, it’s free, well-supported and has a wide user-base in IceCube. If you choose Ubuntu and have problems, please ask questions on Slack.
Check Supported Platforms for the operating system that you are using. If provided, download and run the script for your operating system. These scripts will ensure that you have the necessary system packages installed.
photospline¶
photospline is no longer included as part of IceTray, but developed
independently. Unless you are using CVMFS, it must be installed before building IceTray.
$ git clone https://github.com/icecube/photospline.git
$ mkdir photospline/build
$ cd photospline/build
$ cmake ..
$ make -j$(nproc)
$ sudo make install
For detailed installation instructions see https://github.com/icecube/photospline.
CVMFS¶
If you are running on a cluster, CVMFS is available to manage software installation for you. It provides all of the standard software used in IceCube.
Checking out some code¶
Now you are ready to check out a release of IceTray. Please feel free to replace the version used below with the latest version found at https://github.com/icecube/icetray/
Check out a release into a workspace¶
Generally, it is recommended that you make a single directory as your workspace, with separate subdirectories for source code and another to hold the resulting build objects (libraries and executables). This will keep the source code from the code repository separate from the files created during the build process.
Execute:
$ mkdir -p ~/i3/icetray
$ cd ~/i3/icetray
$ git clone https://github.com/icecube/icetray.git src
(...produces lots of output...)
$ mkdir build
You now have a directory filed with:
build/ src/
Your build/ directory is empty, while your src/ directory contains the
source for all projects in the IceTray release:
$ ls src/
CMakeLists.txt
dataclasses/
icetray/
dataio/
...
You are now ready to build!
Build the Software¶
Building the software is broken up into two parts:
Generating local Makefiles using the
cmakeprogram (see CMake: icetray’s build system)Building libraries and binary executables with
make.
Running cmake¶
We use the command cmake to build the software:
$ cd ~/i3/icetray/build
$ cmake ../src
This will populate your local build directory with directories and local build files:
-- IceCube Configuration starting
--
-- OSTYPE = Linux
-- OSVERSION = 4.15.0-70-generic
-- ARCH = x86_64
-- BUILDNAME = Linux-4.15.0-70-generic/x86_64/gcc-7.4.0
-- TOOLSET = gcc-7.4.0/x86_64/RelWithAssert
-- HOSTNAME = finn
-- CMake path = /usr/bin/cmake
-- CMake version = 3.10.2
...
-- Setting compiler, compile drivers, and linker
-- Generating env-shell.sh
-- Generating icetray-config
-- Configuring 'gfilt' STL decryptor
-- Configuring done
-- Generating done
-- Build files have been written to: /home/olivas/icecube/combo/trunk/build
You’re ready to build.
Build it!¶
In your ~/i3/icetray/build directory execute:
$ make
You will see the build progress:
[ 0%] Checking build against environment
[ 0%] Built target env-check
[ 1%] Linking CXX shared library ../lib/libserialization.so
[ 2%] Built target serialization
Scanning dependencies of target icetray
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/icetray/PythonModule.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/icetray/OMKey.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/modules/AllParametersModule.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/modules/ContextFreeServiceTestModule.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/modules/MaintainInitialValuesModule.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/OMKey.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/I3Tray.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/I3Module.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_char.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_double.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_I3Frame_Stream.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_int.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_map_int_int.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_map_omkey_int.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_omkey.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_pairs.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_sort.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_string.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_ulong.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_unsigned.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_vector_int.cxx.o
[ 2%] Building CXX object icetray/CMakeFiles/icetray.dir/private/pybindings/std_cont_pod/std_cont_pod_vector_string.cxx.o
[ 2%] Linking CXX shared library ../lib/libicetray.so
[ 7%] Built target icetray
Scanning dependencies of target dataclasses
...
Scanning dependencies of target wavedeform
[100%] Building CXX object wavedeform/CMakeFiles/wavedeform.dir/private/wavedeform/I3Wavedeform.cxx.o
[100%] Linking CXX shared library ../lib/libwavedeform.so
[100%] Built target wavedeform
[100%] Linking CXX shared module ../lib/icecube/wavedeform.so
[100%] Built target wavedeform-pybindings
Scanning dependencies of target wavereform
[100%] Building CXX object wavereform/CMakeFiles/wavereform.dir/private/wavereform/I3Wavereform.cxx.o
[100%] Building CXX object wavereform/CMakeFiles/wavereform.dir/private/wavereform/I3WavereformFunctions.cxx.o
[100%] Building CXX object wavereform/CMakeFiles/wavereform.dir/private/wavereform/I3LaunchSelector.cxx.o
[100%] Linking CXX shared library ../lib/libwavereform.so
[100%] Built target wavereform
Scanning dependencies of target wavereform-pybindings
[100%] Building CXX object wavereform/CMakeFiles/wavereform-pybindings.dir/private/pybindings/module.cxx.o
[100%] Linking CXX shared module ../lib/icecube/wavereform.so
[100%] Built target wavereform-pybindings
Scanning dependencies of target wimpsim-reader
[100%] Building CXX object wimpsim-reader/CMakeFiles/wimpsim-reader.dir/private/wimpsim-reader/I3WimpSimReader.cxx.o
[100%] Building CXX object wimpsim-reader/CMakeFiles/wimpsim-reader.dir/private/wimpsim-reader/WimpSimTools.cxx.o
[100%] Linking CXX shared library ../lib/libwimpsim-reader.so
[100%] Built target wimpsim-reader
CMake nicely displays a fraction complete so you can follow the build to completion.
Rsync the test-data¶
If you’re not using a CVMFS toolset on a cluster, sync the test-data to your local test-data directory ($I3_TESTDATA):
$ make rsync
This will download >1GB of data used by testing and example scripts. If you already have them, this command will simply make sure your copy of test-data is up to date.
Using the software¶
Once compiled, you can explore some of the provided example scripts. Each project typically has several examples. This is a simple tour.
Loading the environment¶
This part is straightforward. Assuming that you are starting from a fresh shell (one that contains no information about your any IceCube workspace), you should read one of these files into your workspace. Use the:
$ ./env-shell.sh
which again should produce output roughly like this:
************************************************************************
* *
* W E L C O M E to I C E T R A Y *
* *
* Version combo.trunk r177871 *
* *
* You are welcome to visit our Web site *
* http://icecube.umd.edu *
* *
************************************************************************
Icetray environment has:
I3_SRC = /home/olivas/icecube/combo/trunk/src
I3_BUILD = /home/olivas/icecube/combo/trunk/build
I3_TESTDATA = /home/olivas/icecube/test-data/trunk
Python = 3.6.9
This has setup up your PATH, LD_LIBRARY_PATH and other environment variables so that you are now ready to run IceTray python scripts and executables. This file should work equally well for bash-like and csh-like shells.
A few standard environment variables are also set (and often referred to in scripts, code, etc):
I3_SRC - Pointer to your local src area, where you checked out the source code via git.
I3_BUILD - Pointer to your local build area, where you build IceTray libraries and executables.
I3_TESTDATA - Pointer to your local test-data area, that contains data necessary for testing.
If you load your environment twice, you’ll be warned:
$ ./env-shell.sh
****************************************************************
You are currently in a shell with an Icetray environment loaded.
Please exit the current shell and re-run ./env-shell.sh from a clean shell.
****************************************************************
Environment not (re)loaded.
This is not a fatal situation and your PATH and LD_LIBRARY_PATH have not modified again. Still there are probably some ways to get into trouble (if your toolset has changed since the last time you loaded your environment, and you try to run a binary…). You are still better off starting a new shell before you reload these scripts.
