doc: clarify environment variables and consuming

JeffersonLab · Jan 29, 2025 · 13b3119 · 13b3119
1 parent 861f037
commit 13b3119
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 15 deletions.
diff --git a/doc/setup.md b/doc/setup.md
@@ -1,10 +1,11 @@
 # Setup Guide
 
-| **Table of Contents**                           |
-| ---                                             |
-| 🟠 [**Dependencies**](#dependencies)            |
-| 🟠 [**Building and Installing**](#building)     |
-| 🟠 [**Environment Variables** (optional)](#env) |
+| **Table of Contents**                                      |
+| ---                                                        |
+| 🟠 [**Dependencies**](#dependencies)                       |
+| 🟠 [**Building and Installing**](#building)                |
+| 🟠 [**Environment Variables** (optional)](#env)            |
+| 🟠 [**Connect to a C++ Analysis (consuming)**](#consuming) |
 
 <a name="dependencies"></a>
 ## 🟠 Dependencies
@@ -209,5 +210,23 @@ The following environment variables are set or modified; not all of them are nee
 | `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_CONFIG_PATH`                                     | path to iguana algorithm configuration files (`.yaml`); users may override this with their own path; multiple paths may be specified, delimited by colons (`:`), where paths listed first will override paths listed later (similar behavior as `$PATH`); this variable is _only_ necessary if the Iguana installation has been relocated |
-| `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 |
+| `IGUANA_CONFIG_PATH`                                     | path to iguana algorithm configuration files (`.yaml`); users may override this with their own path; multiple paths may be specified, delimited by colons (`:`), where paths listed first will override paths listed later (similar behavior as `$PATH`) |
+| `IGUANA`                                                 | the path to the Iguana installation prefix |
+
+> [!IMPORTANT]
+> If the Iguana installation is _relocated_, the following environment variables become _necessary_:
+> - `IGUANA`
+> - `IGUANA_CONFIG_PATH`
+
+> [!WARNING]
+> Avoid using the `$IGUANA` environment variable for locating Iguana libraries, headers, _etc._, since the installation
+> tree may vary. Instead, use `pkg-config`, following the [consuming section](#consuming).
+
+<a name="consuming"></a>
+## 🟠 Connect to a C++ Analysis (consuming)
+
+To integrate Iguana with your own C++ analysis code, _i.e._ to "consume" Iguana as a dependency, follow
+one of the examples, depending on your build tool:
+- [CMake](../examples/build_with_cmake)
+- [Meson](../examples/build_with_meson)
+- [Makefile](../examples/build_with_make)
diff --git a/examples/meson.build b/examples/meson.build
@@ -1,5 +1,5 @@
 # install config files
-example_config_files_prefix = project_etc / 'examples'
+example_config_files_prefix = project_etc_dir / 'examples'
 install_subdir('config', install_dir: example_config_files_prefix, strip_directory: true)
 
 # example source information

diff --git a/meson.build b/meson.build
@@ -175,8 +175,8 @@ endif
 project_inc       = include_directories('src')
 project_libs      = []
 project_deps      = declare_dependency(dependencies: dep_list) # do NOT include ROOT here
-project_etc       = get_option('sysconfdir') / meson.project_name()
-project_data      = get_option('datadir') / meson.project_name()
+project_etc_dir   = get_option('sysconfdir') / meson.project_name()
+project_data_dir  = get_option('datadir') / meson.project_name()
 project_test_env  = environment()
 project_pkg_vars  = [
   'bindir='            + '${prefix}' / get_option('bindir'),
@@ -209,8 +209,8 @@ project_test_env.set(
 # set preprocessor macros
 add_project_arguments(
   '-DIGUANA_PREFIX="' + get_option('prefix') + '"',
-  '-DIGUANA_ETCDIR="' + project_etc + '"',
-  '-DIGUANA_DATADIR="' + project_data + '"',
+  '-DIGUANA_ETCDIR="' + project_etc_dir + '"',
+  '-DIGUANA_DATADIR="' + project_data_dir + '"',
   language: ['cpp'],
 )
 
@@ -269,7 +269,7 @@ if get_option('z_install_envfile')
       'python': get_option('bind_python') ? 'true' : 'false',
       'libdir': get_option('libdir'),
       'root': ROOT_dep.found() ? 'true' : 'false',
-      'etcdir': project_etc,
+      'etcdir': project_etc_dir,
     },
   )
   foreach shell : [ 'csh', 'tcsh' ]

diff --git a/src/iguana/algorithms/meson.build b/src/iguana/algorithms/meson.build
@@ -218,7 +218,7 @@ install_headers(algo_headers, subdir: meson.project_name() / 'algorithms', prese
 foreach algo_datum : algo_data
   install_data(
     algo_data,
-    install_dir:   project_data / 'algorithms',
+    install_dir:   project_data_dir / 'algorithms',
     preserve_path: true,
   )
 endforeach
@@ -239,5 +239,5 @@ install_headers(vdor_headers, subdir: meson.project_name() / 'algorithms', prese
 
 # install config files
 foreach algo_config : algo_configs
-  install_data(algo_config, install_dir: project_etc / 'algorithms', preserve_path: true)
+  install_data(algo_config, install_dir: project_etc_dir / 'algorithms', preserve_path: true)
 endforeach