# Installing LArSoft and its dependencies

The LArSoft toolkit and its dependencies are distributed by Fermilab's
SciSoft team.  Although generally packaged as Docker images for PPS
studies, it can be helpful to access LArSoft software outside of a
container.

Fermilab is in the process of adopting Spack's package distribution
model.  However, until that migration is effected, the LArSoft
software is obtained by using Fermilab's Unix Product Support (UPS)
system.

## Creating the UPS area (do once)

Your UPS area is a directory where you will install all of the LArSoft
products.  As the total size of the products amounts to over 10 GB, it
is advisable for your UPS area to reside in some type of "scratch"
space.

To create your UPS area, execute the following instructions (the
`pullProducts` command can take up to 10 minutes to complete,
dependending on your network connection):

```console
$ mkdir <products directory>
$ curl -O https://scisoft.fnal.gov/scisoft/bundles/tools/pullProducts
$ chmod +x pullProducts
$ ./pullProducts -r <products directory> <os> larwire-v1_04_00 e19 prof
```

The following operating systems (i.e. `<os>`) are supported:

- `slf7` (Scientific Linux 7)
- `u18` (Ubuntu 18.04 LTS)
- `u20` (Ubuntu 20.04 LTS)

## Setting up the UPS environment (each time)

With LArSoft installed in your UPS area, you need to setup the
computing environment to access the products in that area--you will do
this for each shell that needs to access it.

```console
$ source <products directory>/setup
$ setup larwirecell v09_02_03 -q e19:prof
```

Once `larwirecell` has been setup, the environment is ready for
building and running any `larwirecell`/`wirecell` code.  To verify a
correctly setup environment, you should see similar printouts when
typing the following commands:

```console
$ echo $SPDLOG_INC
<products directory>/spdlog/v1_8_2/Linux64bit+3.10-2.17-e19-prof/include
$ which g++
<products directory>/gcc/v8_2_0/Linux64bit+3.10-2.17/bin/g++
```

## Building from source

Building from source is not generally recommended as it takes
substantial time to build all products required by
`wire-cell-gen-kokkos`.  However, when required, it can be done using
the following

```console
$ mkdir <build dir>
$ cd <build dir>
$ curl -O https://scisoft.fnal.gov/scisoft/bundles/tools/buildFW
$ chmod +x buildFW
$ ./buildFW [-F] -b e19 -t <products directory> <spec> larwire-v1_04_00
```

where specifying `-F` forces the build script to build from source
(i.e. *not* download) all products not already present in your
products directory.

The following values for `<spec>` are supported:

- `prof` - optimized build using the flags `-g -O3`
- `debug` - no optimization, built with `-g -O0` - best used for debugging programs

The behavior of `buildFW` can be confusing.  Although it may be
desirable to build from source some components of the `larwire` stack,
building (e.g.) GCC or ROOT from scratch is very time-consuming.  For
that reason, it is recommended that you place all products in your
product directory that you do not want to rebuild.  All products
that you want to rebuild should be relocated to a different directory.
