#pueoBuilder Installation Tutorial

This tutorial will guide you through the process of building the tools included in pueoBuilder from scratch, including the prerequisites and any environment variables that you will need to set. This sort of thing is always a bit of a nightmare process for me, so hopefully this guide can help you skip some of the frustration that I ran into. I did not have root acces on the system I was building on, so the instructions below are what I had to do to get things working with local installations. If you have root access, then things might be a bit easier. For reference I'm working on CentOS 7, other operating systems might have different problems that arise. 

##Prerequisites
As far as I can tell, the prerequisites that need to be built first are:

-cmake 3.21.2 (I had problems with 3.11.4)
-gcc 11.1.0 (9.X will not work)
-fftw 3.3.9
-gsl 2.7.1 (for ROOT)
-ROOT 6.24.00

###CMake
You can download the source files for CMake here: https://cmake.org/download/. Untar the source files with:

    tar -xzvf cmake-3.22.1.tar.gz

Compiling CMake is as easy as following the directions on the website: https://cmake.org/install/, but since we're doing a local build, we'll use the `configure` script instead of the listed `bootstrap` script. As an example, suppose that I downloaded the above tar file to `/scratch/wluszczak/cmake`: 

    mkdir install
    cd cmake-3.22.1
    ./configure --prefix=/scratch/wluszczak/cmake/install
    make
    make install

You should additionally add this directory to your `$PATH` variable:

    export PATH=/scratch/wluszczak/cmake/install/bin:$PATH

To check to make sure that you are using the correct version of CMake, run:

    cmake --version

and you should get:

    cmake version 3.22.1

    CMake suite maintained and supported by Kitware (kitware.com/cmake).

### gcc 11.1.0

Download the gcc source from github here: https://github.com/gcc-mirror/gcc/tags. I used the 11.1.0 release, though there is a more recent 11.2.0 release that I have not tried. Once you have downloaded the source files, untar the directory:

    tar -xzvf gcc-releases-gcc-11.1.0.tar.gz

Then install the prerequisites for gcc:
    
    cd gcc-releases-gcc-11.1.0
    contrib/download_prerequisites

One of the guides I looked at also recommended installing flex separately, but I didn't seem to need to do this, and I'm not sure how you would go about it without root priviledges, though I imagine it's similar to the process for all the other packages here (download the source and then build by providing an installation prefix somewhere)

After you have installed the prerequisites, create a build directory:

    cd ../
    mkdir build
    cd build

Then configure GCC for compilation like so:

    ../gcc-releases-gcc-11.1.0/configure -v --prefix=/home/wluszczak/gcc-11.1.0 --enable-checking=release --enable-languages=c,c++,fortran --disable-multilib --program-suffix=-11.1

I don't remember why I installed to my home directory instead of the /scratch/ directories used above. In principle the installation prefix can go wherever you have write access. Once things have configured, compile gcc with:

    make -j $(nproc)
    make install

Where `$(nproc)` is the number of processing threads you want to devote to compilation. More threads will run faster, but be more taxing on your computer. For reference, I used 8 threads and it took ~15 min to finish. 

Once gcc is built, we need to set a few environment variables:

    export PATH=/home/wluszczak/gcc-11.1.0/bin:$PATH
    export LD_LIBRARY_PATH=/home/wluszczak/gcc-11.1.0/lib64:$LD_LIBRARY_PATH

We also need to make sure cmake uses this compiler:

    export CC=/home/wluszczak/gcc-11.1.0/bin/gcc-11.1
    export CXX=/home/wluszczak/gcc-11.1.0/bin/g++-11.1
    export FC=/home/wluszczak/gcc-11.1.0/bin/gfortran-11.1

If your installation prefix in the configure command above was different, substitute that directory in place of `/home/wluszczak/gcc-11.1.0` for all the above export commands. To easily set these variables whenever you want to use gcc-11.1.0, you can stick these commands into a single shell script:

    #load_gcc11.1.sh
    export PATH=/home/wluszczak/gcc-11.1.0/bin:$PATH
    export LD_LIBRARY_PATH=/home/wluszczak/gcc-11.1.0/lib64:$LD_LIBRARY_PATH

    export CC=/home/wluszczak/gcc-11.1.0/bin/gcc-11.1
    export CXX=/home/wluszczak/gcc-11.1.0/bin/g++-11.1
    export FC=/home/wluszczak/gcc-11.1.0/gfortran-11.1

(again substituting your installation prefix in place of mine). You can then set all these environment variables by simply running:
    
    source load_gcc11.1.sh

