doc: env var usage

JeffersonLab · Jan 13, 2024 · ed00384 · ed00384
1 parent 78a9c50
commit ed00384
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 36 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -115,7 +115,6 @@ jobs:
             echo "| \`$dep\` | $($dep --version) |" >> $GITHUB_STEP_SUMMARY
           done
           if [ "${{ inputs.runner }}" = "macos-latest" ]; then
-            echo HOMEBREW_NO_COLOR=1 >> $GITHUB_ENV
             echo "| \`fmt\` | $(brew info fmt | head -n1) |" >> $GITHUB_STEP_SUMMARY
           else
             echo "| \`fmt\` | ${{ env.fmt_version }} |" >> $GITHUB_STEP_SUMMARY

diff --git a/doc/setup.md b/doc/setup.md
@@ -1,5 +1,11 @@
 # Setup Guide
 
+**Table of Contents**
+1. [Dependencies](#dependencies)
+1. [Building and Installing](#building)
+1. [Environment Variables (optional)](#env)
+
+<a name="dependencies"/>
 ## Dependencies
 
 The following sections list the dependencies and how to obtain them.
@@ -50,6 +56,7 @@ cmake --build build-hipo -j$(nproc)
 cmake --install build-hipo
 ```
 
+<a name="building"/>
 ## Building and Installing
 
 - For convenience, a configuration script is provided.
@@ -99,3 +106,33 @@ meson install -C build-iguana
 
 > [!TIP]
 > `configure.py` produces a native file (`.ini`) which may be used by `meson setup` option `--native-file`.
+
+
+<a name="env"/>
+## Environment Variables (optional)
+The C++ `iguana` implementation does not require the use of any environment variables. However,
+some language bindings may take advantage of environment variables being set, such as `$PYTHONPATH`
+for Python. The documentation will tell you if certain environment variables are recommended.
+
+You may prefer to set your own environment variables, but for a quick start with suggested settings,
+the installed file `bin/this_iguana.sh` may be used as
+```
+source bin/this_iguana.sh [OPTIONAL ARGUMENTS]...
+
+OPTIONAL ARGUMENTS:
+
+   ld       append library paths to LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH);
+            by default these variables are NOT modified
+
+   quiet    don't print anything
+```
+
+which may set or modify the following environment variables:
+
+| Variable                                                 | Modification                                                                                                                              |
+| ---                                                      | ---                                                                                                                                       |
+| `PKG_CONFIG_PATH`                                        | adds paths to the `pkg-config` files (`.pc`) for dependencies and `iguana`; see [note on dependency resolution](dependency_resolution.md) |
+| `PYTHONPATH`                                             | adds paths to dependency and `iguana` Python packages, if Python bindings are installed                                                   |
+| `LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (macOS) | adds paths to dependency and `iguana` libraries, if the optional argument `ld` was used                                                   |
+
+This file compatible with `bash` and `zsh, but not with `tcsh` or `csh`.
diff --git a/meson/this_iguana.sh.in b/meson/this_iguana.sh.in
@@ -1,39 +1,5 @@
 #!/bin/bash
-
-################################################################################
-#
-# `source` this file to set environment variables relevant for this `iguana`
-# installation. This file is compatible with `bash` and `zsh`, but not with
-# `tcsh`.
-#
-# In general, users should not be _required_ to `source` this file, since we
-# have tried to discourage the usage of environment variables in `iguana`;
-# however, there may be cases where a user may want to `source` this file, for
-# example:
-#  - if `LD_LIBRARY_PATH` has conflicting libraries.
-#  - if `pkg-config` paths are needed, _e.g_, for `pyiguana` (Python bindings)
-#
-# You may use any of the following arguments when sourcing this file, for example
-# `source this_iguana.sh quiet ld`
-#
-#   ld       append library paths to LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH);
-#            by default these variables are not modified
-#
-#   quiet    don't print anything
-#
-# The following environment variables may be set (depending on iguana build
-# options, user arguments, and operating system):
-#
-#   PKG_CONFIG_PATH     paths to the `pkg-config` files (extension `.pc`) for
-#                       dependencies; `pkg-config` is used in `iguana` for
-#                       dependency resolution
-#
-#   PYTHONPATH          paths to dependency and `iguana` Python packages
-#
-#   LD_LIBRARY_PATH     paths to dependency and `iguana` libraries (on Linux)
-#   DYLD_LIBRARY_PATH   paths to dependency and `iguana` libraries (on macOS)
-#
-################################################################################
+# `source` this file to set environment variables relevant for this `iguana` installation
 
 # find the iguana installation prefix, with respect to this file
 this_env=${BASH_SOURCE[0]:-$0}