.. SPDX-FileCopyrightText: 2024 The IceTray Contributors .. .. SPDX-License-Identifier: BSD-2-Clause Getting Started - A guided tour =============================== .. highlight:: console 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 :ref:`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, :ref:`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 ``cmake`` program (see :ref:`cmake`) * 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.