Skip to content

Setup Guide

🟠 Dependencies

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 tag --list --sort=-v:refname  # list all the tags (latest first)
git checkout v1.0.0               # checkout the tag 'v1.0.0'

The following boxes list the dependencies and how to obtain them. Click on each for details.

🟩 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
🟩 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
  • mariadb is an open source fork of mysql
  • depending on your OS's packages, you may need the "dev" version, e.g., libmariadb-dev

🟠 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. Run 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

Aside from --prefix, most other build options are set with -D: 

meson configure -D<option>=<value>  # syntax
meson configure -Dbind_python=true  # example, which sets option 'bind_python' to 'true'
The following table includes commonly-used build options; they are not required since they have default values, but you may prefer to change them:

Option Description
rcdb:home Location of RCDB installation; if empty, RCDB-dependent code will not be included. TIP: set it to $RCDB_HOME
install_examples Install examples
bind_python Install Python bindings
bind_fortran Install Fortran bindings

The current value of all options, and their descriptions, may be found by running: 

meson configure   # you may scroll, or press 'q' to quit
Scroll down to the "Project options" sections, which are near the bottom, for Iguana specific options.

Note

The first "Project options" section is for Iguana, while the subsequent "Project options" sections are for its subprojects. To set a subproject option, you must prefix the subproject name; for example, for subproject rcdb, to set option home to /opt/rcdb: 

meson configure -Drcdb:home=/opt/rcdb

Tip

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

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

🟩 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
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