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