#! /bin/sh

die () {
    echo >&2 "$@"
    exit 1
}

# try to handle all shells' reaction to globs which don't match (e.g. returning the glob on no match)
# try to handle spaces in globs
_glob () (
    set +o noglob
    for glob in "$@" ; do
        for direntry in $(eval echo "$glob" 2>/dev/null) ; do
            test -e "$direntry" && echo "$direntry"
        done
    done
)

_VARS () {
    echo                                        \
        INFOPATH                                \
        LD_LIBRARY_PATH                         \
        LUA_CPATH                               \
        LUA_PATH                                \
        MANPATH                                 \
        PATH					\
        PERL5LIB                                \
        PFILES                                  \
        SAOTRACE_BINDIR                         \
        SAOTRACE_LIBDIR                         \
        SAOTRACE_DIR                            \
        SAOTRACE_EXECDIR                        \
        SAOTRACE_DATADIR                        \
        SAOTRACE_DATAROOTDIR                    \
        SAOTRACE_VERSION                        \
        UDUNITS2_XML_PATH
}

set_perl_paths () {

    # if there's a compiled version of Perl, make sure its paths get relocated
    PERL="$SAOTRACE_BINDIR/perl"
    test -e "$PERL" || PERL="$SAOTRACE_PRIVATE_BINDIR/perl"
    local _perl5lib="$SAOTRACE_EXECDIR/lib/perl5:$SAOTRACE_EXECDIR/lib/perl5/site_perl"
    if [ -e "${PERL}" ]; then
        for dir in $("$PERL" -le 'print for @INC') ; do
            _perl5lib="$(relocate $dir):${_perl5lib}"
        done
    fi
    PERL5LIB="${_perl5lib}${PERL5LIB:+:$PERL5LIB}"
}

set_library_paths () {

    case "$(uname -s)" in

        Linux )
            LD_LIBRARY_PATH=$SAOTRACE_LIBDIR
            ;;

        Darwin )
            # This has to be done by rewriting fields in the executables; see finalize-saotrace
            ;;

    esac
}

set_lua_path () {
    lua_path='./?.lua'
    for path in $(_glob "$SAOTRACE_DATAROOTDIR/lua/*" "$SAOTRACE_DATAROOTDIR/lib/lua/*") ; do
        lua_path="${lua_path};$path/?.lua;$path/?/init.lua"
    done

    if [ -n "$LUA_PATH" ]; then
        LUA_PATH="$lua_path;$LUA_PATH"
    else
        LUA_PATH="$lua_path;;"
    fi
}

set_lua_cpath () {
    local lua_cpath='./?.so'
    for path in $(_glob "$SAOTRACE_EXECDIR/lib/lua/*");  do
        lua_cpath="${lua_cpath};$path/?.so;$path/loadall.so"
    done

    if [ -n "$LUA_CPATH" ]; then
        LUA_CPATH="$lua_cpath;$LUA_CPATH"
    else
        LUA_CPATH="$lua_cpath;;"
    fi
}

set_lua_paths () {
    set_lua_path
    set_lua_cpath
}

