[urisagit/Stem.git] / bin / run_stem

#!/usr/bin/perl -w

eval 'exec /usr/bin/perl -w -S $0 ${1+"$@"}'
    if 0; # not running under some shell
#  File: bin/run_stem

#  This file is part of Stem.
#  Copyright (C) 1999, 2000, 2001 Stem Systems, Inc.

#  Stem 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 2 of the License, or
#  (at your option) any later version.

#  Stem 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 Stem; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

#  For a license to use the Stem under conditions other than those
#  described here, to purchase support for this software, or to purchase a
#  commercial warranty contract, please contact Stem Systems at:

#       Stem Systems, Inc.		781-643-7504
#  	79 Everett St.			info@stemsystems.com
#  	Arlington, MA 02474
#  	USA


eval { use lib 'blib/lib' } if -d 'blib/lib';
eval { use lib '../blib/lib' } if -d '../blib/lib';

$Data::Dumper::Indent = 1 ;
$Data::Dumper::Purity = 1 ;
$Data::Dumper::Useqq = 1 ;

$| = 1 ;

#print "RUN STEM $0\n" ;

my @conf_args ;

# we set Stem's default environment before we load any Stem modules so
# they can use those values

use Stem::InstallConfig ;

BEGIN {
	my $env_text ;
	my $stem_lib_dir = $Stem::InstallConfig::Config{'conf_path'} ;

	my $is_win32 = $^O =~ /Win32/i ;

# get the site env and home env files

	my @env_files = "$stem_lib_dir/env" ;

	unless ( $is_win32 ) {

		push @env_files, ( $ENV{HOME} ||
				   $ENV{LOGDIR} ||
				   (getpwuid($>))[7] ) . '/.stem_env' ;
	}

	foreach my $env_file ( @env_files ) {

		next unless -r $env_file ;

# shut up a dumb warning
		use vars '*ARGVOUT' ;
		$env_text .= 
			do { local( @ARGV, $/ ) = $env_file ; <> } ;
	}


# set the starting %env from the files

	%Stem::Vars::Env = $env_text =~ /^([^=]+)=(.+)$/mg if $env_text ;


# set the %Stem::Vars::Env from %ENV any %ENV name starting with STEM_
# is used. the STEM_ is deleted and the rest of the lower case name is
# used with the %ENV value

	/^STEM_(\w+)/ and $Stem::Vars::Env{ lc $1 } = $ENV{ $_ } for keys %ENV ;

# set %Stem::Vars::Env from 'name=value' command line args
# all other args are assumed to be conf file names.
# we do this after we process %ENV so the command line args can override
# any shell environment values

	while( @ARGV ) {

		my $arg = shift ;

		if ( $arg =~ /([^=]+)=(.*)/ ) {

			$Stem::Vars::Env{ $1 } = $2 ;
			next ;
		}

		push @conf_args, $arg ;
	}

# set the default config search path. this will be changed by the install
# script.

	$Stem::Vars::Env{ 'conf_path' } ||= 'conf:.' ;

# set the trace levels

# 	$Stem::Vars::Env{ 'MainTraceStatus'    } ||= 1 ;
# 	$Stem::Vars::Env{ 'MainTraceError'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'ProcTraceStatus'    } ||= 1 ;
# 	$Stem::Vars::Env{ 'ProcTraceError'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'PortalTraceStatus'  } ||= 1 ;
# 	$Stem::Vars::Env{ 'PortalTraceError'   } ||= 1 ;
# 	$Stem::Vars::Env{ 'SockMsgTraceStatus' } ||= 1 ;
# 	$Stem::Vars::Env{ 'SockMsgTraceError'  } ||= 1 ;
# 	$Stem::Vars::Env{ 'ConfTraceStatus'    } ||= 1 ;
# 	$Stem::Vars::Env{ 'ConfTraceError'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'LogTraceStatus'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'LogTraceError'      } ||= 1 ;
# 	$Stem::Vars::Env{ 'CellTraceStatus'    } ||= 0 ;
# 	$Stem::Vars::Env{ 'CronTraceStatus'    } ||= 1 ;
# 	$Stem::Vars::Env{ 'CronTraceError'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'EventTraceStatus'   } ||= 0 ;
# 	$Stem::Vars::Env{ 'EventTraceError'    } ||= 0 ;
# 	$Stem::Vars::Env{ 'GatherTraceStatus'  } ||= 1 ;
# 	$Stem::Vars::Env{ 'GatherTraceError'   } ||= 1 ;
# 	$Stem::Vars::Env{ 'HubTraceStatus'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'HubTraceError'      } ||= 1 ;
# 	$Stem::Vars::Env{ 'TailTraceStatus'    } ||= 1 ;
# 	$Stem::Vars::Env{ 'TailTraceError'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'MsgTraceError'      } ||= 1 ;
# 	$Stem::Vars::Env{ 'MsgTraceStatus'     } ||= 1 ;
# 	$Stem::Vars::Env{ 'MsgTraceMsg'        } ||= 1 ;
# 	$Stem::Vars::Env{ 'SwitchTraceStatus'  } ||= 1 ;
# 	$Stem::Vars::Env{ 'SwitchTraceError'   } ||= 1 ;
# 	$Stem::Vars::Env{ 'AsynchIOTraceStatus'} ||= 1 ;
# 	$Stem::Vars::Env{ 'AsynchIOTraceError' } ||= 1 ;
# 	$Stem::Vars::Env{ 'TtyMsgTraceStatus'  } ||= 1 ;
# 	$Stem::Vars::Env{ 'TtyMsgTraceError'   } ||= 1 ;

}

