Introduction

Overview

Teaching: 5 min
Exercises: 0 min

Questions

• How can I set easily set up eic-shell to develop and compile parts of the ePIC software stack`?

Objectives

• Download the drich-dev environment.

As usual, we start with

./eic-shell
source /opt/detector/epic-nightly/setup.sh

Now download drich-dev:

git clone https://github.com/eic/drich-dev.git

Reminder: If you expect to contribute to a repository, you must have developer privileges, for the most part by being a member of the EIC organization and becoming a member of the ePIC devs team. In that case, it is beneficial to upload your ssh credentials to github and use the ssh clone interface by replacing https://github.com/with git@github.com:, i.e.

git clone git@github.com:eic/drich-dev.git

To do so using the docker version, it is for this version best to issue git commands from outside eic-shell so that your credentials are known.

Now just initialize the environment and we are ready to install a repository from scratch in the next lesson:

cd drich-dev
source environ.sh

Some parameters you can set:

• $BUILD_NPROC controls the number of parallel threads during building. By default it will use as many threads as there are cores, while memory-hungry builds may be done on a single thread.
• $EIC_SHELL_PREFIX is the local installation location for all built modules, byt default ./prefix

Homework:

Explore this directory and familiarize yourself with the documentation. There are many helpers in here to run simulations, visualize gemetries etc. But in this tutorial, we will focus exclusively on build.sh

Key Points

• All our packaes are in public repositories. The drich-dev environment provides helpers to streamline building and setting the PATHs just right.

Building an ePIC Package

Overview

Teaching: 15 min
Exercises: 0 min

Questions

• How can I modify and build parts of the ePIC software stack inside eic-shell?

Objectives

• Download and build a package, set up the environment to use it.

Begin by obtaining the code of the repository you want to compile:

git clone git@github.com:eic/afterburner.git

Installing is now as easy as:

./build.sh afterburner

Note: You most likely will want to develop packages like epic, eicrecon, … Due to current technical issues, full compilation from scratch of these in the docker version of eic-shell on a Silicon Mac takes 15+ minutes, too much for this tutorial.

It is instructive to follow the steps that this script takes:

# ./build.sh afterburner
CMAKE COMMANDS:
========================================

[ generate buildsystem ]
cmake -S afterburner/cpp -B afterburner/build -DHEPMC3_ROOTIO=ON -DCMAKE_INSTALL_PREFIX=/Users/eickolja/eic/drich-dev/prefix

[ build ]
cmake --build afterburner/build -j4

[ install ]
cmake --install afterburner/build

========================================

This tells you almost everything the script does, and in fact if you make changes to a file or two, it can make sense to use these commands directly instead of running through the makefile generation step again.

[Add std::cout<<"Hello world 1" << std::endl; to afterburner/cpp/abconv/main.cc]
time ./build.sh afterburner

Then try

[Change "Hello world 1" to "Hello world 2"]
time cmake --build afterburner/build -j4 && cmake --install afterburner/build

Also, note in the above the appearance of -DHEPMC3_ROOTIO=ON. By default, build.sh can build anything that relies on the “cmake, make, make install” paradigm, but for some named packages, options can be added and changed by default, explore build.sh to learn more!

Finally, it is sometimes necessary, and it never hurts, to update the environment again, and we can learn from its output as well.

source environ.sh

Homework:

Install any of epic, EICrecon, etc. Make a change, recompile, see what happens! Suggestions: Add simple text output, change the parameters of a detector subsystem and look for the consequences of such a change, like overlaps. Some packages:

git clone git@github.com:eic/epic.git
git clone git@github.com:eic/irt.git
git clone git@github.com:eic/EDM4eic.git
git clone git@github.com:eic/EICrecon.git

You can also explore how this works with external packages, such as:

git clone https://github.com/AIDASoft/DD4hep.git
git clone https://github.com/eic/EDM4eic

Some repositories have changed capitalization over time, you may need to rename them for build.sh to pick them up. Please report/file an issue/contact the Mattermost helpdesk, if you come across such instances.

Key Points

• Any downloaded ePIC software package can be installed using build.sh

Quick Tour of the epic and eicrecon repositories

Overview

Teaching: 15 min
Exercises: 0 min

Questions

• Where does some relevant code live, and what does it look like?

Objectives

• Explore a few key repositories.

A deep, interactive dive into either package would exceed the time frame of this tutorial. Some of it will be covered in the following tutorials. While build times, especially for eicrecon on a Silicon Mac are somewhat prohibitive, you know now how to do it. For any interactive work later today, it is strongly recommended to use eic-shell either on an intel machine, or at least start the build right now. Note that only the initial build will take that long, changes to a few files generally don’t trigger the rebuild of an entire package.

Detector geometry is handled by the epic package. Sub-detector cml filese are in epic/compact, their corresponding C++ (Geant4) implementations in epic/src

Configurations (like bruycecanyon, craterlake, customized ones for special purposes are in the epic top level directory, but instead of making changes here, add to or edit the YAML files in epic/configurations, rebuilding the package will auto-generate the composite configurations.

Key Points

• The [epic repository])(https://github.com/eic/epic) contains the detector geometry descriptions. The eicrecon repository handles digitization, reconstruction, and pre-analysis such as jet-finding.