README

Running the tests
-----------------

Before running the tests you should have the $MPC_ROOT environment variable
set or have the $ACE_ROOT environment variable set with MPC checked out into
$ACE_ROOT. $QTDIR and $PERL5_INCLUDE should also be set under UNIX as some of
the tests need them to build.  

Also, you can optionally add a file base.cfg to $MPC_ROOT/config with content: 
$TEST_ROOT = $TEST_MPC_CONFIG.  The run_tests.pl script will then set
$TEST_MPC_CONFIG so each test uses either the MPC.cfg in MPC_TEST/config, 
one in $TEST_ROOT/config if it exists, or the one in $MPC_ROOT/config if 
$TEST_ROOT/config contains MPC_PHONY.cfg instead of MPC.cfg.  This is optional
because of the need to add a file to MPC.  Therefore, tests should use this
feature to enhance tests, logging, etc., but lack of a base.cfg shouldn't cause 
a test to fail.

Run run_tests.pl to run all of the MPC tests.  
The run_tests.pl script will generate all of the supported MPC project types 
and attempt to build at least one of the project types in order to ensure that
things get generated correctly after the project has been built.  A warning will be
printed if it is unable to build for at least one project type.

Adding a new test
-----------------
NOTE: This must be done under UNIX due to the incorrect handling of carriage
return/line feed combination under Windows subversion.

1) Create a directory under the 'tests' directory containing the test.
   a) Any additional options that need to be passed to Perl should be placed
      in a file named perl_options.txt in the root directory of the test.
   b) Any additional options that need to be passed to MPC should be placed
      in a file named additional_options.txt in the root directory of the
      test.
   c) If environment variables need to be set, create an environment.txt
      file in the root directory of the test.  Each line should be of the
      form NAME = VALUE.  These will be set before running the test. The
      TEST_ROOT environment variable is always set to the full path of the
      test, but can be overridden by values in this file.
   d) A 'config' directory is automatically added via the -include option when
      MPC is run.
   e) The library path (for whatever platform you are testing on) is set to
      contain the full path up to the name of your test with a /lib
      appended if it is necessary for the particular project type.
   f) If a workspace (.mwc file) of the same name as your test directory
      exists in the test directory, it will be passed to MPC.
   g) If the test has non-default build file names (due to options passed to
      MPC) or the test should not be built, it should be specified by
      placing a file named build_entry.txt in the root directory of the
      test.  The file has the format of <mpc type>: [build file name].  If
      [build file name] is empty, the workspace will not be built for the
      specified mpc type.
   h) If any files in the test need modification after MPC generation there
      should be one or more files ending in .patch containing patch
      information.  The patch utility is run with the -p0 option.
   i) If the test needs to run anything, a run_test.pl should be
      placed in the root of the test directory.  This perl script should
      return zero when successful and non-zero when not.  A run_test.pl
      script is optional.
   j) To use mpc.pl instead of mwc.pl, add a file in the test top-level
      directory named MPC_ONLY.

2) With the $ACE_ROOT environment variable set, run run_tests.pl with the
   --expected option to create the expected results for all tests.

3) Add the test and expected results to Subversion by changing to the
   expected directory and running the add_expected_directories.sh script
   found in the utils directory.  You must provide the full path to the
   script.