bin/run_stem

   1 #!/usr/bin/perl -w
   2
   3 eval 'exec /usr/bin/perl -w -S $0 ${1+"$@"}'
   4     if 0; # not running under some shell
   5 #  File: bin/run_stem
   6
   7 #  This file is part of Stem.
   8 #  Copyright (C) 1999, 2000, 2001 Stem Systems, Inc.
   9
  10 #  Stem is free software; you can redistribute it and/or modify
  11 #  it under the terms of the GNU General Public License as published by
  12 #  the Free Software Foundation; either version 2 of the License, or
  13 #  (at your option) any later version.
  14
  15 #  Stem is distributed in the hope that it will be useful,
  16 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 #  GNU General Public License for more details.
  19
  20 #  You should have received a copy of the GNU General Public License
  21 #  along with Stem; if not, write to the Free Software
  22 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23
  24 #  For a license to use the Stem under conditions other than those
  25 #  described here, to purchase support for this software, or to purchase a
  26 #  commercial warranty contract, please contact Stem Systems at:
  27
  28 #       Stem Systems, Inc.              781-643-7504
  29 #       79 Everett St.                  info@stemsystems.com
  30 #       Arlington, MA 02474
  31 #       USA
  32
  33
  34 eval { use lib 'blib/lib' } if -d 'blib/lib';
  35 eval { use lib '../blib/lib' } if -d '../blib/lib';
  36
  37 $Data::Dumper::Indent = 1 ;
  38 $Data::Dumper::Purity = 1 ;
  39 $Data::Dumper::Useqq = 1 ;
  40
  41 $| = 1 ;
  42
  43 #print "RUN STEM $0\n" ;
  44
  45 my @conf_args ;
  46
  47 # we set Stem's default environment before we load any Stem modules so
  48 # they can use those values
  49
  50 use Stem::InstallConfig ;
  51
  52 BEGIN {
  53         my $env_text ;
  54         my $stem_lib_dir = $Stem::InstallConfig::Config{'conf_path'} ;
  55
  56         my $is_win32 = $^O =~ /Win32/i ;
  57
  58 # get the site env and home env files
  59
  60         my @env_files = "$stem_lib_dir/env" ;
  61
  62         unless ( $is_win32 ) {
  63
  64                 push @env_files, ( $ENV{HOME} ||
  65                                    $ENV{LOGDIR} ||
  66                                    (getpwuid($>))[7] ) . '/.stem_env' ;
  67         }
  68
  69         foreach my $env_file ( @env_files ) {
  70
  71                 next unless -r $env_file ;
  72
  73 # shut up a dumb warning
  74                 use vars '*ARGVOUT' ;
  75                 $env_text .=
  76                         do { local( @ARGV, $/ ) = $env_file ; <> } ;
  77         }
  78
  79
  80 # set the starting %env from the files
  81
  82         %Stem::Vars::Env = $env_text =~ /^([^=]+)=(.+)$/mg if $env_text ;
  83
  84
  85 # set the %Stem::Vars::Env from %ENV any %ENV name starting with STEM_
  86 # is used. the STEM_ is deleted and the rest of the lower case name is
  87 # used with the %ENV value
  88
  89         /^STEM_(\w+)/ and $Stem::Vars::Env{ lc $1 } = $ENV{ $_ } for keys %ENV ;
  90
  91 # set %Stem::Vars::Env from 'name=value' command line args
  92 # all other args are assumed to be conf file names.
  93 # we do this after we process %ENV so the command line args can override
  94 # any shell environment values
  95
  96         while( @ARGV ) {
  97
  98                 my $arg = shift ;
  99
 100                 if ( $arg =~ /([^=]+)=(.*)/ ) {
 101
 102                         $Stem::Vars::Env{ $1 } = $2 ;
 103                         next ;
 104                 }
 105
 106                 push @conf_args, $arg ;
 107         }
 108
 109 # set the default config search path. this will be changed by the install
 110 # script.
 111
 112         $Stem::Vars::Env{ 'conf_path' } ||= 'conf:.' ;
 113
 114 # set the trace levels
 115
 116 #       $Stem::Vars::Env{ 'MainTraceStatus'    } ||= 1 ;
 117 #       $Stem::Vars::Env{ 'MainTraceError'     } ||= 1 ;
 118 #       $Stem::Vars::Env{ 'ProcTraceStatus'    } ||= 1 ;
 119 #       $Stem::Vars::Env{ 'ProcTraceError'     } ||= 1 ;
 120 #       $Stem::Vars::Env{ 'PortalTraceStatus'  } ||= 1 ;
 121 #       $Stem::Vars::Env{ 'PortalTraceError'   } ||= 1 ;
 122 #       $Stem::Vars::Env{ 'SockMsgTraceStatus' } ||= 1 ;
 123 #       $Stem::Vars::Env{ 'SockMsgTraceError'  } ||= 1 ;
 124 #       $Stem::Vars::Env{ 'ConfTraceStatus'    } ||= 1 ;
 125 #       $Stem::Vars::Env{ 'ConfTraceError'     } ||= 1 ;
 126 #       $Stem::Vars::Env{ 'LogTraceStatus'     } ||= 1 ;
 127 #       $Stem::Vars::Env{ 'LogTraceError'      } ||= 1 ;
 128 #       $Stem::Vars::Env{ 'CellTraceStatus'    } ||= 0 ;
 129 #       $Stem::Vars::Env{ 'CronTraceStatus'    } ||= 1 ;
 130 #       $Stem::Vars::Env{ 'CronTraceError'     } ||= 1 ;
 131 #       $Stem::Vars::Env{ 'EventTraceStatus'   } ||= 0 ;
 132 #       $Stem::Vars::Env{ 'EventTraceError'    } ||= 0 ;
 133 #       $Stem::Vars::Env{ 'GatherTraceStatus'  } ||= 1 ;
 134 #       $Stem::Vars::Env{ 'GatherTraceError'   } ||= 1 ;
 135 #       $Stem::Vars::Env{ 'HubTraceStatus'     } ||= 1 ;
 136 #       $Stem::Vars::Env{ 'HubTraceError'      } ||= 1 ;
 137 #       $Stem::Vars::Env{ 'TailTraceStatus'    } ||= 1 ;
 138 #       $Stem::Vars::Env{ 'TailTraceError'     } ||= 1 ;
 139 #       $Stem::Vars::Env{ 'MsgTraceError'      } ||= 1 ;
 140 #       $Stem::Vars::Env{ 'MsgTraceStatus'     } ||= 1 ;
 141 #       $Stem::Vars::Env{ 'MsgTraceMsg'        } ||= 1 ;
 142 #       $Stem::Vars::Env{ 'SwitchTraceStatus'  } ||= 1 ;
 143 #       $Stem::Vars::Env{ 'SwitchTraceError'   } ||= 1 ;
 144 #       $Stem::Vars::Env{ 'AsynchIOTraceStatus'} ||= 1 ;
 145 #       $Stem::Vars::Env{ 'AsynchIOTraceError' } ||= 1 ;
 146 #       $Stem::Vars::Env{ 'TtyMsgTraceStatus'  } ||= 1 ;
 147 #       $Stem::Vars::Env{ 'TtyMsgTraceError'   } ||= 1 ;
 148
 149 }
 150
 151 # we load Stem after we process the command line args and %ENV so the
 152 # modules can use those values
 153
 154 use Stem ;
 155
 156 use Stem::Trace 'log' => 'stem_status',
 157                 'sub' => 'TraceStatus',
 158                 'env' => 'MainTraceStatus' ;
 159
 160 my $prog_name = $0 ;
 161
 162 $prog_name =~ s|.+/|| ;
 163
 164 unless ( @conf_args ) {
 165
 166         $prog_name eq 'run_stem' &&
 167                         die "run_stem must be passed a stem config file" ;
 168
 169         @conf_args = $prog_name ;
 170 }
 171
 172 # always start with the site config file
 173 # this defines site wide configuration settings that are internal
 174 # to Stem
 175
 176 my $err = Stem::Conf::load_confs( 'site' ) ;
 177
 178 # ignore a missing site config
 179
 180 die $err if defined $err && $err !~ /Can't find config/ ;
 181
 182 $err = Stem::Conf::load_confs( @conf_args ) ;
 183
 184 TraceStatus "Stem startup" ;
 185
 186 TraceStatus $err if $err;
 187
 188 die $err if $err ;
 189
 190 ###############
 191 # this should use Stem::Event
 192 ###############
 193 $SIG{ 'INT' } = sub {
 194         TraceStatus "INT signal received" ;
 195         Stem::Event::stop_loop()
 196 } ;
 197
 198 Stem::Event::start_loop() ;
 199
 200 TraceStatus "Stem shutdown" ;
 201
 202 exit;
 203
 204 =head1 run_stem - Start up Stem and load configuration files
 205
 206 =head2 Synopsis
 207
 208         run_stem foo=bar stem_conf_file
 209
 210 This script is the way most Stem applications are started. It does
 211 several important things so you don't have to create your own top
 212 level scripts. It is not required to execute run_stem to use Stem but
 213 it makes it much easier to get it going in most cases. The following
 214 are the steps that 'run_stem' does when bringing up Stem.
 215
 216 =head2 * Load Stem Environment
 217
 218 Many Stem modules and cells look at the Stem environment for default
 219 configuration values or global flags. This allows you to control how
 220 many of the cells and modules behave when loaded and instantiated.  If
 221 a Stem attribute in a specification has its 'env' name description
 222 set, it will use that name (optionally prefixed with the cell's
 223 registration name) as a key to lookup in the Stem Environement. If
 224 found there, that value becomes is used and overrides the default and
 225 any value set in a configuration file. This allows the user to
 226 override default setting from the outside without modifying Stem
 227 configuration files. See Stem::Class for more on this.  The Stem
 228 environment is set from these sources in the following order:
 229
 230 =over 4
 231
 232 =item Global Site Environment File
 233
 234 'run_stem' initially looks for a file named 'env' in the first
 235 configuration directory (set at install time) and loads it if
 236 found. These site and user files both have a simple key=value format
 237 with one entry per line.
 238
 239 =item User Environment File
 240
 241 'run_stem' then will look in your home directory (not supported on
 242 windows) for a file named .stem_env and loads it if found.
 243
 244 =item Shell Environment
 245
 246 Any shell environment variable with the form 'STEM_*' will
 247 have the 'STEM_' part deleted and the rest of its name
 248 converted to lower case. That will become the key in the Stem
 249 environment with the value set to the shell variable's value.
 250
 251 =item Command Line
 252
 253 Any command line arguments of the form key=value will be
 254 parsed out and used to set a Stem environment variable.
 255
 256 =back
 257
 258 =head2 * Load Stem Core Modules
 259
 260         'run_stem' then loads all the core Stem modules with a use
 261         Stem line.
 262
 263 =head2 * Load Configuration Files
 264
 265 Any arguments left in @ARGV are assumed to be Stem configuration
 266 files. Typically there is only one configuration file but you can have
 267 pass in as many as you want.  The config file arguments can have a
 268 .stem suffix or no suffix. The configuration directory list is
 269 searched in order for the file and it is loaded and all of its entries
 270 are constructed.
 271
 272 You can override the default configuration directory list (set at
 273 install time) by setting the 'conf_path' Stem environment variable
 274 from the shell environment or on the 'run_stem' command line. The
 275 following are equivilent:
 276
 277         export STEM_CONF_PATH=/etc/stem/conf:/home/foo/.stem
 278         run_stem bar
 279
 280         run_stem conf_path=/etc/stem/conf:/home/foo/.stem bar
 281
 282 =head2 * Start Event Loop
 283
 284 The final operation 'run_stem' does is start the main event
 285 loop. If no events were created by the loaded configuration
 286 files, this will fail and 'run_stem will exit immediately. If
 287 all the created events eventually get canceled, the event loop
 288 will exit and 'run_stem' will exit too.
 289
 290 =cut