Skip to content

Commit 8cc1574

Browse files
c-dilksc-dilks
authored
doc: simplify dependencies list (#287)
1 parent 41bbc35 commit 8cc1574

File tree

3 files changed

+88
-59
lines changed

3 files changed

+88
-59
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Iguana is not a framework for _reading_ data, rather it is a set of algorithms t
2525

2626
### For Developers
2727
1. [Design Notes](doc/design.md)
28-
1. [Developing a new Algorithm](src/iguana/algorithms/example/README.md)
28+
1. [Developing a new Algorithm](src/iguana/algorithms/example/ExampleAlgorithm/README.md)
2929
1. [Algorithm Tests and Validators](doc/testing.md)
3030
1. [Repository Maintenance](doc/maintenance.md)
3131
1. [Building for `cvmfs` or `ifarm`](doc/ifarm.md)

‎doc/setup.md

Lines changed: 77 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<a name="dependencies"></a>
1010
## 🟠 Dependencies
1111

12-
The following sections (🟩) list the dependencies and how to obtain them.
12+
The following sections (🟩) list the dependencies and how to obtain them. Click on each for details.
1313

1414
> [!TIP]
1515
> 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.
2525
> ```
2626
<!--`-->
2727
28-
### 🟩 `meson`: Build system used by Iguana
29-
<https://mesonbuild.com/>
30-
- Likely available in your package manager, but the latest version is preferred and may be installed with `pip`:
31-
```bash
32-
python -m pip install meson ninja
33-
```
34-
This includes [`ninja`](https://ninja-build.org/), which `meson` will benefit from using.
35-
36-
### 🟩 `fmt`: C++ output formatting library
37-
<https://github.com/fmtlib/fmt>
38-
- Likely available in your package manager, likely as `fmt` or `libfmt`
39-
- If you need Python bindings on macOS, please install `fmt` with `brew install fmt`
40-
- If you compile it yourself on Linux, include the `cmake` option `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` to build the static library
41-
42-
### 🟩 `yaml-cpp`: YAML parser and emitter
43-
<https://github.com/jbeder/yaml-cpp>
44-
- Likely available in your package manager, likely as `yaml-cpp`
45-
46-
### 🟩 `hipo`: C++ HIPO API
47-
<https://github.com/gavalian/hipo>
48-
- Use the `hipo` module on `ifarm`, or obtain and build it yourself
49-
- Example `cmake` commands:
50-
```bash
51-
cmake -S /path/to/hipo_source_code -B build-hipo -DCMAKE_INSTALL_PREFIX=/path/to/hipo_installation
52-
cmake --build build-hipo
53-
cmake --install build-hipo
54-
```
28+
<details>
29+
<summary>🟩 Meson: Build system used by Iguana</summary>
30+
31+
> <https://mesonbuild.com/>
32+
> - Likely available in your package manager, but the latest version is preferred and may be installed with `pip`:
33+
> ```bash
34+
> python -m pip install meson ninja
35+
> ```
36+
> <!--`-->
37+
> This includes [`ninja`](https://ninja-build.org/), which `meson` will benefit from using.
38+
</details>
39+
40+
<details>
41+
<summary>🟩 fmt: C++ output formatting library</summary>
42+
43+
> <https://github.com/fmtlib/fmt>
44+
> - Likely available in your package manager, likely as `fmt` or `libfmt`
45+
> - If you need Python bindings on macOS, please install `fmt` with `brew install fmt`
46+
> - If you compile it yourself on Linux, include the `cmake` option `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` to build the static library
47+
</details>
48+
49+
<details>
50+
<summary>🟩 yaml-cpp: YAML parser and emitter</summary>
51+
52+
> <https://github.com/jbeder/yaml-cpp>
53+
> - Likely available in your package manager, likely as `yaml-cpp`
54+
</details>
55+
56+
<details>
57+
<summary>🟩 HIPO: C++ HIPO API</summary>
58+
59+
> <https://github.com/gavalian/hipo>
60+
> - Use the `hipo` module on `ifarm`, or obtain and build it yourself
61+
> - Example `cmake` commands:
62+
> ```bash
63+
> cmake -S /path/to/hipo_source_code -B build-hipo -DCMAKE_INSTALL_PREFIX=/path/to/hipo_installation
64+
> cmake --build build-hipo
65+
> cmake --install build-hipo
66+
> ```
67+
> <!--`-->
68+
</details>
69+
70+
<details>
71+
<summary>🟩 Ruby [optional]: programming language</summary>
72+
73+
> <https://www.ruby-lang.org/en/>
74+
> - Likely available in your package manager, likely as `ruby`
75+
> - This is only needed if you intend to use Iguana with languages other than C++
76+
> - Bindings to other programming languages are generated by [`chameleon`](/src/chameleon), a local Ruby program
77+
</details>
78+
79+
<details>
80+
<summary>🟩 ROOT [optional]: Data analysis framework</summary>
81+
82+
> <https://root.cern.ch/>
83+
> - ROOT is an **optional** dependency: some algorithms and test code depends on ROOT, but if you do not
84+
> have ROOT on your system, `iguana` will build everything _except_ ROOT-dependent code
85+
> - It is **NOT recommended** to use your package manager to install ROOT; the most reliable installation
86+
> method is [building it from source](https://root.cern/install/build_from_source/)
87+
> - You may need to set the C++ standard to match that used in `iguana`, which is currently 17; to do so,
88+
> use the build option `-DCMAKE_CXX_STANDARD=17`
89+
> - After installation, depending on ROOT's installation prefix you may also need to set your environment so
90+
> ROOT may be found; this is typically done by `source /path/to/root/bin/thisroot.sh`
91+
</details>
92+
93+
<details>
94+
<summary>🟩 RCDB [optional]: Run Condition Database</summary>
95+
96+
> <https://github.com/JeffersonLab/rcdb>
97+
> - RCDB is optional, but needed for algorithms that use, _e.g._, the beam energy
98+
> - You do not need to compile RCDB, just clone the repository
99+
> - You may need to use the latest version on the main branch, rather than the most recent tag
100+
> - Iguana uses `mysql` for RCDB; you may need to install `mariadb` or `mysql` client on your system
101+
> - [`mariadb` is an open source fork of `mysql`](https://mariadb.org/)
102+
> - depending on your OS's packages, you may need the "dev" version, _e.g._, `libmariadb-dev`
103+
</details>
55104
56-
### 🟩 Optional: `ruby`: programming language
57-
<https://www.ruby-lang.org/en/>
58-
- Likely available in your package manager, likely as `ruby`
59-
- This is only needed if you intend to use Iguana with languages other than C++
60-
- Bindings to other programming languages are generated by [`chameleon`](/src/chameleon), a local Ruby program
61-
62-
### 🟩 Optional: `ROOT`: Data analysis framework
63-
<https://root.cern.ch/>
64-
- ROOT is an **optional** dependency: some algorithms and test code depends on ROOT, but if you do not
65-
have ROOT on your system, `iguana` will build everything _except_ ROOT-dependent code
66-
- It is **NOT recommended** to use your package manager to install ROOT; the most reliable installation
67-
method is [building it from source](https://root.cern/install/build_from_source/)
68-
- You may need to set the C++ standard to match that used in `iguana`, which is currently 17; to do so,
69-
use the build option `-DCMAKE_CXX_STANDARD=17`
70-
- After installation, depending on ROOT's installation prefix you may also need to set your environment so
71-
ROOT may be found; this is typically done by `source /path/to/root/bin/thisroot.sh`
72-
73-
### 🟩 Optional: `RCDB`: Run Condition Database
74-
<https://github.com/JeffersonLab/rcdb>
75-
- RCDB is optional, but needed for algorithms that use, _e.g._, the beam energy
76-
- You do not need to compile RCDB, just clone the repository
77-
- You may need to use the latest version on the main branch, rather than the most recent tag
78-
- Iguana uses `mysql` for RCDB; you may need to install `mariadb` or `mysql` client on your system
79-
- [`mariadb` is an open source fork of `mysql`](https://mariadb.org/)
80-
- depending on your OS's packages, you may need the "dev" version, _e.g._, `libmariadb-dev`
81105
82106
<a name="building"></a>
83107
## 🟠 Building and Installing

‎doc/troubleshooting.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Troubleshooting Notes
22

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

56
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:
67
```bash
@@ -14,10 +15,11 @@ To redirect output to a file with the ordering preserved, run your executable wi
1415
stdbuf -o0 myAnalysisProgram |& tee output.txt
1516
```
1617

17-
> [!NOTE]
18-
> `stdbuf` on macOS may be installed as `gstdbuf`, from the Homebrew package `coreutils`.
18+
**NOTE:** `stdbuf` on macOS may be installed as `gstdbuf`, from the Homebrew package `coreutils`.
19+
</details>
1920

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

2224
Enable debugging symbols by setting the Iguana build option `buildtype` to `'debug'`, then rebuild.
2325
Assuming you're in your build directory, run:
@@ -28,8 +30,10 @@ Then rebuild (`meson compile` and/or `meson install`).
2830

2931
Remember to revert this change and rebuild/re-install, so that Iguana runs with
3032
full optimization when you are processing large data sets (`-Dbuildtype=release`).
33+
</details>
3134

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

3438
[Chameleon is a code generator](/src/chameleon) to automatically create
3539
`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:
3842
- something is wrong with `chameleon`
3943

4044
In either case, open an issue or contact the maintainers.
45+
</details>

0 commit comments

Comments
 (0)