quickstart.mdx

---
title: "Quick-start Guide"
---


## Prerequisites

We assume that you are somewhat familiar with:
- git and gitlab (https://eicweb.phy.anl.gov)
- working in the terminal over ssh
- cmake, C++, python, and shell scripting


This tutorial requires that [singularity](singularity) is installed 
on the local system. 
Singularity can be [downloaded here](https://sylabs.io/guides/3.7/user-guide/quick_start.html) -- 3.7 being the 
most recent version as of January 2021.

*For an optimal experience, we strongly recommend you to use singularity 3 or later for this tutorial. 
Use (very) old versions of singularity (e.g. 2.6.x) at your own risk!*
 
## The EIC Software Container (jug_xl)

### Step 1: Create a local directory that you want to work in, e.g., `~/eic`
```bash
mkdir ~/eic
cd ~/eic
```

### Step 2: Deploy the containerized environment and launch a shell

Execute the following line in your terminal to setup your environment in your sandbox
directory. This will install the latest stable container and place a script called
`eic-shell` in the top-level directory. This script will load the environment for you.

```bash
curl https://eicweb.phy.anl.gov/containers/eic_container/-/raw/master/install.sh | bash
```

Now you can launch a shell in our development environment:
```bash
./eic-shell
```

### Step 3: Clone the repos

There are 2 repos you need:
* IP6 (IP-specific components)
* Athena detector

```bash
git clone https://eicweb.phy.anl.gov/EIC/detectors/athena.git
git clone https://eicweb.phy.anl.gov/EIC/detectors/ip6.git
ln -s ../ip6/ip6 athena/ip6
```

In part 1 of the tutorial we will be mostly using files from a tutorial repo. 
Later on, we will com back to these detector repositories.

### Step 4: Looking at the geometry

Before moving on to part 1, let's generate the geometry in a root file:


```bash
cd athena
source /opt/detector/setup.sh
dd_web_display --export athena.xml
```

This will generate the file `detector_geometry.root`, which you should copy to your local machine.
Then open the [web viewer](https://eic.phy.anl.gov/geoviewer/), click on the `...` and open the local root file.

Or if you want to skip this just 
[click here to view the latest detector](https://eic.phy.anl.gov/geoviewer/index.htm?file=https://eicweb.phy.anl.gov/api/v4/projects/473/jobs/artifacts/master/raw/geo/detector_geo_full.root?job=report&item=default;1&opt=clipxyz;transp30;zoom75;ROTY290;ROTZ350;trz0;trr0;ctrl;all&).

(Note: the `source /opt/detector/setup.sh` command adds the Athena detector plugins that ship
with the jug_xl container to your environment.)