# Using EICrecon with `eic-shell`


The EIC environment `eic-shell` is a singularity/docker container with a
curated selection of software components. It is the recommended way to use
`eicrecon` as it already has all of the dependencies compiled with matching
version numbers. This requires either singularity or docker to be installed
on your local machine. Below are some quick start instructions for using
Singularity.

## Quick start for eic-shell
~~~bash
mkdir ~/eic
cd ~/eic

curl --location https://get.epic-eic.org | bash
./eic-shell
~~~~

_n.b. if on the JLab CUE you should do module load singularity/3.9.5 first_

Full tutorials on setting up you environment with `eic-shell` can be found here:
- [EIC Tutorial: Setting Up Your Environment](https://eic.github.io/tutorial-setting-up-environment/index.html)
- [`eic-shell` video tutorial](https://www.youtube.com/watch?v=Y0Mg24XLomY)



## Using the `eic-shell` environment

Once inside the `eic-shell` you should source the geometry setup script since
this is not done by default. Then, clone the `EICrecon` repository and build it:

```bash
source /opt/detector/epic-main/bin/thisepic.sh

git clone https://github.com/eic/EICrecon
cmake -S EICrecon -B build
cmake --build build --target install -- -j8
```

Assuming all goes well, `EICrecon` will be installed in the _EICrecon_ directory.
To set you environment up to use it, source the setup script generated by the build:
~~~bash
source EICrecon/bin/eicrecon-this.sh
~~~

Test the installation by running the _eicrecon_ executable with no arguments:

~~~bash
eicrecon

Usage:
    eicrecon [options] source1 source2 ...

Description:
    Command-line interface for running JANA plugins. This can be used to
    read in events and process them. Command-line flags control configuration
    while additional arguments denote input files, which are to be loaded and
    processed by the appropriate EventSource plugin.

Options:
   -h   --help                  Display this message
   -v   --version               Display version information
   -c   --configs               Display configuration parameters
   -l   --loadconfigs <file>    Load configuration parameters from file
   -d   --dumpconfigs <file>    Dump configuration parameters to file
   -b   --benchmark             Run in benchmark mode
   -L   --list_factories        List all the factories without running
   -Pkey=value                  Specify a configuration parameter

Example:
    eicrecon -Pplugins=plugin1,plugin2,plugin3 -Pnthreads=8 inputfile1.txt
~~~

At this point, you can [add a new factory (i.e. algorithm)](/howto/add_factory.md).
