This file contains a brief description of what you will need to do if
you intend to use the installed OSE C++ libraries without makeit.


Preprocessor Symbols:

Once you have installed OSE, if you use the libraries from your own make
environment and not makeit, you will need to define special preprocessor
symbols which identify the C++ compiler being used. You will also need to
define special preprocessor symbols if you are using either ObjectStore or
Versant.

To identify the C++ compiler, at least two symbols need to be defined. The
first of these identifies the compiler vendor and the second the version of
the compiler (excluding minor revision number). For example, for Sun C++
3.0.1 the following two symbols are defined:

  CXX_SUN
  CXX_SUN3_0

If a revision of a compiler is felt to be different in functionality or
features supported to other revisions of the compiler, a third symbol is
define incorporating the revision number. For example, for Sun C++ 3.0.1
the following is also defined:

  CXX_SUN3_0_1

To find exactly which symbols you need to define, note which symbols are
defined when OSE is being installed for the C++ compiler you will be using.
At present this is only really required for Sun C++ 3.0.1 as some header
files contain a workaround for a bug in that compiler. It is also only
really required to define the symbol CXX_SUN in this case. Tags for each
version are not required.

In addition to the above, if you are using ObjectStore through the library
interface, not DML, you must define the symbol:

  ENV_OSTORE

If using Versant, you must define the symbol:

  ENV_VERSANT

If thread support is compiled into the libraries, you will need to define
the appropriate define indicating this, when you compile your own code.
For Solaris threads the symbol is:

  HAVE_SOLARIS_THREADS

For Posix threads the symbol is:

  HAVE_POSIX_THREADS

For VxWorks the symbol is:

  HAVE_VXWORKS_THREADS

For Win32 the symbol is:

  HAVE_WIN32_THREADS

You will also need to ensure you link in the appropriate thread libraries.

When using VxWorks, you should also define the symbol:

  ENV_NOCOMMONPOOL

This will disable the use of the common memory pools.

Other symbols may need to be defined, check what makeit defines when OSE
is being installed. The only symbol you shouldn't define is OSE_BUILD.


Include Path:

When the header files are installed they are installed in two locations. In
the first location, header files common to all hosts are placed. In the
second location, header files specific to an installation on a host are
installed. If you are using OSE version 4.0 and OSE is installed under the
root directory `/usr/local/ose', and the host identifier is `SPARC_SUN4',
you will need to define the include search path using:

  -I/usr/local/ose/4.0/include -I/usr/local/ose/4.0/SPARC_SUN4/include


Library Linking:

When libraries are installed, they are installed in directories named using
the tag identifying the compiler you are using. For example, if you are using
Sun C++ 3.0.1, the libraries will be installed in the directory:

  lib/SUN3.0.1

underneath where OSE is installed. If you are using OSE version 4.0
and OSE is installed under the root directory `/usr/local/ose', and
the host identifier is `SPARC_SUN4', the linker flags you will need to use
are:

  -L/usr/local/ose/4.0/SPARC_SUN4/lib/SUN3.0.1 \
   -lOUX_4X0_SUN3X0X1_dbg -lOTC_4X0_SUN3X0X1_dbg -lOSE

This will cause versions of the libraries which included debugging
information to be linked in with your application. If you wanted to link
with the optimised versions of the libraries you would use:

  -L/usr/local/ose/4.0/SPARC_SUN4/lib/SUN3.0.1 \
   -lOUX_4X0_SUN3X0X1_opt_40000 -lOTC_4X0_SUN3X0X1_opt -lOSE

A similar thing is done to link with either the "std" or "prf" variants
of the library.

Note that if you are using a cfront 3.0.X based compiler, check whether
it searches in libraries linked using the -l option for expanded templates.
If the compiler does not search the libraries correctly, the libraries
will need to be linked explicitly using an absolute pathname. For example:

  -L/usr/local/ose/4.0/SPARC_SUN4/lib/SUN3.0.1 \
   /usr/local/ose/4.0/SPARC_SUN4/lib/SUN3.0.1/libOUX_4X0_SUN3X0X1_dbg.a \
   /usr/local/ose/4.0/SPARC_SUN4/lib/SUN3.0.1/libOTC_4X0_SUN3X0X1_dbg.a \
   -lOSE

Refer to the PROBLEMS file for more information about this.


Template Map Files:

For cfront 3.0 based compilers, template map files are provided. These are
called PTMAP and can be found in the directories include/OTC and
include/OUX in the common include files area. The files, if required,
should be copied in to the repository directory and called nmap0 and nmap1.


Directed Instantiation:

OSE is setup such that if you include into your application, header files
for all classes making use of templates, you can define the preprocessor
symbol EXPAND_TEMPLATES. This will allow the compiler to instantiate
templates directly into your application object file. In the case of
cfront based compilers, this avoids the use of the repository for expanding
templates. Note that for cfront based compilers, the program code files
must be compiled separately to other code files, and the link performed
at the same time as the compilation in order for this to work. For example:

  CC -DEXPAND_TEMPLATES -D... program.cc *.o -L... -l... -o program

will work, but:

  CC -DEXPAND_TEMPLATES -D... -c program.cc
  CC program.o *.o -L... -l... -o program

will not.


All these gory details, and many others, are all handled automatically
by makeit. It is highly recommended that you use makeit as it will make
using OSE, and also compilation of your own code, much easier. At least
run makeit on some simple programs to see what compiler specific options
it may be defining, in case you need to define the same options.
