Skip to content

Latest commit

 

History

History
165 lines (132 loc) · 8.46 KB

setup.md

File metadata and controls

165 lines (132 loc) · 8.46 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.

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

🔶 Optional: ROOT: 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

🟠 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; you can also choose to write those build options to an INI (native) file.

Alternatively, you may use environment variables; 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 near the bottom, under "Project options".

Alternatively, see meson.options for the list of project options, and some more details.

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.

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