Skip to content

Latest commit

 

History

History
213 lines (169 loc) · 10.3 KB

setup.md

File metadata and controls

213 lines (169 loc) · 10.3 KB

Setup Guide

Table of Contents
🟠 Dependencies
🟠 Building and Installing
🟠 Environment Variables (optional)

🟠 Dependencies

The following sections (🟩) list the dependencies and how to obtain them. Click on each for details.

Tip

It's generally better to use your a package manager to install most dependencies, e.g.:

  • macOS Homebrew: brew install <package>
  • Linux (depends on distribution) examples: apt install <package>, dnf install <package>, pacman -S <package>
  • The name of the package may be different for different package managers; search for and read about the package before installing it

Important

If you obtain a dependency from GitHub (or similar), it's best practice to obtain a recent tag rather than the latest version on the main branch:

git log --tags --decorate --simplify-by-decoration --oneline     # list all the tags (latest first)
git checkout 1.0.0                                               # checkout the tag '1.0.0'
🟩 Meson: Build system used by Iguana

https://mesonbuild.com/

  • Likely available in your package manager, but the latest version is preferred and may be installed with pip:
python -m pip install meson ninja

This includes ninja, which meson will benefit from using.

🟩 fmt: C++ output formatting library

https://github.com/fmtlib/fmt

  • Likely available in your package manager, likely as fmt or libfmt
    • If you need Python bindings on macOS, please install fmt with brew install fmt
    • If you compile it yourself on Linux, include the cmake option -DCMAKE_POSITION_INDEPENDENT_CODE=ON to build the static library
🟩 yaml-cpp: YAML parser and emitter

https://github.com/jbeder/yaml-cpp

  • Likely available in your package manager, likely as yaml-cpp
🟩 HIPO: C++ HIPO API

https://github.com/gavalian/hipo

  • Use the hipo module on ifarm, or obtain and build it yourself
  • Example cmake commands:
cmake -S /path/to/hipo_source_code -B build-hipo -DCMAKE_INSTALL_PREFIX=/path/to/hipo_installation
cmake --build build-hipo
cmake --install build-hipo
🟩 Ruby [optional]: programming language

https://www.ruby-lang.org/en/

  • Likely available in your package manager, likely as ruby
  • This is only needed if you intend to use Iguana with languages other than C++
    • Bindings to other programming languages are generated by chameleon, a local Ruby program
🟩 ROOT [optional]: Data analysis framework

https://root.cern.ch/

  • ROOT is an optional dependency: some algorithms and test code depends on ROOT, but if you do not have ROOT on your system, iguana will build everything except ROOT-dependent code
  • It is NOT recommended to use your package manager to install ROOT; the most reliable installation method is building it from source
    • You may need to set the C++ standard to match that used in iguana, which is currently 17; to do so, use the build option -DCMAKE_CXX_STANDARD=17
  • After installation, depending on ROOT's installation prefix you may also need to set your environment so ROOT may be found; this is typically done by source /path/to/root/bin/thisroot.sh
🟩 RCDB [optional]: Run Condition Database

https://github.com/JeffersonLab/rcdb

  • RCDB is optional, but needed for algorithms that use, e.g., the beam energy
  • You do not need to compile RCDB, just clone the repository
  • You may need to use the latest version on the main branch, rather than the most recent tag
  • Iguana uses mysql for RCDB; you may need to install mariadb or mysql client on your system

🟠 Building and Installing

Iguana uses meson as its build system. From here, we assume that:

  • you are in a working directory, which may be any directory
  • the Iguana source code directory (this repository) is found at /path/to/iguana-source

The following Steps (🟩) explain how to use meson to install Iguana.

🟩 Step 1: Resolve Dependencies

Any dependencies which are not installed in the system-wide default locations will need to be found. Use meson/resolve-dependencies.py to help you:

/path/to/iguana-source/meson/resolve-dependencies.py --help    # prints the usage guide

Tell it where your dependencies are installed and it will tell you the build options that you need for Step 2.

See the note on dependency resolution for more general guidance.

🟩 Step 2: Generate a build directory

Make a build directory, then cd into it. You may choose any name, but we'll use build-iguana in this example:

meson setup build-iguana /path/to/iguana-source [BUILD_OPTIONS_FROM_STEP_1]
cd build-iguana

You'll need to replace [BUILD_OPTIONS_FROM_STEP_1] with the build options from Step 1 above.

Important

The next steps assume your current directory is the build directory. Refer to meson documentation if you'd rather be in a different directory.

🟩 Step 3: Set build options

If you will install iguana (recommended), set an installation prefix:

meson configure --prefix=/path/to/iguana-installation  # must be an ABSOLUTE path

All build options, their current values, and their descriptions may be found by running one of

meson configure              # outputs in a pager (`less`); you may scroll, or press 'q' to quit
meson configure --no-pager   # do not use a pager

but that's a lot of text! The most important build options are under the "Project options" sections: the first such section is for iguana, and the rest are for subprojects (e.g., rcdb).

To see just the project options, run the following (which requires jq):

/path/to/iguana-source/meson/dump-build-options.sh .

To set any build option, e.g. install_examples to true, run:

meson configure -Dinstall_examples=true

You can add as many -D<option>=<value> arguments as you need.

Note

To set a subproject's option, you must prefix the subproject name. For example, for rcdb, use -Drcdb:<option>=<value>.

🟩 Step 4: Compile and Install

Now compile and install Iguana:

meson compile   # builds Iguana, filling your build directory
meson install   # installs Iguana to your prefix (build option 'prefix')

Tip

You can use combine these two commands by just running meson install

Important

If you have trouble and want to try a clean build, do not delete your build directory (since you spent the time to configure it); instead, clean your build directory by running:

meson setup --wipe /path/to/iguana-source

This will preserve your build options; then try to rebuild.

🟠 Environment Variables (optional)

The C++ Iguana implementation does not require the use of any environment variables. However,

  • if Iguana libraries are not in your default linker library search path, you may need to update it, e.g. with $LD_LIBRARY_PATH (Linux) or $DYLD_LIBRARY_PATH (macOS)
  • some language bindings may need variables such as $PYTHONPATH, for Python

You may set your own environment variables, but for a quick start with suggested settings, the installed files bin/this_iguana.sh and bin/this_iguana.tcsh may be used as

source bin/this_iguana.sh    # for 'bash' and 'zsh' only; use the --help argument to see more usage options
source bin/this_iguana.tcsh  # for 'tcsh' only; has no --help option and spawns a 'tcsh' sub-shell

The following environment variables are set or modified; not all of them are needed for all users:

Variable Modification
PKG_CONFIG_PATH adds paths to the pkg-config files (.pc) for dependencies and Iguana; see note on dependency resolution
LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS) adds paths to dependency and Iguana libraries
PYTHONPATH adds paths to dependency and Iguana Python packages, if Python bindings are installed
ROOT_INCLUDE_PATH adds paths to dependency and Iguana header files, for usage in ROOT
IGUANA_CONFIG_PATH path to iguana algorithm configuration files (.yaml); users may override this with their own path; multiple paths may be specified, delimited by colons (:), where paths listed first will override paths listed later (similar behavior as $PATH); this variable is only necessary if the Iguana installation has been relocated
IGUANA the path to the Iguana installation prefix, equivalent to pkg-config iguana --variable prefix; this is only for consumers that do not use pkg-config or the other standard environment variables, however usage of this variable is discouraged since the installation layout may vary