/* $XConsortium: README /main/7 1996/07/15 14:14:53 drk $ */
2.  OSF/Motif Resource Manager Tests

This README describes the OSF/Motif Resource Manager tests.
It provides information about the individual tests, and
offers instructions for running and interpreting the tests
and test output.

                            Note

Throughout this README, we use the path ./tests/Mrm to
identify the top directory of the Resource Manager tests.
The ./ indicates the testing tree root and is not an actual
path designation.  For example, if you installed the Motif
software at /source/Motif, then ./tests/Mrm translates to 
/source/Motif/tests/Mrm at your site.

2.1  Overview and Directory Structure

The OSF/Motif Resource Manager test directory, ./tests/Mrm,
consists of several files and subdirectories:

   * The file Imakefile is used to build the tests.

   * The file run_all is used to run all the Resource
     Manager tests in series.  It simply runs the scripts
     run_int and run_nonint.

   * The file run_int is used to run all the interactive
     Resource Manager tests in series.  It also sets up a
     log of its action in the file intsum.out

   * The file run_nonint is used to run all the noninterac-
     tive Resource Manager tests in series.  It also sets up
     a log of its action in the file nonint.out

   * The file MrmTest.h contains declarations used by all
     the tests.

   * The file convenience.c contains the source code for
     convenience routines used by all the tests.

   * The files main.c and main.uil contain the source code
     for the MessageBox used in interactive tests.

   * The file pixmaps.uil contains color and icon declara-
     tions used in the tests.

   * The file summary.c contains the source code for the
     routine that generates summary results in the Message-
     Box for the interactive tests.

   * Test source files consisting of the suffixes .c, .h,
     and .uil.

   * The files beginning with ABrowse are the source files
     for the ABrowse Athena widget used by the RegisterCA
     test.  Note: the RegisterCA test does not run in this
     release.  For this reason, this test is not built, and
     the files comprising this test are not in the Imakefile
     or Makefile.

   * The files beginning with Browse are the source files
     for the Browse Motif widget used by the RegisterC test.

   * The subdirectory ./tests/Mrm/OpenHLang is used by OpenH
     to test UIDPATH support in the Resource Manager.

   * The file OpenH_if is used by OpenH to test the effects
     of opening a bad .uid file.  This is just a plain text
     file, it needs no compiling.

This directory contains the following tests.

CloseH      Tests the MrmCloseHierarchy function.

FetchCL     Tests the MrmFetchColorLiteral function.

FetchIL     Tests the MrmFetchIconLiteral function.

FetchL      Tests the MrmFetchLiteral function.

FetchSV     Tests the MrmFetchSetValues function.

FetchW      Tests the MrmFetchWidget function.

FetchWO     Tests the MrmFetchWidgetOverride function.

HierN       Tests the hierarchy-based name registration
            functions.

OpenH       Tests the MrmOpenHierarchy function.

RegisterC   Tests the MrmRegisterClass function with a
            user-defined Motif widget.

RegisterCA  Tests the MrmRegisterClass function with a
            user-defined Athena widget.  Note: the Regis-
            terCA test does not run at this release.

RegisterN   Tests the MrmRegisterNames function.

compiling FetchWloop.uil
            Tests the uil compiler's ability to detect cycl-
            ical widget references.


2.2  Compiling the Tests

All the tests must be compiled before you can run them.

   * If you used the global build process after installing
     the software, the tests should already be built.  We do
     not recommend building the tests with global build pro-
     cess because of the size of the test suite.  (This
     assumes that you did not move the test suite files
     prior to invoking the make commands.)

   * If you did not include the test suite files in your
     initial global build process, you can build the tests
     using the make all command from the ./tests/Mrm directory.
     Prior to building the tests you need to make Makefile in 
     the current directory. 

Neither RegisterCA nor FetchWloop.uil will be compiled
using either of the global compiling methods previously
described.  RegisterCA is not compiled because it requires
Athena toolkit libraries, and would cause the build process
to fail on systems that do not have the libraries installed.
FetchWloop.uil is not compiled because it tests a condition
that should fail the compile process and will cause the
build process to quit.