set_environment () {
    # The functions in this file provide support for relocatability of
# shell scripts.  They should be included near the beginning of each
# shell script in a relocatable program, by adding @relocatable_sh@
# and causing the script to be expanded with AC_CONFIG_FILES.  A
# small amount of additional code must be added and adapted to the
# package by hand; see doc/relocatable-maint.texi (in Gnulib) for
# details.
#
# Copyright (C) 2003-2014 Free Software Foundation, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#

# func_tmpdir
# creates a temporary directory.
# Sets variable
# - tmp             pathname of freshly created temporary directory
func_tmpdir ()
{
  # Use the environment variable TMPDIR, falling back to /tmp. This allows
  # users to specify a different temporary directory, for example, if their
  # /tmp is filled up or too small.
  : ${TMPDIR=/tmp}
  {
    # Use the mktemp program if available. If not available, hide the error
    # message.
    tmp=`(umask 077 && mktemp -d "$TMPDIR/glXXXXXX") 2>/dev/null` &&
    test -n "$tmp" && test -d "$tmp"
  } ||
  {
    # Use a simple mkdir command. It is guaranteed to fail if the directory
    # already exists.  $RANDOM is bash specific and expands to empty in shells
    # other than bash, ksh and zsh.  Its use does not increase security;
    # rather, it minimizes the probability of failure in a very cluttered /tmp
    # directory.
    tmp=$TMPDIR/gl$$-$RANDOM
    (umask 077 && mkdir "$tmp")
  } ||
  {
    echo "$0: cannot create a temporary directory in $TMPDIR" >&2
    { (exit 1); exit 1; }
  }
}

# Support for relocatability.
func_find_curr_installdir ()
{
  # Determine curr_installdir, even taking into account symlinks.
  curr_executable="$0"
  case "$curr_executable" in
    */* | *\\*) ;;
    *) # Need to look in the PATH.
      if test "${PATH_SEPARATOR+set}" != set; then
        # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which
        # contains only /bin. Note that ksh looks also at the FPATH variable,
        # so we have to set that as well for the test.
        PATH_SEPARATOR=:
        (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \
          && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \
                 || PATH_SEPARATOR=';'
             }
      fi
      save_IFS="$IFS"; IFS="$PATH_SEPARATOR"
      for dir in $PATH; do
        IFS="$save_IFS"
        test -z "$dir" && dir=.
        for exec_ext in ''; do
          if test -f "$dir/$curr_executable$exec_ext"; then
            curr_executable="$dir/$curr_executable$exec_ext"
            break 2
          fi
        done
      done
      IFS="$save_IFS"
      ;;
  esac
  # Make absolute.
  case "$curr_executable" in
    /* | ?:/* | ?:\\*) ;;
    *) curr_executable=`pwd`/"$curr_executable" ;;
  esac
  # Resolve symlinks.
  sed_dirname='s,/[^/]*$,,'
  sed_linkdest='s,^.* -> \(.*\),\1,p'
  while : ; do
    lsline=`LC_ALL=C ls -l "$curr_executable"`
    case "$lsline" in
      *" -> "*)
        linkdest=`echo "$lsline" | sed -n -e "$sed_linkdest"`
        case "$linkdest" in
          /* | ?:/* | ?:\\*) curr_executable="$linkdest" ;;
          *) curr_executable=`echo "$curr_executable" | sed -e "$sed_dirname"`/"$linkdest" ;;
        esac ;;
      *) break ;;
    esac
  done
  curr_installdir=`echo "$curr_executable" | sed -e 's,/[^/]*$,,'`
  # Canonicalize.
  curr_installdir=`cd "$curr_installdir" && pwd`
}
func_find_prefixes ()
{
  # Compute the original/current installation prefixes by stripping the
  # trailing directories off the original/current installation directories.
  orig_installprefix="$orig_installdir"
  curr_installprefix="$curr_installdir"
  while true; do
    orig_last=`echo "$orig_installprefix" | sed -n -e 's,^.*/\([^/]*\)$,\1,p'`
    curr_last=`echo "$curr_installprefix" | sed -n -e 's,^.*/\([^/]*\)$,\1,p'`
    if test -z "$orig_last" || test -z "$curr_last"; then
      break
    fi
    if test "$orig_last" != "$curr_last"; then
      break
    fi
    orig_installprefix=`echo "$orig_installprefix" | sed -e 's,/[^/]*$,,'`
    curr_installprefix=`echo "$curr_installprefix" | sed -e 's,/[^/]*$,,'`
  done
}
    prefix="/build/phase1"
    exec_prefix="/build/phase1"   # usually needs $prefix.
    datarootdir="${prefix}/share"   # usually needs $prefix.
    datadir="${datarootdir}"
    bindir="${exec_prefix}/bin"
    libdir="${exec_prefix}/lib"

    if test "yes" = yes; then
        orig_installdir="${bindir}" # see Makefile.am's *_SCRIPTS variables
        func_find_curr_installdir # determine curr_installdir
        func_find_prefixes
        relocate () {
            echo "$1/" \
                | sed -e "s%^${orig_installprefix}/%${curr_installprefix}/%" \
                | sed -e 's,/$,,'
        }
    else
        relocate () {
            echo "$1"
        }
    fi

    SAOTRACE_VERSION='2.0.6'
    SAOTRACE_DIR=$(relocate "${prefix}")
    SAOTRACE_BINDIR=$(relocate "${bindir}")
    SAOTRACE_LIBDIR=$(relocate "${libdir}")
    SAOTRACE_DATAROOTDIR=$(relocate "${datarootdir}")
    SAOTRACE_DATADIR=$(relocate "${datadir}")
    SAOTRACE_EXECDIR=$(relocate "${exec_prefix}")
    SAOTRACE_PRIVATE_DIR=$(relocate "${prefix}/private")
    SAOTRACE_PRIVATE_BINDIR=$(relocate "${prefix}/private/bin")
    test -d "$SAOTRACE_PRIVATE_BINDIR" || unset SAOTRACE_PRIVATE_BINDIR

    PATH="${SAOTRACE_BINDIR}:${SAOTRACE_PRIVATE_BINDIR}:${PATH}"
    set_lua_paths
    set_perl_paths
    set_library_paths

    MANPATH=$(relocate "${datarootdir}/man"):$MANPATH
    INFOPATH=$(relocate "${datarootdir}/info"):$INFOPATH

    if [ -z "$PFILES" ]; then
        PFILES="./;$SAOTRACE_DATAROOTDIR/uparm"
    else
        if echo "$PFILES" | grep ';' 1>/dev/null 2>&1 ; then
            PFILES=`echo "$PFILES" | sed -e "s,;,;$SAOTRACE_DATAROOTDIR/uparm:," -e 's/:$//g'`
        else
            PFILES="${PFILES};$SAOTRACE_DATAROOTDIR/uparm"
        fi
    fi

    UDUNITS2_XML_PATH="$SAOTRACE_DATAROOTDIR/udunits/udunits2.xml"
}

