Installing calin

There is more than one way to start using calin on your machine : the easy way, and the hard way. The easy way is to install a pre-built image that runs under Docker, a containerisation (or light-weight virtualisation) platform. The calin Docker image contains all the libraries that it needs to run, so installation is as easy as installing Docker on your system (Linux, Mac, Windows) then downloading (or "pull"ing) the calin image.

The hard way to do the installation is to get the calin source code from github and compile it. The difficulty arises due to all the dependent libraries that need to be installed. Some of these can usually be found in the package manager that comes with your system (apt, macports etc..) but some will have to be installed by hand. In general the recipe for installing calin by source will depend on what system you have, instructions are given below for XXXXXX. Nonetheless there are certain advantages of installing from source, which are discussed below.

In the future it may be possible to combine the ease of installation of Docker with the flexibility of having a non-containerised installation that comes from installing from source (perhaps using RPM, conda or something like that), but I haven't developed this yet - if anyone wants to do so, please let me know.

Installing using Docker

Installing with Docker is incredibly easy.

1. Install Docker on your system, assuming you have the rights to do this. Personally I have tested this on MacOS 10.11.6 with Docker 1.12.0-a, and I am confident that it should work under Linux since Docker is native to Linux.
2. Get the calin image for Docker by running : docker pull llrcta/calin
3. Run calin inside Docker to do something useful, for example analyse a single photo-electron run.

Installing from source

Build using Docker

In some cases you may wish (or need) to build calin from source but may not wish to invest the time in building all the support libraries. For example if you normally use Docker to run the code but you wish to change or customise the code or there may be some problems running the binary on Docker (e.g., older CPU not supported by Docker binary). One option is clone the calin source from GitHub and use Docker to build it into a private container.

1. Install Docker on your system, as described above.

2. Clone the calin Github repository and build it.

   git clone https://github.com/llr-cta/calin.git
   cd calin

3. Build calin into a private container using Docker.

   docker build . --tag calin:test

   This will take a while and will eventually build a container calin:test on your machine which you can use. To test it you can try some of the examples, replacing llrcta/calin:latest by calin:test everywhere in the instructions.

MacOS 10.15 Catalina using MacPorts (tested 2020-01-06)

1. Install required packages from MacPorts.

   port install cmake python37 py37-scipy py37-notebook sqlite3 \
     py37-matplotlib fftw-3 fftw-3-single wget gsl \
     swig3 swig3-python protobuf3-cpp geant4 xercesc3 

2. Download and install the CTA CamerasToACTL package. This step is optional; skipping it will mean calin will not be able to read CTA ZFits data. A slightly modified version, which works under MacOS, can be downloaded from a private GitHub repository (email me for access).

   mkdir mybuild
   cd mybuild
   cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/local ..
   make -j4
   make  install

3. Clone the calin Github repository and build it.

   git clone https://github.com/llr-cta/calin.git
   cd calin
   mkdir mybuild
   cd mybuild
   bash ../configure_macports_py37.sh
   make -j5
   make install

4. Enjoy!

MacOS High Sierra using MacPorts

With High Sierra I recommend installing Geant4 and protobuf3 through MacPorts, which simplifies the installation procedure significantly over that given below for Sierra. I also recommend updating from Python 3.4 to 3.6, although you can choose either.

1. Install required packages from MacPorts.

   port install cmake python36 py36-scipy py36-notebook sqlite3 \
     py36-matplotlib fftw-3 fftw-3-single wget gsl swig protobuf3-cpp geant4 xercesc3 

2. Download and install the CTA CamerasToACTL package. This step is optional; skipping it will mean calin will not be able to read CTA ZFits data. This can be downloaded from the CTA SVN repository (under ???) or from a private GitHub repository (email me for access).

   mkdir mybuild
   cd mybuild
   cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/local ..
   make -j4
   make  install

3. Clone the calin Github repository and build it.

   git clone https://github.com/llr-cta/calin.git
   cd calin
   mkdir mybuild
   cd mybuild
   bash ../configure_macports_py36.sh
   make -j5
   make install

4. Enjoy!

MacOS Sierra using macports

1. Install required packages from MacPorts.

   port install cmake python34 py34-scipy py34-notebook sqlite3 \
     py34-matplotlib fftw-3 fftw-3-single wget gsl swig xerces3

2. Download and install the Google protobuf3 package; as of April 2017 the package that comes with macports protobuf3-cpp (v3.0.0) does not work well with Sierra, it generates a huge number of warnings. If this version is eventually upgraded by macports it could be installed and this step could be skipped.

   wget https://github.com/google/protobuf/releases/download/v3.2.0/protobuf-cpp-3.2.0.tar.gz
   tar zxvf protobuf-cpp-3.2.0.tar.gz
   cd protobuf-3.2.0
   ./configure --prefix=/usr/local/
   make -j5
   sudo make install

3. Download and install the CTA CamerasToACTL package. This step is optional; skipping it will mean calin will not be able to read CTA ZFits data. This can be downloaded from the CTA SVN repository (under ???) or from a private GitHub repository (email me for access).

   mkdir mybuild
   cd mybuild
   cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/local ..
   make -j4
   make  install

4. Download and install GEANT-4. This step is optional and is only useful if you want to do shower simulations with calin.

   wget http://geant4.cern.ch/support/source/geant4.10.02.p02.tar.gz
   tar zxvf geant4.10.02.p02.tar.gz
   cd geant4.10.02.p02
   mkdir mybuild
   cd mybuild
   cmake -DGEANT4_INSTALL_DATA=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..
   make -j5
   sudo make install

5. Clone the calin Github repository and build it.

   git clone https://github.com/llr-cta/calin.git
   cd calin
   mkdir mybuild
   cd mybuild
   bash ../configure_macports.sh
   make -j5
   make install

6. Enjoy!