Building an external package
============================

Prerequisites
-------------

Build and install **PandaRoot**. A ``PandaRootConfig.sh`` script will be created in the course of the installation. It  
exports the **PANDAROOTPATH** variable, which is set to **PandaRoot**'s installation directory, which contains the 
include and the lib folder, which are required for compiling and linking against **PandaRoot**. Additionally, the include 
paths of **PandaRoot** are exported. This is currently necessary, as the include paths is not a singular directory 
under the installation directory pointed to by **PANDAROOTPATH**, but a "complex" tree mirroring the **PandaRoot** source tree.

To be able to compile external **PandaRoot** related packages, source ``PandaRootConfig.sh``:

.. code-block:: bash

    source <path to your PandaROOT installation directory>/bin/PandaRootConfig.sh -a

External package
----------------

Currently one has to manually copy the ``FindPandaROOT.cmake`` module into the external package.
Such an external package may look like:

.. code-block:: bash

    cmake
    cmake/modules/FindPandaROOT.cmake
    cmake/scripts/config.sh.in
    src/
    src/<your source files>
    src/CMakeLists.txt
    CMakeLists.txt
    PackageConfig.cmake

The ``FindPandaROOT.cmake`` will use the env-variables (exported by the ``PandaRootConfig.sh``) to locate
**PandaRoot**'s CMake-Modules. This allows to include ``PandaRootSetup.cmake``, which defines
the MACRO **pandaroot_setup** which takes care of finding **FairRoot** and **VMC**, so it can be compiled against in the
external packages.

The main ``CMakeLists.txt`` may look as follows:

.. code-block:: cmake

    Project(MyPackage)
    cmake_minimum_required (VERSION 3.16)
    cmake_policy(SET CMP0003 NEW)

    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
    SET(CMAKE_CXX_STANDARD 17)
    SET(CMAKE_CXX_STANDARD_REQUIRED)
    SET(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/modules)

    find_package(PandaRoot REQUIRED)
    SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${PANDAROOT_CMAKEMOD_DIR})
    include(PandaRootSetup)
    pandaroot_setup()

    ## Set some paths where stuff is to be installed to (CMAKE_INSTALL_PREFIX
    ## is set to $ENV{PANDA_3RDPARTY_INSTALL_DIR} in the PackageConfig.cmake)
    SET(CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX}/include)
    SET(CMAKE_INSTALL_LIBDIR ${CMAKE_INSTALL_PREFIX}/lib)
    SET(CMAKE_INSTALL_BINDIR ${CMAKE_INSTALL_PREFIX}/bin)

    ## Add subdirectory to be compiled
    add_subdirectory(src)


    ## After all subdirs have been compiled, add
    SET(MY_ROOT_INCLUDE_PATH ${CMAKE_INSTALL_INCLUDEDIR})
    SET(MY_ROOT_LIBRARY ${CMAKE_INSTALL_LIBDIR}:${ROOT_LIBRARY})
    SET(MY_PATH ${CMAKE_INSTALL_BINDIR})
    SET(MY_LIB_PATH ${CMAKE_INSTALL_LIBDIR})

    configure_file(
    ${PANDAROOTPATH}/cmake/scripts/package_config.sh.in
    ${CMAKE_BINARY_DIR}/package_config.sh
    )
    install(PROGRAMS ${CMAKE_BINARY_DIR}/package_config.sh DESTINATION ${CMAKE_INSTALL_BINDIR})

And the `PackageConfig.cmake` may look like this:

.. code-block:: cmake

    # General usage
    #
    # cmake -S <source-dir> -B <build-dir> -C <source-dir>/PackageConfig.cmake
    # cmake --build <build-dir> [-j<ncpus>]
    #

    # In the following uncomment/change the appropriate option to your needs. Manage multiple
    # configurations by simply copying this file under different filenames.

    #
    # Install prefix
    #
    #  Where to install PPackage
    #  Default should be the 3rdParty subdirectory of the PandaROOT installation directory
    #  but one can override it with the commandline option 
    #    -DCMAKE_INSTALL_PREFIX="/some/other/path" 
    set(PANDA_3RDPARTY_INSTALL_DIR $ENV{PANDA_3RDPARTY_INSTALL_DIR})
    set(CMAKE_INSTALL_PREFIX ${PANDA_3RDPARTY_INSTALL_DIR} CACHE PATH "Install prefix" FORCE)
    # set(CMAKE_INSTALL_PREFIX "/some/other/path" CACHE PATH "Install prefix" FORCE)

    # Note: Defaults are effective even if the option is not set explicitly in this file.

The idea is, that if no ``CMAKE_INSTALL_PREFIX`` is specified, you install the 3rdParty package into
the 3rdParty subdirectory in your **PandaRoot** install direction. This eases the process of
exporting the **ROOT_INCLUDE_PATH** so that **ROOT** can find your new classes in the case you have many, many 
packages. This will be automatically done, if you 

.. code-block:: bash

    source <path to your PandaROOT installation directory>/bin/PandaRootConfig.sh -a

again.