diff --git a/README.md b/README.md index 3804be4e..fa186450 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Iguana is not a framework for _reading_ data, rather it is a set of algorithms t ### For Developers 1. [Design Notes](doc/design.md) -1. [Developing a new Algorithm](src/iguana/algorithms/example/README.md) +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) diff --git a/doc/setup.md b/doc/setup.md index 513f8bfb..aa937cdf 100644 --- a/doc/setup.md +++ b/doc/setup.md @@ -9,7 +9,7 @@ ## 🟠 Dependencies -The following sections (🟩) list the dependencies and how to obtain them. +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._: @@ -25,59 +25,83 @@ The following sections (🟩) list the dependencies and how to obtain them. > ``` -### 🟩 `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. - -### 🟩 `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 - -### 🟩 `yaml-cpp`: YAML parser and emitter - -- Likely available in your package manager, likely as `yaml-cpp` - -### 🟩 `hipo`: C++ HIPO API - -- Use the `hipo` module on `ifarm`, or obtain and build it yourself -- Example `cmake` commands: -```bash -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 -``` +
+🟩 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. +
+ +
+🟩 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 +
+ +
+🟩 yaml-cpp: YAML parser and emitter + +> +> - Likely available in your package manager, likely as `yaml-cpp` +
+ +
+🟩 HIPO: C++ HIPO API + +> +> - Use the `hipo` module on `ifarm`, or obtain and build it yourself +> - Example `cmake` commands: +> ```bash +> 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 + +> +> - 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`](/src/chameleon), a local Ruby program +
+ +
+🟩 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` +
+ +
+🟩 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` +
-### 🟩 Optional: `ruby`: 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`](/src/chameleon), a local Ruby program - -### 🟩 Optional: `ROOT`: 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` - -### 🟩 Optional: `RCDB`: 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 diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md index 469767dd..a6fc3379 100644 --- a/doc/troubleshooting.md +++ b/doc/troubleshooting.md @@ -1,6 +1,7 @@ # Troubleshooting Notes -### 🔵 My output appears to be out of order: errors are not printed exactly when they occur +
+🔵 My output appears to be out of order: errors are not printed exactly when they occur If you redirect `stdout` and `stderr` to a file, you may notice that `stderr` lines are out-of-order with respect to the `stdout` lines; for example: ```bash @@ -14,10 +15,11 @@ To redirect output to a file with the ordering preserved, run your executable wi stdbuf -o0 myAnalysisProgram |& tee output.txt ``` -> [!NOTE] -> `stdbuf` on macOS may be installed as `gstdbuf`, from the Homebrew package `coreutils`. +**NOTE:** `stdbuf` on macOS may be installed as `gstdbuf`, from the Homebrew package `coreutils`. +
-### 🔵 I got a crash, but the stack trace (or debugger) is not telling me exactly where +
+🔵 I got a crash, but the stack trace (or debugger) is not telling me exactly where Enable debugging symbols by setting the Iguana build option `buildtype` to `'debug'`, then rebuild. Assuming you're in your build directory, run: @@ -28,8 +30,10 @@ Then rebuild (`meson compile` and/or `meson install`). Remember to revert this change and rebuild/re-install, so that Iguana runs with full optimization when you are processing large data sets (`-Dbuildtype=release`). +
-### 🔵 I got some error about "chameleon", or an error in some "chameleon" file that I can't find +
+🔵 I got some error about "chameleon", or an error in some "chameleon" file that I can't find [Chameleon is a code generator](/src/chameleon) to automatically create `iguana` bindings for programming languages other than C++. All generated code @@ -38,3 +42,4 @@ is produced in your build directory. If you have issues with Chameleon, either: - something is wrong with `chameleon` In either case, open an issue or contact the maintainers. +