src/test/README STEP Class Library Example Suite Last Update: 2/27/98 These programs are intended as a set of examples for programming with the STEP Class Library (SCL) -- e.g. instantiating entities, manipulating data, using the dictionary classes, etc. This file describes what these programs are and how to get them running (if configure fails to build them). The configure installation script should have correctly built: - the SCL code for the data/example/example.exp EXPRESS schema. It should have installed it using the /bin/mkProbe script with the -i option. This is the schema and corresponding SCL Schema Class Library that is used by these SCL applications. - the executables for these SCL applications under the corresponding directories in /testbuild/. If configure did not have success you will need to build the example schema with the mkProbe script using the -i option. This process is detailed in the top-level README.scl that comes with this releaes. You will also need to build these SCL applications under /testbuild/. This process is detailed below under 'Building and running the test programs if configure fails to build them'. Other Software ~~~~~~~~~~~~~~ You will need some other software to use this package to its fullest. First, you will need the STEP Class Library release (which includes this directory.) Secondly, to make full use of the scl2html program, you will need an HTML browser such as Netscape. Oh, and most importantly of all, you need a C++ compiler that can build C++ 2.0 source. The Programs ~~~~~~~~~~~~ p21read The simplest example program. It reads a Part 21 file and writes it out. Errors found in the file are reported to standard error (using the underlying fedex parser). This program's primary usefulness is to illustrate the components necessary to build an application which uses the SCL. tstatic A simple instantiation test. This creates some static instances of entities from the 'example' schema, puts some data in them, and prints them out. This also uses a simple iterator class to pass over an array of pointers to STEPentities. The entities are printed in STEP Exchange file format. treg This test uses the dictionary classes of the SCL, the Registry, to instantiate an object of each entity type, and give them some data by analyzing the attribute types via the registry (and not knowing what objects we have). Also, all instances are kept track of with an instance manager, which, among other things, allows us to keep an organized STEP file of the data without explicitly maintaining it. The resulting objects are output in STEP Exchange File format both to the screen and to an optional file. NOTE: The output file that treg produces will not necessarily be a valid STEP Exchange file. While treg happily produces values for most entity attributes, it will leave attributes of type SELECT, AGGREGATE, or ENTITY blank. Since in many cases, these attributes will not be optional, a subsequent STEPread of the file will flag errors with the data. The illustrative character of treg, however, is satisfied as is. tio Some simple tricks with STEPfiles and the instance manager. A given STEP Exchange file is read in, its objects are instantiated, and the resulting instances are printed out. The same file is read again, and a duplicate set of objects is appended to the ones already read. Finally, the resulting list of instances is written to the screen and an optional output file in STEP Exchange file format. As noted above, tio may choke on some STEP files produced by treg... this is not tio's fault, but treg's. A sample STEP exchange files (testfile.step) is included. scl2html This program, when linked to a 'compiled' schema, will use the Registry information to create a suite of HTML documents describing the structure of the schema. A 'page' is created for each entity, describing its attributes, inheritance ancestry, and subtypes, complete with hypertext links tying the pages together. While perhaps not the most useful application as it is (the exp2html utility produces more complete output, and doesn't require compiling the schema and the program linked to it), it is plausible that forms and such could be added to create a Web-accessible Data Probe. As it stands, it demonstrates several methods for accessing the registry information in a schema-independant manner. scl2html requires a Web browser or live-hypertext HTML editor to be of any use beyond reading the HTML result files. treg, tio, and scl2html are schema-independant; while they link to 'example''s class library by default, they can be rebuilt to access the class library of any schema. See below for details. tstatic requires 'example''s class library to run. Building and running the test programs if configure fails to build them ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before building the tests, you will need to have built the header files and class library for the 'example' schema included with this release (data/example/example.exp) (this will only be necessary if configure failed to build it correctly). It should be built with the mkProbe script using the -i option. See the top-level README.scl for complete instructions. Next, you'll need to look at the file /testbuild/schema-loc, which is included by all the test program Makefiles. This file defines the locations of the example schema library and the appropriate make_rules file. If the library for the example schema was built using the mkProbe script with the -i option then the macros in schema-loc defining the schema location should be correct. If not, you will need to change the schema related macros; if you do this, keep things defined in terms of $(SCHEMA_NAME), otherwise, you will create problems for the other Makefiles. To build all the programs, just type 'make' in the /testbuild/ directory. To build individual tests, just type 'make' in their directory under /testbuild/. The script /testbuild/runtests executes all the test programs, except for scl2html. For best results, execute as follows (this is in csh): % runtests >&! tests.out To run scl2html, it is recommended that you create an empty directory and run it from there, as it creates several .html files as its output: % cd scl2html % mkdir tmp % cd tmp % ../scl2html This can save you a lot of cleanup work if you change scl2html to use a more complex schema than 'example'. Using Alternate Schemas ~~~~~~~~~~~~~~~~~~~~~~~ All the programs except for tstatic can be built to use any schema class library; tstatic _must_ use 'example'. Building any of the programs to use an alternate schema is very easy to do. First, as with 'example', build your Schema Class Library. If you are again using mkProbe with the -i option, /testbuild/schema-loc need not be altered. (Or you may edit the SCHEMA_NAME macro in schema-loc to specify the name of the schema you just built as reflected in the directory and library name for the schema.) Then, in the directory of the program you want to build, type: % make SCHEMA_NAME= or if you already edited the SCHEMA_NAME macro % make where is the name of the schema, e.g., 'example.' Any of the other schema-loc variables can be set this way (at least using GNU make), so if you want to keep your schema class libraries somewhere else you can specify the locations along with the SCHEMA_NAME on the command line (this is all one line): % make SCHEMA_NAME=my_schema SCHEMA_DIR=~rms/schemas/my_schema SCHEMA_LIB_DIR=~rms/probes/my_schema Other Source Files in this Directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ needFunc.{h|cc} The needFunc source code is needed to create SCL applications that do not link with the Data Probe libraries. It is installed in the /lib/ directory during installation of the SCL software. Known Problems ~~~~~~~~~~~~~~ If you are using Gnu g++ version 2.5.8 with this program you might encounter a problem. If you run make depend on the various makefiles of the separate applications makedepend may insert a dependency for the nonexistent file _IO_config.h ( this particular dependency was generated by makedepend when it encountered the libio.h file of the g++ package. ) This may be caused by makedepend being unable to follow C++ preprocessor conditionals in header files. Another version of makedepend (unfortunately the exact version number is unknown though maybe it's newer) seems to have fixed the problem at NIST. It is up to the individual user to find the makedepend version that will work well with this package if makedepend is used at all (it's not necessary). More information ~~~~~~~~~~~~~~~~ See the top level README file of this release for more information on the software. Acknowledgments ~~~~~~~~~~~~~~~ These examples were developed by Ian Soboroff, a student formerly employed at NIST.