Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: simplify dependencies list #287

Merged
merged 4 commits into from
Oct 3, 2024
Merged

doc: simplify dependencies list #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1d5f698
doc: simplify dependencies list
c-dilks Oct 3, 2024
79a0938
modified: doc/troubleshooting.md
c-dilks Oct 3, 2024
399c9a2
fix: link
c-dilks Oct 3, 2024
1ed63ac
fix: note format
c-dilks Oct 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
130 changes: 77 additions & 53 deletions doc/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
<a name="dependencies"></a>
## 🟠 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._:
Expand All @@ -25,59 +25,83 @@ The following sections (🟩) list the dependencies and how to obtain them.
> ```
<!--`-->

### 🟩 `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`:
```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
<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:
```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
```
<details>
<summary>🟩 Meson: Build system used by Iguana</summary>

> <https://mesonbuild.com/>
> - 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.
</details>

<details>
<summary>🟩 fmt: C++ output formatting library</summary>

> <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
</details>

<details>
<summary>🟩 yaml-cpp: YAML parser and emitter</summary>

> <https://github.com/jbeder/yaml-cpp>
> - Likely available in your package manager, likely as `yaml-cpp`
</details>

<details>
<summary>🟩 HIPO: C++ HIPO API</summary>

> <https://github.com/gavalian/hipo>
> - 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
> ```
> <!--`-->
</details>

<details>
<summary>🟩 Ruby [optional]: programming language</summary>

> <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`](/src/chameleon), a local Ruby program
</details>

<details>
<summary>🟩 ROOT [optional]: Data analysis framework</summary>

> <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](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`
</details>

<details>
<summary>🟩 RCDB [optional]: Run Condition Database</summary>

> <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`](https://mariadb.org/)
> - depending on your OS's packages, you may need the "dev" version, _e.g._, `libmariadb-dev`
</details>

### 🟩 Optional: `ruby`: 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`](/src/chameleon), a local Ruby program

### 🟩 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](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
<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`](https://mariadb.org/)
- depending on your OS's packages, you may need the "dev" version, _e.g._, `libmariadb-dev`

<a name="building"></a>
## 🟠 Building and Installing
Expand Down
15 changes: 10 additions & 5 deletions doc/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Troubleshooting Notes

### 🔵 My output appears to be out of order: errors are not printed exactly when they occur
<details>
<summary>🔵 My output appears to be out of order: errors are not printed exactly when they occur</summary>

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
Expand All @@ -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`.
</details>

### 🔵 I got a crash, but the stack trace (or debugger) is not telling me exactly where
<details>
<summary>🔵 I got a crash, but the stack trace (or debugger) is not telling me exactly where</summary>

Enable debugging symbols by setting the Iguana build option `buildtype` to `'debug'`, then rebuild.
Assuming you're in your build directory, run:
Expand All @@ -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`).
</details>

### 🔵 I got some error about "chameleon", or an error in some "chameleon" file that I can't find
<details>
<summary>🔵 I got some error about "chameleon", or an error in some "chameleon" file that I can't find</summary>

[Chameleon is a code generator](/src/chameleon) to automatically create
`iguana` bindings for programming languages other than C++. All generated code
Expand All @@ -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.
</details>
Loading