output_environment () {
    local fmt=$1

    # from https://www.etalabs.net/sh_tricks.html
    quote () { printf '%s\n' "$1" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/'/" ; }
    value () { eval quote "\${$1}" ; }

    case $fmt in

        sh )
            first () { :; }
            output () { echo "$1=$2; export $1;" ; }
            last () { :; }
            ;;

        bash|dash|zsh|ksh )
            first () { :; }
            output () { echo "export $1=$2;" ; }
            last () { :; }
            ;;

        csh|tcsh )
            first () { :; }
            output () { echo "setenv $1 $2;" ; }
            last () { :; }
            ;;

        yaml )
            first () { echo '---'; }
            output () { echo "$1: $2"; }
            value () { eval "echo \${$1}" ; }
            last () { :; }
            ;;

        -list )
            echo sh bash zsh ksh csh tcsh yaml
            return 0
            ;;

        *)
            die "unknown output format: $fmt"
            ;;

    esac


    set_environment
    first

    for var in $(_VARS)
    do
        local _value=$(value $var)
        test "$_value" = "''" && continue
        output $var "$_value"
    done
    last
}

help_setup () {
    set_environment

    cat <<EOF
Howdy!

You are here because you attempted to source

  $SAOTRACE_BINDIR/saotrace_setup.sh

and something went wrong.  This is probably because you are using a
shell which isn't supported directly by saotrace_setup.sh

In the future, to set up the SAOTrace environment, you should run the
following command

   eval \`$SAOTRACE_BINDIR/saotrace-env --fmt=$setup_shell\`

Please note that the single quotes above are "back-ticks", not "apostrophes".

EOF
}

help () {
    cat <<EOF
usage: saotrace-env [options]

  Options
  --fmt=FMT            output environment variables in the specified format
                       use --fmt=-list to list formats
  -h,--help            output short usage instructions and exit
  --man,--manual       output a manual page and exit
  --list-env-vars      list enviroment variables output
  -v,--version         output version informaiton and exit
EOF
}

_roff () {
        local file=$1
        sed -n -e '
/^# <<< roff/,/^# >>> roff/{
/^# <<< roff/d
/^# >>> roff/d
p
}
' $0 > "$file"
        test $? -ne 0 && die "unable to create temporary file"
}


manual () {
    local TMP_PFX=/tmp/saotrace-env-$$
    local tmpfile
    tmpfile=$(mktemp -- "$TMP_PFX.XXXXXXX")
    test $? -ne 0 && die "unable to create temporary file"
    _roff $tmpfile
    man $tmpfile
}

fmt=sh
dump_to_stderr=0
while [ $# -gt 0 ]
do
    arg=$1
    case $arg in

        --clean-env )
            unset $(_VARS)
            PATH=/usr/local/bin:/usr/bin:/bin
            ;;

        --fmt=* )
            fmt=${arg#--fmt=}
            ;;

        --fmt | -f )
            shift
            test $# -ne 0 || die "missing argument to $arg"
            fmt=$1
            ;;

        --dump-to-stderr )
            dump_to_stderr=1
            ;;

        --list-env-vars )
            for var in $(_VARS) ; do echo $var ; done
            exit 0
            ;;

        --help-setup=* )
            setup_shell=${arg#--help-setup=}
            help_setup
            exit 0
            ;;

        --help|-h )
            help
            exit 0
            ;;

        --manual|--man )
            manual
            exit 0
            ;;

        -v|--version)
              echo 'saotrace-env 1.1.4'
              exit 0
              ;;

        -x )
            set -x
            ;;

        *)
            die "unknown option to $0: $arg"
            ;;
    esac
    shift
done

output_environment "$fmt"
if [ $dump_to_stderr -ne 0 ]; then
    output_environment "$fmt" >&2
fi

exit 0

# <<< roff
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "aotrace-env 1"
.TH aotrace-env 1 "2023-02-22" "1.1.3_01" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& saotrace\-env \- output environment variables required to run SAOTrace
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& saotrace\-env [options]
\&
\& # output and evaluate zsh compatible shell commands
\& eval \`saotrace\-env \-\-fmt=zsh\`
\&
\& # output and evaluate bash compatible shell commands
\& eval \`saotrace\-env \-\-fmt=bash\`
\&
\& # output and evaluate csh compatible shell commands
\& eval \`saotrace\-env \-\-fmt=csh\`
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBsaotrace-env\fR generates environment variables required to run SAOTrace.
.PP
Typical use is to generate commands for a shell to set the environment
and evaluate those commands.  For example,
.PP
.Vb 1
\&  eval \`saotrace \-\-fmt=zsh\`
.Ve
.SH "OPTIONS AND ARGUMENTS"
.IX Header "OPTIONS AND ARGUMENTS"
.IP "\-\-fmt=\fIformat\fR" 4
.IX Item "--fmt=format"
Specify the output format.  To list all of the possible formats, set \f(CW\*(C`\-\-fmt=\-list\*(C'\fR.
.Sp
The available formats are:
.RS 4
.ie n .IP """bash"" | ""csh"" | ""dash"" | ""ksh"" | ""tcsh"" | ""zsh""" 4
.el .IP "\f(CWbash\fR | \f(CWcsh\fR | \f(CWdash\fR | \f(CWksh\fR | \f(CWtcsh\fR | \f(CWzsh\fR" 4
.IX Item "bash | csh | dash | ksh | tcsh | zsh"
Output commands to set the environment for the specified shell.
.IP "yaml" 4
.IX Item "yaml"
Output the environment variables as a \s-1YAML\s0 document
.RE
.RS 4
.RE
.IP "\-\-help" 4
.IX Item "--help"
output short usage instructions and exit
.IP "\-\-manual" 4
.IX Item "--manual"
output a manual page and exit
.IP "\-\-list\-env\-vars" 4
.IX Item "--list-env-vars"
list the names of the environment variables which are output
.IP "\-\-version" 4
.IX Item "--version"
output version informaiton and exit
.SH "RELOCATABLE EXECUTION"
.IX Header "RELOCATABLE EXECUTION"
The ability to move the SAOTrace installation to another location and
run it from there makes it \fIrelocatable\fR.
.PP
There are two components to making it relocatable.
.IP "\(bu" 4
At runtime SAOTrace needs access to bundled data, and finds them
via environment variables.
.IP "\(bu" 4
The system linker must locate all of the libraries which are used by
the executables.  Each operating system has a unique method of doing
so.  For Linux, it is possible to use the \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR
environment variable to override the paths written into the executable
and library binary files.  For Mac \s-1OS,\s0 the paths in the files must
be rewritten.
.PP
\&\fBsaotrace-env\fR can only modify environment variables; rwriting the
executable and library binary files must be done (once) by another
tool (e.g. finalize-saotrace).
.PP
To avoid having the user source a setup file to run SAOTrace, it is
possible (and is actually done in practice by finalize-saotrace) to
wrap the executable with a slim \s-1POSIX\s0 shell compatible wrapper, like so:
.PP
.Vb 5
\&  #!/bin/sh
\&  parent=${0%/*}/../
\&  test \-z "$SAOTRACE_BINDIR" && eval $(${parent}/bin/saotrace\-env \-\-fmt=sh)
\&  PATH="${parent}/xbin:${PATH}"
\&  exec @EXE@ "$@"
.Ve
.PP
where \f(CW\*(C`@EXE@\*(C'\fR is eplaced by the name of the executable. This relies upon
the original executable being available in a parallel path (\f(CW\*(C`xbin\*(C'\fR).
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright the Smithsonian Astrophysical Observatory
and is released under the \s-1GNU\s0 General Public License.  You may find a
copy at <http://www.fsf.org/copyleft/gpl.html>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Diab Jerius <djerius@cfa.harvard.edu>
# >>> roff

=pod

=head1 NAME

 saotrace-env - output environment variables required to run SAOTrace

=head1 SYNOPSIS

 saotrace-env [options]

 # output and evaluate zsh compatible shell commands
 eval `saotrace-env --fmt=zsh`

 # output and evaluate bash compatible shell commands
 eval `saotrace-env --fmt=bash`

 # output and evaluate csh compatible shell commands
 eval `saotrace-env --fmt=csh`

=head1 DESCRIPTION

B<saotrace-env> generates environment variables required to run SAOTrace.

Typical use is to generate commands for a shell to set the environment
and evaluate those commands.  For example,

  eval `saotrace --fmt=zsh`

=head1 OPTIONS AND ARGUMENTS

=over

=item --fmt=I<format>

Specify the output format.  To list all of the possible formats, set C<--fmt=-list>.

The available formats are:

=over

=item C<bash> | C<csh> | C<dash> | C<ksh> | C<tcsh> | C<zsh>

Output commands to set the environment for the specified shell.

=item yaml

Output the environment variables as a YAML document

=back

=item --help

output short usage instructions and exit

=item --manual

output a manual page and exit

=item --list-env-vars

list the names of the environment variables which are output

=item --version

output version informaiton and exit

=back

=head1 RELOCATABLE EXECUTION

The ability to move the SAOTrace installation to another location and
run it from there makes it I<relocatable>.

There are two components to making it relocatable.

=over

=item *

At runtime SAOTrace needs access to bundled data, and finds them
via environment variables.

=item *

The system linker must locate all of the libraries which are used by
the executables.  Each operating system has a unique method of doing
so.  For Linux, it is possible to use the C<LD_LIBRARY_PATH>
environment variable to override the paths written into the executable
and library binary files.  For Mac OS, the paths in the files must
be rewritten.

=back

B<saotrace-env> can only modify environment variables; rwriting the
executable and library binary files must be done (once) by another
tool (e.g. L<finalize-saotrace>).

To avoid having the user source a setup file to run SAOTrace, it is
possible (and is actually done in practice by L<finalize-saotrace>) to
wrap the executable with a slim POSIX shell compatible wrapper, like so:

  #!/bin/sh
  parent=${0%/*}/../
  test -z "$SAOTRACE_BINDIR" && eval $(${parent}/bin/saotrace-env --fmt=sh)
  PATH="${parent}/xbin:${PATH}"
  exec @EXE@ "$@"

where C<@EXE@> is eplaced by the name of the executable. This relies upon
the original executable being available in a parallel path (C<xbin>).

=head1 COPYRIGHT AND LICENSE

This software is copyright the Smithsonian Astrophysical Observatory
and is released under the GNU General Public License.  You may find a
copy at L<http://www.fsf.org/copyleft/gpl.html>.

=head1 AUTHOR

Diab Jerius E<lt>djerius@cfa.harvard.eduE<gt>
