From ed00384b5ceae525c02d356c95eab266bb334cf6 Mon Sep 17 00:00:00 2001 From: Christopher Dilks Date: Sat, 13 Jan 2024 17:28:07 -0500 Subject: [PATCH] doc: env var usage --- .github/workflows/ci.yml | 1 - doc/setup.md | 37 +++++++++++++++++++++++++++++++++++++ meson/this_iguana.sh.in | 36 +----------------------------------- 3 files changed, 38 insertions(+), 36 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f7a4cc5a..e460ac9b 100644 --- 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 index 5d51af01..19df8661 100644 --- 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) + + ## 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 ``` + ## 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`. + + + +## 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 index ffbb040b..a20ad04b 100644 --- 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}