`Venus 1.0 README file, April 3, 1998.`

1. Installation Script

The Venus installation script is located at $(VENUS)/INSTALL. The installation script compiles the Venus runtime library and the Venus test suite programs. To run the script, type:

> cd $(VENUS)
> INSTALL

where $(VENUS) is set as discussed in Section 2. For complete instructions on compiling a Venus program, please refer to Section 2.

`2. Compilation Instructions`

Compiling and linking with Venus/CLIPS++ is a multi-step process.

0. Environment setup

Step zero is identifying the Venus directory to use. This depends

upon the architecture and compiler you are using. Set the environment

variable VENUS to this directory. I recommend using a makefile

like the ones in the various programs directories. After this is done,

you must compile the Venus runtime library. To do this, change to the

$(VENUS)/lib directory and type make. For ex.

> cd $(VENUS)/lib; make

1. Venus compile

Step one is translating from Venus source code to C++ using the

Venus compiler. Simply calling the compiler with the source file

is sufficient. No compiler flags are normally required.

> $(VENUS)/bin/venus foo.v

The Venus compiler supports the -fs <size> flag, which specifies
the maximum size of a generated file. For example, the command
> $(VENUS)/bin/venus -fs 100 foo.v
generates files with a maximum size of 100k.

2. C++ compile

Compile your own C/C++ code and the Venus generated C++ code

using the selected compiler. Add $(VENUS)/include to the include

search path.

> CC -c -I$(VENUS)/include foo.C

3. Link

Link the object files with your own libraries and the Venus library.

Add $(VENUS)/lib/libvenus.a to the link. If you are using a Cfront

based C++ compiler (e.g. softbench or sparcworks), add the same

include path as above (this is for the template instantiation system).

> CC -o foo -I$(VENUS)/include foo.o $(VENUS)/lib/libvenus.a

An adjunct to program linking is debugger information file linking.
The Venus compiler generates partial rdb debugging information.
This information must be completed by calling the program rlink.
Rlink is called with the program name as the first option and all
of the module names as the remaining options.

For example, the following would be the rlink call for the above
example.

> rlink -o foo foo

4. Debug

To debug your program, use a combination of a source debugger (dbx,gdb)

and the rule debugger $(VENUS)/bin/rdb. If you think your problem

is in rule related code, use rdb. If you think your problem is in

your own code, use your native debugger (gdb,xdb,dbx...).

NOTE: Much of the above can be automated in a Makefile. Examine
any of the Makefiles in the programs directories for examples.

`3. DIRECTORY STRUCTURE`

The Venus directory structure is organized as follows:

Venus-1.0

bin Venus executables.

doc Help files.

include Included header files needed for compiling.

lib Venus runtime library.

programs Repository of Venus program examples.

bin
venus            Venus compiler executable.
rlink            Executable to create global debugging file.
rdb              Venus rule debugger.

lib
Makefile Makefile to create the Venus runtime library.
libvenus.a Archived Venus library.

programs
venus            Directory of program repository containing.
                 sample programs.
doc
README           The current file you are viewing.
FAQ              Text file of frequently asked questions.
ami.ps           Abstract Machine Interface definition
cikm96.ps        Lane Warshaw, Dan Miranker, "A Case Study of Venus and a
                 Declarative Basis for Rule Modules." Conference on
                 Information and Knowledge Management, Nov. 12 -16, 1996.
cursor.ps        Venus cursor interface.
debug.ps         Rule debugger reference manual.
event.ps         Event Driven Processing in Venus
quick-guide.ps   Venus startup guide for immediate use.
refman.ps        Venus reference manual.

`4. Rule-Based Query Optimizer`

The rule-based query optimizer is located at:

Venus-1.0/programs/venus/rule-opt

For installation directions, please refer to the README located in the rule-opt directory.

5. NOTES

1). Venus 1.0 has an API that enables Venus programs to inference
over data of user defined and non-local containers, the Abstract
Machine Interface (AMI). Two programs in the test suite
are designed to run using the Rogue-Wave container interface which require
the Rogue Wave Tools.h++ library. These programs are:

sawmill2

cycle2

In addition, some of the sample programs that do not use the Rogue Wave container
still utilize the Rogue Wave Tools.h++ library. These programs are:

REALESYS-A

REALESYS

att

oms

tsp-global

tsp-modular

In order to compile programs using the Rogue-Wave container, one must compile the
Venus run-time library including the rwcontb.cpp file. A compilation of any of
the programs metnioned above will require including the Rogue-Wave header files
on the C++ compile line and linking the Rogue-Wave library on the link line.

2). Venus 1.0 only allows for binary expressions in Venus source files.
For ex.

x = 1 + 2 + 3; // syntax error

x = 1 + (2 + 3); // accepted by Venus compiler

3). The "att" program within the program directory cannot be compiled
using the Gnu 2.7.2 or less C++ compiler. This is because there is a bug
in the implementation of templates within the Gnu C++ compiler that will
not allow the program to link.

4). The Venus rule-optimizer uses the Standard Template Library and has only been
tested under the Gnu 2.7.2 and the MSVC 5.0 C++ compilers. Please refer to the
README file located in the programs/venus/rule-opt directory for directions in compiling
the rule-optimizer.

5). The Venus module call graph is limited to a DAG (Directed Acyclic
Graph).

6). The Venus rule-debugger currently works slightly differently on the Window95/NT
operating systems. For more information, please refer to the Venus reference manual,
chapter on debugging.

`6. Contact Info`

Send bug reports to:

venus-bug@arlut.utexas.edu

In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug. Please follow the GNU C++
standards for reporting bugs.

To contact us or ask questions please send mail to:

venus-quest@arlut.utexas.edu