diff --git a/.github/pages-index.html b/.github/pages-index.html deleted file mode 100644 index 51986a6fd..000000000 --- a/.github/pages-index.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - Iguana - - -

Iguana

- - - diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 00c756ecd..38dce04f0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -71,7 +71,6 @@ jobs: - undefined-sanitizer - leak-sanitizer - coverage - - documentation - noROOT include: # main C++ test @@ -88,7 +87,6 @@ jobs: - { id: leak-sanitizer, image: base_root, CC: clang, CXX: clang++, opts: -Dbuildtype=debug -Dz_require_root=true -Db_sanitize=leak -Db_lundef=false -Db_pie=true } # misc. - { id: coverage, image: base_root, CC: gcc, CXX: g++, opts: -Dbuildtype=release -Dz_require_root=true -Db_coverage=true -Dz_test_multithreading=false } - - { id: documentation, image: base_root, CC: gcc, CXX: g++, opts: -Dbuildtype=release -Dz_require_root=true -Dinstall_documentation=true } - { id: noROOT, image: base, CC: gcc, CXX: g++, opts: -Dbuildtype=release -Dz_require_root=false } runs-on: ubuntu-latest container: @@ -119,7 +117,7 @@ jobs: ###### for iguana - name: install packages for iguana run: | - pacman -Syu --noconfirm + pacman -Sy --noconfirm pacman -S --noconfirm \ fmt \ yaml-cpp @@ -131,13 +129,6 @@ jobs: python-colorlog \ python-pygments \ gcovr - ###### for doxygen - - name: install doxygen - if: ${{ matrix.id == 'documentation' }} - run: | - pacman -S --noconfirm \ - doxygen \ - graphviz ###### for python bindings - name: install python bindings dependencies if: ${{ matrix.id == 'python' }} @@ -190,7 +181,6 @@ jobs: - run: tree iguana ### run tests - name: meson test - if: ${{ matrix.id != 'documentation' }} working-directory: iguana_build run: | if [ "${{ env.verbose_test }}" = "true" ]; then @@ -334,45 +324,139 @@ jobs: name: ${{ steps.artifact_names.outputs.validation_name }} retention-days: 90 path: validation_results + + # documentation + ######################################################### + + index_documentation: + name: Index documentation + runs-on: ubuntu-latest + outputs: + versions: ${{ steps.versions.outputs.versions }} + steps: + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + ### get list of versions from git tags; exclude old versions + - name: get versions for documentation generation + id: versions + run: | + echo main | tee version_list + git tag --list --sort=-v:refname |\ + grep -v v0.1.0 |\ + grep -v v0.2.0 |\ + grep -v v0.3.0 |\ + grep -v v0.4.0 |\ + grep -v v0.4.1 |\ + grep -v v0.5.0 |\ + grep -v v0.6.0 |\ + grep -v v0.7.0 |\ + grep -v v0.7.1 |\ + tee -a version_list + versions=$(cat version_list | jq -R -s -c 'split("\n") | map(select(length > 0))') + echo "versions=$versions" | tee -a $GITHUB_OUTPUT + ### dependencies + - name: install packages for mkdocs + run: python -m pip install -r doc/mkdocs/requirements.txt + ### front index page + - name: mkdocs + run: doc/mkdocs/generate.sh build_mkdocs pages $(cat version_list) + - run: tree pages + ### artifacts - name: upload documentation artifacts uses: actions/upload-artifact@v5 - if: ${{ matrix.id == 'documentation' }} with: - name: doc_doxygen + name: doc_web retention-days: 5 - path: iguana/share/doc/iguana/html/ + path: pages + + generate_documentation: + name: Generate documentation + needs: [ index_documentation ] + runs-on: ubuntu-latest + container: + image: codecr.jlab.org/hallb/clas12/container-forge/base_root:latest + options: --user root + strategy: + matrix: + version: ${{ fromJson(needs.index_documentation.outputs.versions) }} + fail-fast: false + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ matrix.version }} + path: iguana_src + ### dependencies + - name: install packages for iguana and doxygen + run: | + pacman -Sy --noconfirm + pacman -S --noconfirm \ + doxygen \ + fmt \ + graphviz \ + yaml-cpp + ### build + - name: set main version to latest + if: ${{ matrix.version == 'main' }} + working-directory: iguana_src + run: sed -i 's;^PROJECT_NUMBER.*=.*;PROJECT_NUMBER = "LATEST";' $(find doc -name Doxyfile.in) + - name: meson setup + run: | + meson setup iguana_build iguana_src \ + --prefix=$GITHUB_WORKSPACE/iguana \ + -Drcdb:home=$RCDB_HOME \ + -Dz_require_rcdb=true \ + -Dz_require_root=true \ + -Dinstall_examples=false \ + -Dinstall_documentation=true + - run: meson compile + working-directory: iguana_build + - run: meson install + working-directory: iguana_build + - name: rename directory + run: | + mkdir pages + cd pages + mkdir ${{ matrix.version }} + mv ../iguana/share/doc/iguana/html/* ${{ matrix.version }}/ + - name: rename latest + if: ${{ matrix.version == 'main' }} + working-directory: pages + run: mv main latest + ### artifacts + - name: upload documentation artifacts + uses: actions/upload-artifact@v5 + with: + name: doc_web_${{ matrix.version }} + retention-days: 5 + path: pages # deployment ######################################################### collect_webpages: - if: ${{ github.ref == 'refs/heads/main' }} name: Collect webpages needs: - iguana + - generate_documentation runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: path: iguana_src - - name: download doxygen documentation + - name: download documentation artifacts uses: actions/download-artifact@v6 with: - name: doc_doxygen - path: doxygen + pattern: doc_web* + path: pages + merge-multiple: true - name: download coverage report uses: actions/download-artifact@v6 with: name: coverage-report path: coverage-report - - run: tree - - name: collect - run: | - mkdir pages - cp iguana_src/.github/pages-index.html pages/index.html - mv doxygen pages/ - run: mv coverage-report pages/ - - run: tree + - run: tree pages - uses: actions/upload-pages-artifact@v4 with: retention-days: 5 diff --git a/.gitignore b/.gitignore index aa188eab6..9ac8344db 100644 --- a/.gitignore +++ b/.gitignore @@ -19,9 +19,9 @@ chameleon-tree *.png # overrides -!doc/gen/logo.png -!doc/gen/logo_small.png -!doc/gen/mermaid/*.png +!doc/logo.png +!doc/logo_small.png +!doc/mermaid/*.png # misc. artifacts .DS_Store diff --git a/README.md b/README.md index 7c287586c..f4c40474f 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,14 @@ - +[![CI](https://github.com/JeffersonLab/iguana/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JeffersonLab/iguana/actions/workflows/ci.yml) +[![Coverage](https://badgen.net/static/coverage/report/purple)](https://jeffersonlab.github.io/iguana/coverage-report) -## Iguana: Implementation Guardian of Analysis Algorithms +--- -The primary goal of Iguana is to preserve and centralize common analysis algorithms, such as fiducial cuts, momentum corrections, and kinematics reconstruction. + -Support is focused on HIPO data for CLAS12, but extending support to other data formats (experiments) may be feasible. +[:star: **Documentation Homepage** :star:](https://jeffersonlab.github.io/iguana) -Iguana is not a framework for _reading_ data, rather it is a set of algorithms to _mutate_ the data. For HIPO data, algorithms mutate banks. See the [API documentation](https://jeffersonlab.github.io/iguana/doxygen) for the list of available algorithms. +### About -> [!CAUTION] -> Iguana is still in the early stages of development. Please see [the issues page](https://github.com/JeffersonLab/iguana/issues) for known issues and development plans. +**IGUANA**: **I**mplementation **Gu**ardian of **An**alysis **A**lgorithms -## Documentation - -### For Users -1. [**Iguana User's Guide**](https://jeffersonlab.github.io/iguana/doxygen) -1. [Setup Guide - how to build and install Iguana](doc/setup.md) -1. [Troubleshooting](doc/troubleshooting.md) - -#### Language Bindings -1. [Python](/bind/python/README.md) -1. [All others: see the Iguana User's guide](https://jeffersonlab.github.io/iguana/doxygen) - -### For Developers -1. [Developing a new Algorithm](src/iguana/algorithms/example/ExampleAlgorithm/README.md) -1. [Algorithm Tests and Validators](doc/testing.md) -1. [Repository Maintenance](doc/maintenance.md) -1. [Building for `cvmfs` or `ifarm`](doc/ifarm.md) - -## Status -1. [Coverage Report](https://jeffersonlab.github.io/iguana/coverage-report) +Iguana is designed to preserve and centralize common analysis algorithms, such as fiducial cuts, momentum corrections, and kinematics reconstruction, for CLAS12 HIPO data. diff --git a/doc/gen/Doxyfile.in b/doc/doxygen/Doxyfile.in similarity index 99% rename from doc/gen/Doxyfile.in rename to doc/doxygen/Doxyfile.in index c917f38d8..4e61f9b15 100644 --- a/doc/gen/Doxyfile.in +++ b/doc/doxygen/Doxyfile.in @@ -61,14 +61,14 @@ PROJECT_BRIEF = "Implementation Guardian of Analysis Algorithms" # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = @top_srcdir@/doc/gen/logo_small.png +PROJECT_LOGO = @top_srcdir@/doc/logo_small.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = @top_builddir@/doc/gen +OUTPUT_DIRECTORY = @top_builddir@/doc/doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -842,7 +842,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = @top_srcdir@/doc/gen/DoxygenLayout.xml +LAYOUT_FILE = @top_srcdir@/doc/doxygen/DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -975,8 +975,8 @@ INPUT = @top_srcdir@/src/ \ @top_builddir@/src/iguana/bankdefs \ @top_builddir@/src/iguana/bankdefs/BankDefs.md \ @top_srcdir@/bind/ \ - @top_srcdir@/doc/gen/ \ - @top_srcdir@/doc/gen/mainpage.md \ + @top_srcdir@/doc/doxygen/ \ + @top_srcdir@/doc/doxygen/mainpage.md \ @top_srcdir@/examples/ \ @top_srcdir@/src/iguana/bankdefs/iguana.json @@ -1090,8 +1090,8 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = @top_srcdir@/doc/gen/logo.png \ - @top_srcdir@/doc/gen/mermaid/flowchart_usage.png +IMAGE_PATH = @top_srcdir@/doc/logo.png \ + @top_srcdir@/doc/mermaid/flowchart_usage.png # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1152,7 +1152,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = @top_srcdir@/doc/gen/mainpage.md +USE_MDFILE_AS_MAINPAGE = @top_srcdir@/doc/doxygen/mainpage.md # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common diff --git a/doc/gen/DoxygenLayout.xml b/doc/doxygen/DoxygenLayout.xml similarity index 100% rename from doc/gen/DoxygenLayout.xml rename to doc/doxygen/DoxygenLayout.xml diff --git a/doc/gen/examples.dox b/doc/doxygen/examples.dox similarity index 100% rename from doc/gen/examples.dox rename to doc/doxygen/examples.dox diff --git a/doc/gen/fortran.dox b/doc/doxygen/fortran.dox similarity index 100% rename from doc/gen/fortran.dox rename to doc/doxygen/fortran.dox diff --git a/doc/gen/mainpage.md b/doc/doxygen/mainpage.md similarity index 100% rename from doc/gen/mainpage.md rename to doc/doxygen/mainpage.md diff --git a/doc/gen/meson.build b/doc/doxygen/meson.build similarity index 100% rename from doc/gen/meson.build rename to doc/doxygen/meson.build diff --git a/doc/gen/namespaces.dox b/doc/doxygen/namespaces.dox similarity index 100% rename from doc/gen/namespaces.dox rename to doc/doxygen/namespaces.dox diff --git a/doc/ifarm.md b/doc/ifarm.md deleted file mode 100644 index de0aa5563..000000000 --- a/doc/ifarm.md +++ /dev/null @@ -1,14 +0,0 @@ -# Building for `ifarm` or `cvmfs` - -## Resolve dependencies - -```bash -meson/resolve-dependencies.py --help # prints the usage guide -``` -Use the resulting arguments when setting up or configuring your build directory. - -## Build and Install - -``` -meson/release/install.sh -``` diff --git a/doc/gen/logo.png b/doc/logo.png similarity index 100% rename from doc/gen/logo.png rename to doc/logo.png diff --git a/doc/gen/logo_small.png b/doc/logo_small.png similarity index 100% rename from doc/gen/logo_small.png rename to doc/logo_small.png diff --git a/doc/maintenance.md b/doc/maintenance.md deleted file mode 100644 index c832a7754..000000000 --- a/doc/maintenance.md +++ /dev/null @@ -1,37 +0,0 @@ -# Repository Maintenance - -Notes for `iguana` maintainers - -## Iguana version - -Please remember to bump to the version number in [`meson.build`](/meson.build) prior to tagging a new release. - -## Python Binding Dependencies - -Keep the Python binding dependency versions reasonably up to date in the corresponding `requirements.txt` file: - -- [`bind/python/requirements.txt`](/bind/python/requirements.txt) - -## C++ Standard - -We currently support up to the C++ standard defined in [`meson.build`](/meson.build); if you change this, you will also need to update: -- [ ] example build configurations in [`examples/build_with_*` subdirectories](/examples) -- [ ] in the [main CI workflow](/.github/workflows/ci.yml), the standard used for the ROOT build (`CMAKE_CXX_STANDARD`) -- [ ] any mention of the standard in documentation - -## Code Ownership - -We maintain a [`CODEOWNERS` file](/CODEOWNERS) to track who wrote and maintains each file. If you make significant contributions to any part of the code, please update `CODEOWNERS`. Pull requests that edit a file that you maintain will automatically request for your review, when marked as ready. - -## Auto-Formatting - -We provide a [`.clang-format`](/.clang-format) file for auto-formatting C++ code. If your system has `clang-format`, -then `meson` will create a `ninja` build target called `clang-format`, which you may run as -```bash -ninja -C clang-format -``` -We also use `meson.format` to format the `meson` build files. - -For semi-automation, the script `.github/auto-format.sh` will create a new -`git` branch, and then run the auto-formatters; run `git diff` to see the -proposed changes. diff --git a/doc/gen/mermaid/build.sh b/doc/mermaid/build.sh similarity index 100% rename from doc/gen/mermaid/build.sh rename to doc/mermaid/build.sh diff --git a/doc/gen/mermaid/flowchart_usage.mmd b/doc/mermaid/flowchart_usage.mmd similarity index 100% rename from doc/gen/mermaid/flowchart_usage.mmd rename to doc/mermaid/flowchart_usage.mmd diff --git a/doc/gen/mermaid/flowchart_usage.png b/doc/mermaid/flowchart_usage.png similarity index 100% rename from doc/gen/mermaid/flowchart_usage.png rename to doc/mermaid/flowchart_usage.png diff --git a/doc/dependency_resolution.md b/doc/mkdocs/docs/dependency_resolution.md similarity index 71% rename from doc/dependency_resolution.md rename to doc/mkdocs/docs/dependency_resolution.md index 1c4e0a577..ad2660f11 100644 --- a/doc/dependency_resolution.md +++ b/doc/mkdocs/docs/dependency_resolution.md @@ -4,16 +4,17 @@ The dependencies in [the setup guide](setup.md) must be locatable by `iguana`, o by anything that depends on `iguana`. Assuming a dependency is installed in `$prefix`, it uses one or more of the following: + - `pkg-config`: a `.pc` file in `$prefix/lib/pkgconfig` - `.cmake` files in `$prefix/lib/cmake` Take a look at each dependency's installation prefix to see which of these options are available. -> [!NOTE] -> Some installations will have libraries, and therefore `cmake/` and `pkgconfig/` directories, within -> `$prefix/lib64`, or within `$prefix/lib/x86_64-linux-gnu`. For brevity in the documentation below, we assume -> they are in `$prefix/lib`. +!!! note + Some installations will have libraries, and therefore `cmake/` and `pkgconfig/` directories, within + `$prefix/lib64`, or within `$prefix/lib/x86_64-linux-gnu`. For brevity in the documentation below, we assume + they are in `$prefix/lib`. ## Resolving Build Dependencies @@ -22,7 +23,7 @@ The following sections explain how to do so with each. ### 🔷 Meson For `iguana`, the build system is `meson`, which accepts the build options -```bash +``` bash -Dpkg_config_path=$prefix/lib/pkgconfig -Dcmake_prefix_path=$prefix ``` @@ -31,23 +32,24 @@ For `iguana`, the build system is `meson`, which accepts the build options ### 🔷 CMake For `cmake`, the `pkg-config` path can be combined with the `cmake` path, so only the build option -```bash +``` bash -DCMAKE_PREFIX_PATH="$prefix" ``` is needed; this assumes: + - all dependencies are in `$prefix` (delimit multiple paths with semicolons) - `PKG_CONFIG_USE_CMAKE_PREFIX_PATH` has not been disabled. ### 🔷 General Case Environment variables may be used instead of build options for a general approach: -```bash +``` bash export PKG_CONFIG_PATH=$prefix/lib/pkgconfig export CMAKE_PREFIX_PATH=$prefix ``` (where multiple paths are delimited by colons). `pkg-config` files (`.pc`) allow for usage of the `pkg-config` command. Assuming the package is `hipo4` and `hipo4.pc` is found in `PKG_CONFIG_PATH`, compiler flags may be found by -```bash +``` bash pkg-config --libs hipo4 pkg-config --cflags hipo4 ``` @@ -55,9 +57,5 @@ Any variable defined in `hipo4.pc` is accessible with `pkg-config --variable + +## User Guides + +Choose a user guide matching the version of Iguana you are using: + +@guides@ + +### Additional Guides + +| Link | Description | +| --- | --- | +| [**Setup Guide**](setup.md) | How to build and install Iguana | +| [**Dependency Resolution**](dependency_resolution.md) | Iguana dependencies and where to get them | +| [**Troubleshooting**](troubleshooting.md) | Common issues and possible solutions | +| [**Python**](https://github.com/JeffersonLab/iguana/blob/main/bind/python/README.md) | Additional notes for Python bindings (see also _User Guides_ above) | + +## Development Guides + +Guidance for developing Iguana algorithms and code maintenance: + +| Link | Description | +| --- | --- | +| [**Algorithm Development**](https://github.com/JeffersonLab/iguana/blob/main/src/iguana/algorithms/example/ExampleAlgorithm/README.md) | How to develop an Iguana Algorithm | +| [**Algorithm Tests and Validators**](testing.md) | How to write validators and tests| +| [**Repository Maintenance**](maintenance.md) | Maintaining this repository | +| [**Building for `cvmfs` or `ifarm`**](ifarm.md) | How to deploy to `ifarm` | diff --git a/doc/mkdocs/docs/maintenance.md b/doc/mkdocs/docs/maintenance.md new file mode 100644 index 000000000..ef335affb --- /dev/null +++ b/doc/mkdocs/docs/maintenance.md @@ -0,0 +1,37 @@ +# Repository Maintenance + +Notes for `iguana` maintainers + +## Iguana version + +Make sure the version number in the top-level `meson.build` is correct, prior to tagging a new release. + +## Python Binding Dependencies + +Keep the Python binding dependency versions reasonably up to date in the corresponding `requirements.txt` file: + +- [`bind/python/requirements.txt`](https://github.com/JeffersonLab/iguana/blob/main/bind/python/requirements.txt) + +## C++ Standard + +We currently support up to the C++ standard defined in the top-level `meson.build`; if you change this, you will also need to update: + +- example build configurations in `examples/build_with_*` subdirectories +- any mention of the standard in documentation + +## Code Ownership + +We maintain a `CODEOWNERS` file to track who wrote and maintains each file. If you make significant contributions to any part of the code, please update `CODEOWNERS`. Pull requests that edit a file that you maintain will automatically request for your review, when marked as ready. + +## Auto-Formatting + +We provide a `.clang-format` file for auto-formatting C++ code. If your system has `clang-format`, +then `meson` will create a `ninja` build target called `clang-format`, which you may run as +``` bash +ninja -C clang-format +``` +We also use `meson.format` to format the `meson` build files. + +For semi-automation, the script `.github/auto-format.sh` will create a new +`git` branch, and then run the auto-formatters; run `git diff` to see the +proposed changes. diff --git a/doc/mkdocs/docs/setup.md b/doc/mkdocs/docs/setup.md new file mode 100644 index 000000000..1b5766000 --- /dev/null +++ b/doc/mkdocs/docs/setup.md @@ -0,0 +1,198 @@ +# Setup Guide + + +## 🟠 Dependencies + +!!! tip + It's generally better to use your a package manager to install most dependencies, _e.g._: + + - macOS Homebrew: `brew install ` + - Linux (depends on distribution) examples: `apt install `, `dnf install `, `pacman -S ` + - 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: + ```bash + 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. + +??? info "🟩 Meson: Build system used by Iguana" + + + - Likely available in your package manager, but the latest version is preferred and may be installed with `pip`: + ``` bash + python -m pip install meson ninja + ``` + This includes [`ninja`](https://ninja-build.org/), which `meson` will benefit from using. + +??? info "🟩 fmt: C++ output formatting library" + + + - 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 + +??? info "🟩 yaml-cpp: YAML parser and emitter" + + + - Likely available in your package manager, likely as `yaml-cpp` + +??? info "🟩 HIPO: C++ HIPO API" + + + - Use the `hipo` module on `ifarm`, or obtain and build it yourself + +??? info "🟩 Ruby [optional]: programming language" + + + - 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`](https://github.com/JeffersonLab/iguana/blob/main/src/chameleon), a local Ruby program + +??? info "🟩 ROOT [optional]: Data analysis framework" + + + - 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](https://root.cern/install/build_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` + +??? info "🟩 RCDB [optional]: Run Condition Database" + + + - 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`](https://mariadb.org/) + - depending on your OS's packages, you may need the "dev" version, _e.g._, `libmariadb-dev` + + + +## 🟠 Building and Installing + +Iguana uses [`meson`](https://mesonbuild.com/) 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: +``` bash +/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](dependency_resolution.md) 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: +``` bash +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: +``` bash +meson configure --prefix=/path/to/iguana-installation # must be an ABSOLUTE path +``` + +Aside from `--prefix`, most other build options are set with `-D`: +``` bash +meson configure -D