Once this is done, you can check that gcc-11.1.0 is properly installed by running:

    gcc-11.1 --version

Note that plain old

    gcc --version

might still point to an older version of gcc. This is fine though. 

###FFTW 3.3.9
Grab the source code for the appropriate versino of FFTW from here: http://www.fftw.org/download.html

However, do NOT follow the installation instructions on the webpage. Those instructions might work if you have root privileges, but I personally couldn't seem to to get things to work that way. Instead, we're going to build fftw with cmake. Untar the fftw source files:

    tar -xzvf fftw-3.3.9.tar.gz

Make a build directory and cd into it:
    
    mkdir build
    cd build

Now build using cmake, using the flags shown below. For reference, I downloaded and untarred the source file in `/scratch/wluszczak/fftw/build`, so adjust your install prefix accordingly to point to your own build directory that you created in the previous step.

    cmake -DCMAKE_INSTALL_PREFIX=/scratch/wluszczak/fftw/build/ -DBUILD_SHARED_LIBS=ON -DENABLE_OPENMP=ON -DENABLE_THREADS=ON ../fftw-3.3.9
    make install -j $(nproc)

Now comes the weird part. Remove everything except the `include` and `lib64` directories in your build directory (if you installed to a different `CMAKE_INSTALL_PREFIX`, the include and lib64 directories might be located there instead. The important thing is that you want to remove everything, but leave the `include` and `lib64` directories untouched):

    rm *
    rm -r CMakeFiles

Now rebuild fftw, but with an additional flag:

    cmake -DCMAKE_INSTALL_PREFIX=/scratch/wluszczak/fftw/build/ -DBUILD_SHARED_LIBS=ON -DENABLE_OPENMP=ON -DENABLE_THREADS=ON -DENABLE_FLOAT=ON ../fftw-3.3.9
    make install -j $(nproc)

At the end of the day, your fftw install directory should have the following files:

    include/fftw3.f  
    include/fftw3.f03
    include/fftw3.h  
    include/fftw3l.f03  
    include/fftw3q.f03 
    lib64/libfftw3f.so          
    lib64/libfftw3f_threads.so.3      
    lib64/libfftw3_omp.so.3.6.9  
    lib64/libfftw3_threads.so
    lib64/libfftw3f_omp.so        
    lib64/libfftw3f.so.3        
    lib64/libfftw3f_threads.so.3.6.9  
    lib64/libfftw3.so            
    lib64/libfftw3_threads.so.3
    lib64/libfftw3f_omp.so.3      
    lib64/libfftw3f.so.3.6.9    
    lib64/libfftw3_omp.so             
    lib64/libfftw3.so.3          
    lib64/libfftw3_threads.so.3.6.9
    lib64/libfftw3f_omp.so.3.6.9  
    lib64/libfftw3f_threads.so  
    lib64/libfftw3_omp.so.3           
    lib64/libfftw3.so.3.6.9

Why do we have to do things this way? I don't know, I'm bad at computers. Maybe someone more knowledgeable knows. I found that when I didn't do this step, I'd run into errors that pueoBuilder could not find some subset of the required files (either the ones added by building with `-DENABLE_FLOAT`, or the ones added by building without `-DENABLE_FLOAT`). 

Once fftw has been installed, export your install directory (the one with the include and lib64 folders) to the following environment variable:

    export FFTWDIR=/scratch/wluszczak/fftw/build

Again, substituting your own fftw install prefix that you used above in place of `/scratch/wluszczak/fftw/build`

###gsl 2.7.1
gsl 2.7.1 is needed for the `mathmore` option in ROOT. If you have an outdated version of gsl, ROOT will still compile, but it will skip installing `mathmore` and `root-config --has-mathmore` will return `no`. To fix this, grab the latest source code for gsl from here: https://www.gnu.org/software/gsl/. Untar the files to a directory of your choosing:

    tar -xzvf gsl-latest.tar.gz

For some reason I also installed gsl to my home directory, but in principle you can put it wherever you want. 

    mkdir /home/wluszczak/gsl
    ./configure --prefix=/home/wluszczak/gsl
    make
    make check
    make install

To make sure ROOT can find this installation of gsl, you'll again need to set an environment variable prior to building ROOT:

    export GSL_ROOT_DIR=/home/wluszczak/gsl/
    
I also added this to my $PATH variable, though I don't remember if that was required to get things working or not:

    export PATH=/home/wluszczak/gsl/bin/:$PATH 
    export LD_LIBRARY_PATH=/home/wluszczak/gsl/lib:$LD_LIBRARY_PATH

