NAME
Env::Sourced - Allows you to import environment variables from a shell
program
SYNOPSIS
use Env::Sourced qw(/first/file/to/include.sh /second/file/to/include.sh);
DESCRIPTION
In the UNIX shell, when you source a file the shell reads and executes
the commands from a specified file in the current shell environment.
This is opposed to simply executing the specified file, which would
cause it to run in its own shell environment. Because the executed
script runs in the current environment, any environment variables
exported by the sub-script will be included in the calling scripts
environment.
On many boxes there are legacy shell scripts which serve as central
points for holding variables that are used in other scripts. These
variable scripts are sourced in all of the worker scripts so that they
can share a common environment.
This works fine for shell scripts, but can be problematic for Perl
scripts. To pick up the shared environment, they typically must be
wrapped by a shell script that does the sourcing for the Perl script:
#/bin/ksh
. /file/to/include.sh
$@
Or the Perl interpreter must be aliased to include the environment:
alias perl='. /file/to/include.sh;perl'
Or any one of many other hacks must be performed to get the correct
environment for your Perl scripts. And, in the end you have a script
that cannot run without having variables that are defined in another
script, but you have no clear note of what script needs to be included.
This is why "Env::Sourced" came about. It allows for you to specify in
your script what files are needed to set up the environment needed by
your script to run. It then takes these files and merges the environment
defined by them into your current environment. This allows your script
to access the sourced environment through the %ENV hash or directly
through scalars and arrays if you use Env.
To use the module, you simply include it in your code and tell it which
scripts to merge into your environment. The scripts will be processed in
the order in which they are passed to the module, so if they both set
the same variable, only the last setting will be kept.
use Env::Sourced qw(/first/file/to/include.sh /second/file/to/include.sh);
It is expected that the scripts that are being called will execute
cleanly. They can output to standard out and standard error (all output
will be passed through standard error anyway), but they must exit
without errors. If they do have errors, chance are you will get a
message like "Can't use an undefined value as a HASH reference..." and
your script will terminate.
INSTALL
This module is installed in the standard Perl style. Just run the
following commands and hope that you don't have any errors :)
perl Makefile.PL
make
make test
make install
BUGS/CAVEATS
* There are times when a script seems to be running fine when you
execute it on the command line, but it errors out when being sourced
by this module. One of the primary reasons for this is the combining
of variable setting and exporting in the same line in your shell
script. For instance, you might have:
export MY_VAR=xyz
And when you use the file with this module you get a "Can't use an
undefined value as a HASH reference" error. The common fix is to
split variable setting and exporting onto multiple lines:
MY_VAR=xyz
export MY_VAR
This is not required for all systems, but it has been known observed
on some systems.
AUTHOR
Josh McAdams <me@joshmcadams.com>