The compiled tests use a large amount of disk space.  You
may prefer to build each test separately if disk space is
limited at your site. You can build each test individually
using the make command for each test shown in the following
sections.

2.2.1  CloseH

make CloseH CloseH.uid OpenH_mf1.uid OpenH_mf2.uid(
OpenH_mf3.uid OpenH_vh.uid

2.2.2  FetchCL

make FetchCL FetchCL.uid

2.2.3  FetchIL

make FetchIL FetchIL.uid

2.2.4  FetchL

make FetchL FetchL.uid

2.2.5  FetchSV

make FetchSV FetchSV.uid

2.2.6  FetchW

make FetchW FetchW.uid

2.2.7  FetchWO

make FetchWO FetchWO.uid

2.2.8  HierN

make HierN RegisterN.uid

2.2.9  OpenH

make OpenH OpenH.uid OpenH_mf1.uid OpenH_mf2.uid OpenH_mf3.uid\
OpenH_vh.uid OpenH_vhws.uid OpenHLang/OpenH_vhev.uid\
OpenHLang/OpenH_vhevl.uid

2.2.10  RegisterC

make RegisterC RegisterC.uid

2.2.11  RegisterCA

Note: The RegisterCA test will not compile or run in this release.

2.2.12  RegisterN

make RegisterN

2.3  Running the Resource Manager Tests

The tests in this section fall into three types.

Interactive       These include a MessageBox with instruc-
                  tions for running and interpreting the
                  test.  When the test is completed, a sum-
                  mary message for the test is displayed in
                  the MessageBox.  The interactive tests are
                  CloseH, FetchCL, FetchIL, FetchSV, FetchW,
                  FetchWO, OpenH, and RegisterC.

Noninteractive    These run without input from the user and
                  print their results out to the file
                  noninit.out.  The noninteractive tests are
                  FetchL, RegisterN, and HierN.

Compile           There is only one compile test,
                  FetchWloop.uil.  It tests that the com-
                  piler produces the proper error given
                  cyclical references.

You can run all the test in series with the run_all script.
The run_all script first executes the run_int script, and
then executes the run_nonint script.

You can run the interactive tests with the run_int script.
The run_int script keeps a log of all the summary informa-
tion displayed in the MessageBox for each test in the file
intsum.out.

You can run the noninteractive tests with the run_nonint
script.  The run_nonint script keeps a log of all the test
information usually sent to the standard output in the file
nonint.out.  The run_nonint also runs the compile test for
FetchWloop.uil.

To run any of the tests except FetchWloop.uil individually
simply enter the name of the compiled test in the
./tests/Mrm directory.  The interactive tests will display a
MessageBox with instructions for the test.  When the test
has completed, a summary of the results is displayed in the
MessageBox and on the standard output.  The noninteractive
test will run with no further input.  When the test has com-
pleted, a summary of the results is displayed on the stan-
dard output.

To run the FetchWloop.uil test, simply enter make
FetchWloop.uid in the ./tests/Mrm directory.  If the test
is successful the compile will fail because of cyclic
errors.  If the compile is successful, the test has failed
to find cyclic references in the uil file.

The interactive tests OpenH and CloseH do a number of itera-
tions of opening and closing a file to test for memory
usage.  These tests will create the log files OH_log and
CH_log respectively.  These log files show on which itera-
tion of the test memory was lost during the test.  The sum-
mary of the test in the MessageBox will indicate that memory
was lost.  You can look in the log files for detailed infor-
mation about when the memory was lost and how much was lost.

BUGS SHOWN BY THESE TESTS
 
OpenH
PIRS No.:      3890
MrmOpenHierarchy fails if UIDPATH is set at all.  Other Mrm
functions seem to work ok with UIDPATH.
Version found in:      1.1.4

ENDBUGS