###ROOT 6.24.00
Download the specific version of ROOT that you need from here: https://root.cern/install/all_releases/

You might need to additionally install some of the dependencies (https://root.cern/install/dependencies/), but it seems like everything I needed was already installed on my system. 

Untar the source you downloaded:
    
    tar -xzvf root_v6.24.00.source.tar.gz

Make some build and install directories:

    mkdir build install
    cd build

Run CMake, but be sure to enable the fortan, mathmore and minuit2 options. For reference, I had downloaded and untarred the source files to `/scratch/wluszczak/root`. Your installation and source paths will be different.

    cmake -DCMAKE_INSTALL_PREFIX=/scratch/wluszczak/root/install/ /scratch/wluszczak/root/root-6.24.00/ -Dfortran=ON -Dminuit2=ON -Dmathmore=ON

Note: if you end up with an error related to compiling XROOTD, then add -Dxrootd=OFF to the original cmake command above.

Then proceed to start the build:

    cmake --build . --target install -j $(nproc)
    

If everything has worked then after the above command finishes running, you should be able to run the following file to finish setting up ROOT:

    source ../install/bin/thisroot.sh

##pueoBuilder
By this point, you should have working installations of CMake 3.21.2, gcc-11.1.0, fftw 3.3.9, and ROOT 6.24.00. Additionally, the following environment variables should have been set:

    export PATH=/scratch/wluszczak/cmake/install/bin:$PATH

    export PATH=/home/wluszczak/gcc-11.1.0/bin:$PATH
    export LD_LIBRARY_PATH=/home/wluszczak/gcc-11.1.0/lib64:$LD_LIBRARY_PATH

    export CC=/home/wluszczak/gcc-11.1.0/bin/gcc-11.1
    export CXX=/home/wluszczak/gcc-11.1.0/bin/g++-11.1
    export FC=/home/wluszczak/gcc-11.1.0/gfortran-11.1

    export FFTWDIR=/scratch/wluszczak/fftw/build

At this point, the hard work is mostly done. Check out pueoBuilder with:

    git clone git@github.com:PUEOCollaboration/pueoBuilder 

set the following environment variables:

    export PUEO_BUILD_DIR=/scratch/wluszczak/PUEO/pueoBuilder
    export PUEO_UTIL_INSTALL_DIR=/scratch/wluszczak/PUEO/pueoBuilder
    export NICEMC_SRC=${PUEO_BUILD_DIR}/components/nicemc
    export NICEMC_BUILD=${PUEO_BUILD_DIR}/build/components/nicemc
    export PUEOSIM_SRC=${PUEO_BUILD_DIR}/components/pueoSim
    export LD_LIBRARY_PATH=${PUEO_UTIL_INSTALL_DIR}/lib:$LD_LIBRARY_PATH

Where $PUEO_BUILD_DIR and $PUEO_UTIL_INSTALL_DIR point to where you cloned pueoBuilder to (in my case, `/scratch/wluszczak/PUEO/pueoBuilder`. Now you should be able to just run:

    ./pueoBuilder.sh

Perform a prayer to the C++ gods while you're waiting for it to compile, and hopefully at the end of the day you'll have a working set of PUEO software. 

##Issues I Ran Into
If you already have an existing installation of ROOT, you may still need to recompile to make sure you're using the same c++ standard that the PUEO software is using. I believe the pre-compiled ROOT binaries available through their website are insufficient, though maybe someone else has been able to get those working. 

If you're running into errors about c++ standard or compiler version even after you have installed gcc-11.1.0, then for some reason your system isn't recognizing your local installation of gcc-11.1.0. Check the path variables ($PATH and $LD_LIBRARY_PATH) to make sure the gcc-11.1.0 `bin` directory is being searched.

If you're running into an error that looks like:
        
    CMake Error: The following variables are used in this project, but they are set to NOTFOUND.
    Please set them or make sure they are set and tested correctly in the CMake files:
    FFTWF_LIB (ADVANCED)

then pueoBuilder can't seem to find your fftw installation (or files that are supposed to be included in that installation), try rebuilding with different flags according to which files it seems to think are missing.

If it seems like pueoBuilder can't seem to find your fftw installation at all (i.e. you're getting some error that looks like `missing: FFTW_LIBRARIES` or `missing: FFTW_INCLUDES`), check the environment variables that are supposed to point to your fftw installation (`$FFTWDIR`) and make sure there are the correct files in the `lib` and `include` subdirectories.