Repo restructuring

1 files changed, 172 insertions, 0 deletions

diff --git a/ACE/docs/run_test.txt b/ACE/docs/run_test.txt
new file mode 100644
index 00000000000..9889a9222e3
--- /dev/null
+++ b/ACE/docs/run_test.txt
@@ -0,0 +1,172 @@
+/**
+@page run_test_howto How to write a run_test.pl
+
+ACE/TAO's auto_builds expect run_test.pl's to follow some guidelines
+that are needed to keep the auto_builds from hanging and to make
+sure the run_test.pl works on all platforms
+
+- The run_test must not hang or block.
+- The run_test must clean up any temporary files when it is done.  
+- The run_test must not require any user input
+- The run_test should return a non-zero value if the test failed
+
+Following is an example
+
+@subsection example Example
+
+@verbatim
+eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}'
+    & eval 'exec perl -S $0 $argv:q'
+    if 0;
+
+# $Id$
+# -*- perl -*-
+
+use lib '../../../bin';
+use PerlACE::Run_Test;
+
+$status = 0;
+
+$server_ior = PerlACE::LocalFile ("server.ior");
+unlink $server_ior;
+
+$SV = new PerlACE::Process ("server", "-o $server_ior");
+$CL = new PerlACE::Process ("client", "-k file://$server_ior");
+
+$SV->Spawn ();
+
+if (PerlACE::waitforfile_timed ($server_ior, 5) == -1) {
+    print STDERR "ERROR: cannot find file <$server_ior>\n";
+    $SV->Kill ();
+    exit 1;
+} 
+
+$client = $CL->SpawnWaitKill (60);
+
+if ($client != 0) {
+    print STDERR "ERROR: client returned $client\n";
+    $status = 1;
+}
+
+$server = $SV->TerminateWaitKill (5);
+
+if ($server != 0) {
+    print STDERR "ERROR: server returned $server\n";
+    $status = 1;
+}
+
+unlink $server_ior;
+ 
+exit $status;
+@endverbatim
+
+@subsection details Example Details
+
+@verbatim
+eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}'
+    & eval 'exec perl -S $0 $argv:q'
+    if 0;
+
+# $Id$
+@endverbatim
+
+This is the standard header stuff.  The eval is a trick used
+to get the perl script to run if it a unix shell treats it as
+a shell script.
+
+The CVS ID string is the usual one we put in.
+
+@verbatim
+use lib '../../../bin';
+use PerlACE::Run_Test;
+@endverbatim
+
+The use lib line is used to tell Perl where the PerlACE modules are.
+It should be a relative path to the bin directory.
+
+And PerlACE::Run_Test is a module to be used by all run_test.pl's.
+It does a couple of things, including parsing some common command
+line arguments (like -Config and -ExeSubDir) and also brings in
+the PerlACE::Process module.
+
+@verbatim
+$status = 0;
+
+$server_ior = PerlACE::LocalFile ("server.ior");
+
+unlink $server_ior;
+@endverbatim
+
+Because of the way tests work on chorus, we need to have a fully 
+qualified path to all *.ior and *.conf files.  We unlink the file
+immediately because we use PerlACE::waitforfile_timed later.
+
+@verbatim
+$SV = new PerlACE::Process ("server", "-o $server_ior");
+$CL = new PerlACE::Process ("client", " -k file://$server_ior ");
+
+$SV->Spawn ();
+@endverbatim
+
+The PerlACE::Process is constructed with an executable and 
+arguments.  @note Unlike the old Process module, the process
+isn't started until one of the Spawn methods is used.
+
+@verbatim
+if (PerlACE::waitforfile_timed ($server_ior, 5) == -1) {
+    print STDERR "ERROR: cannot find file <$server_ior>\n";
+    $SV->Kill (); 
+    exit 1;
+} 
+@endverbatim
+
+The PerlACE::waitforfile_timed method waits until the file is
+created.  In this way, we know when to start the client.  If
+no IOR file is used, then you'd need to use Perl's sleep 
+method. 
+
+@verbatim
+$client = $CL->SpawnWaitKill (60);
+
+if ($client != 0) {
+    print STDERR "ERROR: client returned $client\n";
+    $status = 1;
+}
+@endverbatim
+
+Here is an example of starting the client.  SpawnWaitKill will start 
+the process and wait for the specified number of seconds for the 
+process to end.  If the time limit is reached, it will kill the 
+process and return -1.  
+
+The return value of SpawnWaitKill is the return value of the 
+process, unless it timed out.  You don't need to check for the 
+timeout, since SpawnWaitKill will print out a timeout error.  
+Instead, just check for != 0.
+
+@verbatim
+$server = $SV->TerminateWaitKill (5);
+
+if ($server != 0) {
+    print STDERR "ERROR: server returned $server\n";
+    $status = 1;
+}
+@endverbatim
+
+Here is the termination of the server.  Servers are usually terminated
+either by TerminateWaitKill or just WaitKill.  TerminateWaitKill is 
+used when the server doesn't shut down itself.  WaitKill is used when
+it does (such as when the client calls a shutdown method).  Once
+again, we check the return status.
+
+
+@verbatim
+unlink $server_ior;
+ 
+exit $status;
+@endverbatim
+
+And finally, we unlink any files that were created and then just
+exit with $status.  
+
+*/
\ No newline at end of file