# we load Stem after we process the command line args and %ENV so the
# modules can use those values

use Stem ;

use Stem::Trace 'log' => 'stem_status',
		'sub' => 'TraceStatus',
		'env' => 'MainTraceStatus' ;

my $prog_name = $0 ;

$prog_name =~ s|.+/|| ;

unless ( @conf_args ) {

	$prog_name eq 'run_stem' &&
			die "run_stem must be passed a stem config file" ;

	@conf_args = $prog_name ;
}

# always start with the site config file
# this defines site wide configuration settings that are internal
# to Stem

my $err = Stem::Conf::load_confs( 'site' ) ;

# ignore a missing site config

die $err if defined $err && $err !~ /Can't find config/ ;

$err = Stem::Conf::load_confs( @conf_args ) ;

TraceStatus "Stem startup" ;

TraceStatus $err if $err;

die $err if $err ;

###############
# this should use Stem::Event
###############
$SIG{ 'INT' } = sub {
	TraceStatus "INT signal received" ;
	Stem::Event::stop_loop()
} ;

Stem::Event::start_loop() ;

TraceStatus "Stem shutdown" ;

exit;

=head1 run_stem - Start up Stem and load configuration files

=head2 Synopsis

	run_stem foo=bar stem_conf_file

This script is the way most Stem applications are started. It does
several important things so you don't have to create your own top
level scripts. It is not required to execute run_stem to use Stem but
it makes it much easier to get it going in most cases. The following
are the steps that 'run_stem' does when bringing up Stem.

=head2 * Load Stem Environment

Many Stem modules and cells look at the Stem environment for default
configuration values or global flags. This allows you to control how
many of the cells and modules behave when loaded and instantiated.  If
a Stem attribute in a specification has its 'env' name description
set, it will use that name (optionally prefixed with the cell's
registration name) as a key to lookup in the Stem Environement. If
found there, that value becomes is used and overrides the default and
any value set in a configuration file. This allows the user to
override default setting from the outside without modifying Stem
configuration files. See Stem::Class for more on this.  The Stem
environment is set from these sources in the following order:

=over 4

=item Global Site Environment File

'run_stem' initially looks for a file named 'env' in the first
configuration directory (set at install time) and loads it if
found. These site and user files both have a simple key=value format
with one entry per line.

=item User Environment File

'run_stem' then will look in your home directory (not supported on
windows) for a file named .stem_env and loads it if found.

=item Shell Environment

Any shell environment variable with the form 'STEM_*' will
have the 'STEM_' part deleted and the rest of its name
converted to lower case. That will become the key in the Stem
environment with the value set to the shell variable's value.

=item Command Line

Any command line arguments of the form key=value will be
parsed out and used to set a Stem environment variable.

=back

=head2 * Load Stem Core Modules

	'run_stem' then loads all the core Stem modules with a use
	Stem line.

=head2 * Load Configuration Files

Any arguments left in @ARGV are assumed to be Stem configuration
files. Typically there is only one configuration file but you can have
pass in as many as you want.  The config file arguments can have a
.stem suffix or no suffix. The configuration directory list is
searched in order for the file and it is loaded and all of its entries
are constructed.

You can override the default configuration directory list (set at
install time) by setting the 'conf_path' Stem environment variable
from the shell environment or on the 'run_stem' command line. The
following are equivilent:

	export STEM_CONF_PATH=/etc/stem/conf:/home/foo/.stem
	run_stem bar

	run_stem conf_path=/etc/stem/conf:/home/foo/.stem bar

=head2 * Start Event Loop

The final operation 'run_stem' does is start the main event
loop. If no events were created by the loaded configuration
files, this will fail and 'run_stem will exit immediately. If
all the created events eventually get canceled, the event loop
will exit and 'run_stem' will exit too.

=cut
Commit	Line	Data
3104a1f1	1	#!/usr/bin/perl -w
	2
	3	eval 'exec /usr/bin/perl -w -S $0 ${1+"$@"}'
	4	if 0; # not running under some shell
4536f655	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
3104a1f1	33
3104a1f1	34	eval { use lib 'blib/lib' } if -d 'blib/lib';
6b34fa66	35	eval { use lib '../blib/lib' } if -d '../blib/lib';
3104a1f1	36
4536f655	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