App::Env App::Env presents a uniform interface to initializing environments for applications which require special environments. App::Env only handles the loading, merging, and caching of environments; it does not create them. That is done within modules for each application suite (e.g. App::Env::MyApp). App::Env ships with two such modules, App::Env::Null which simply returns a snapshot of the current environment, and App::Env::Example, which provides example code for creating an application specific environment. App::Env is probably most useful in situations where a Perl program must invoke multiple applications each of which may require an environment different and possibly incompatible from the others. The simplified interface it provides makes it useful even in less complicated situations. Initializing Application Environments As mentioned above, App::Env does not itself provide the environments for applications; it relies upon application specific Perl modules to do so. Such modules must provide an envs() function which should return a hash reference containing the environment. Application specific options (e.g. version) may be passed to the module. See App::Env::Example for information on how to write such modules. Managing Environments In the simplest usage, App::Env can merge ("import") the application's environment directly into the current environment. For situations where multiple incompatible environments are required, it can encapsulate those as objects with convenience methods to easily run applications within those environments. Environment Caching Environments are (by default) cached to improve performance; the default cache id is generated from the name of the Perl module which creates the environment and the options passed to it. signature. When a environment is requested its signature is compared against those stored in the cache and if matched, the associated cached environment is returned. The cache id is (by default) generated from the full module name (beginning with "App::Env" and including the optional site path -- see "Site Specific Contexts") and the contents of the AppOpts hash passed to the module. If the AppOpts hash is empty, the id is just the module name. The cache id may be explicitly specified with the "CacheID" option. If "CacheID" is set to the string "AppID" the cache id is set to the full module name, ignoring the contents of AppOpts. This is useful if an application wishes to load an environment using special options but make it available under the more generic cache id. To prevent caching, use the "Cache" option. It doesn't prevent App::Env from *retrieving* an existing cached environment -- to do that, use the "Force" option, which will result in a freshly generated environment. To retrieve a cached environment using its cache id use the retrieve() function. If multiple applications are loaded via a single call to import or new the applications will be loaded incrementally in the order specified. In order to ensure a properly merged environment the applications will be loaded freshly (any caches will be ignored) and the merged environment will be cached. The cache id will by default be generated from all of the names of the environment modules invoked; again, this can be overridden using the CacheID option. Application Aliases App::Env performs a case-insensitive search for application modules. For example, if the application module is named App::Env::CIAO, a request for "ciao" will resolve to it. Explicit aliases are also possible. A module should be created for each alias with the single class method alias which should return the name of the original application. For example, to make "App3" be an alias for "App1" create the following App3.pm module: package App::Env::App3; sub alias { return 'App1' }; 1; The aliased environment can provide presets for AppOpts by returning a hash as well as the application name: package App::Env::ciao34; sub alias { return 'CIAO', { Version => 3.4 } }; 1; These will be merged with any "AppOpts" passed in via import(), with the latter taking precedence. Site Specific Contexts In some situations an application's environment will depend upon which host or network it is executed on. In such instances App::Env provides a means for loading an alternate application module. It does this by loading the first existent module from the following set of module names: App::Env::$SITE::$app App::Env::$app The default value for $SITE is determined when "App::Env" is first loaded. If the environment variable "APP_ENV_SITE" exists it is set to that, otherwise if the "App::Env::Site" module exists, that is loaded. It should set the "APP_ENV_SITE" variable. After this, modifications to "APP_ENV_SITE" are ignored. The default value may be overridden via the Site option passed to the class import() function or the new() object constructor. Take as an example the situation where an application's environment is stored in /usr/local/myapp/setup on one host and /opt/local/myapp/setup on another. One could include logic in a single "App::Env::myapp" module which would recognize which file is appropriate. If there are multiple applications, this gets messy. A cleaner method is to have separate site-specific modules (e.g. "App::Env::LAN1::myapp" and "App::Env::LAN2::myapp"), and switch between them based upon the APP_ENV_SITE environment variable. The logic for setting that variable might be encoded in an App::Env::Site module to transparently automate things: package App::Env::Site; my %LAN1 = map { ( $_ => 1 ) } qw( sneezy breezy queasy ); my %LAN2 = map { ( $_ => 1 ) } qw( dopey mopey ropey ); use Sys::Hostname; if ( $LAN1{hostname()} ) { $ENV{APP_ENV_SITE} = 'LAN1'; } elsif ( $LAN2{hostname()} ) { $ENV{APP_ENV_SITE} = 'LAN2'; } 1; The Null Environment App::Env provides the "null" environment, which simply returns a snapshot of the current environment. This may be useful to provide fall-backs in case an application specific environment was not found, but the code should fallback to using the existing environment. $env = eval { App::Env->new( "MyApp" ) } \ // App::Env->new( "null", { Force => 1, Cache => 0 } ); As the "null" environment is a *snapshot* of the current environment, if future "null" environments should reflect the environment at the time they are constructed, C"null" environments should not be cached (e.g. "Cache => 0"). The "Force => 1" option is specified to ensure that the environment is not being read from cache, just in case a prior "null" environment was inadvertently cached. INSTALLATION This is a Perl module distribution. It should be installed with whichever tool you use to manage your installation of Perl, e.g. any of cpanm . cpan . cpanp -i . Consult http://www.cpan.org/modules/INSTALL.html for further instruction. Should you wish to install this module manually, the procedure is perl Build.PL ./Build ./Build test ./Build install COPYRIGHT AND LICENSE This software is Copyright (c) 2018 by Smithsonian Astrophysical Observatory. This is free software, licensed under: The GNU General Public License, Version 3, June 2007