Tools.h++
Build Guide
For use with Rogue Wave's
Software Parts Manager
Rogue Wave Software
Corvallis, Oregon, USA
1.
Introduction
Section
This document describes the compilation procedures and requirements for
Tools.h++, a Rogue Wave C++ library. The procedures described in this
book apply to versions of Tools.h++ that have been unlocked and installed
from the Software Parts Manager (SPM) CD. These procedures also
apply if SPM was in place when you installed your product from a floppy
disk or a web distribution.
In addition to compilation procedures, this guide provides information
about using the resulting Tools.h++ libraries with your own programs.
1.1 Requirements
Before attempting to compile Tools.h++ be sure that you are familiar with
any product dependencies or other product-specific requirements.
If you intend to use this version of Tools.h++ with applications that used
a previous version of Tools.h++, you must change include paths, library
paths and the link library name in all relevant makefiles or IDE projects.
Be sure to read the information in Section 3.1 for more information before
you build Tools.h++.
1.1.1 Dependencies on Other Rogue Wave Products
These instructions assume that you have already installed Rogue Wave's
Software Parts Manager. If you have not, please refer to the Software
Parts Manager CD package for installation instructions.
1.1.2 Tools.h++ and the Standard C++ Library
This version of Tools.h++ works with Rogue Wave's Standard C++ Library
v1.2.1, and with the version of the Standard C++ Library shipped with
MSVC 4.2. If you want to use features in Tools.h++, such as the Standard
C++ Library-based collections, and extended regular expressions, you must
have a working version of the Standard C++ Library available before you
compile Tools.h++. If you do not have the Standard C++ Library on your
system, you will not be able to use all the features of Tools.h++.
Tools.h++ Build Guide
Introduction 3
1.2 Overview
A complete installation and compilation of Tools.h++ includes the following
steps:
Before you begin: If you plan to use Tools.h++ with the Standard C++
Library, install and build the latter, using the same build options you plan to
use for Tools.h++.
1.
Unlock Tools.h++ from the Rogue Wave CD. Skip this step for floppy
or web distributions of the product.
2.
Install the Tools.h++ source code, examples, and documentation from
the unlocked source on the CD. (Or, run the install scripts provided
with your floppy or web distribution of the product.)
3.
Use the SPM build mechanism to compile the Tools.h++ libraries.
4.
Compile and run the Tools.h++ examples. (optional)
This guide assumes that you have completed steps 1 and 2, and have an
installed Tools.h++ part in the /parts directory on your system hard drive.
1.3 Available Documentation
Documentation that is delivered with your product includes HTML files
and readme files. Printed documentation is available for purchase.
1.3.1 Readme Files
The Tools.h++ readme files supplement this and other Tools.h++
documentation. They contain important information regarding specific
compilers and operating systems, how to use shared libraries and DLLs,
and other items of interest. We urge you to read all the files in the docs
directory, but especially toolread.doc.
The installation process places copies of the Tools.h++ readme files into one
of the following directories, as determined by the product you installed
•
For Windows: <rw_root> \parts\tls0706w\docs
•
For UNIX: <rw_root>/parts/tls0706u/docs
After you build the library, the readme files are exported to the workspace.
(See Section 2.3.1.)
You can display the toolread.doc file from within Software Parts
Manager by selecting the product in the Installed Parts folder on the
Build Info tab, and clicking the right mouse button. We recommend that
you read this file before building the library.
4 Introduction
Tools.h++ Build Guide
1.3.2 Tools.h++ Documentation
Tools.h++ user's documentation includes manuals in HTML format. To use
the documentation point your browser at the file shown in Table 1.
These documents describe features of Tools.h++ and provide specific
information about the Tools.h++ classes.
Table 1. Tools.h++ HTML Documentation
Document
Location
Note: UNIX users should read "\" as "/" in this table.
<rw_root>/htmldocs/tlsug/ug.htm
Tools.h++ User's Guide
Tools.h++ Reference
Tools.h++ Build Guide (this
document)
Tools.h++ Installation and Build
Guide (Floppy/Web
distribution only)
<rw_root>/htmldocs/tlsref/ref.htm
<rw_root>/htmldocs/tls706bd/ug.htm
<rw_root>/htmldocs/tls706in/ug.htm
Printed versions of these documents can be purchased. Contact Rogue
Wave for more information. Use our web site:
http://www.roguewave.com
or contact sales at one of the following numbers:
In the US:
Rogue Wave Software, Inc.
(800) 487-3217
In Europe:
Rogue Wave Software GmbH
Rogue Wave Software B.V.
Rogue Wave Software S.A.R.L.
Rogue Wave Software-UK.Ltd.
+49(61 03) 59 34-0
+31 20-695 55 11
+33-1-47695803
+44 118 9880224
1.4 Terminology
Buildable part: A package of software that can be installed and built using
the SPM configuration and build model. Parts may be recursive; that is, they
can contain sub-parts. For example, the Tools.h++ library is one buildable
part, and the Tools.h++ examples are another. Note that all the examples as
a whole constitute a single buildable part, since they exist in the same
directory and share the same makefile.
build profile: Files that specify various combinations of four common
library build options: static/shared, debug/not debug, singleTools.h++ Build Guide
Introduction 5
threaded/multithreaded, with Standard C++ Library/without Standard
C++ Library. A build profile is combined with an environment profile to
create a configuration file.
configuration and build model (CBM): A series of Korn shell scripts that
know how to determine a compiler's capabilities, generate makefiles from
makefile templates, invoke make, and install software.
configuration file: A file used to provide the build configuration
information to the CBM. A configuration file combines the information in a
build profile and an environment profile and may specify additional
compile and link options.
distribution repository: A data file that contains information about the
products, documentation, and configurations installed by, or available to
SPM. SPM updates this repository when you install additional products or
define additional configurations.
environment profile: Files that specify various operating system and
compiler combinations. An environment profile is combined with a build
profile to create a configuration file.
parts directory: A directory hierarchy containing the sources for a buildable
software part.
Software Parts Manager (SPM): A tool for selecting and managing Rogue
Wave parts. SPM has two parts: a set of configuration and build model scripts
and the partmgr application, which has a graphical user interface that
displays marketing literature, installs Rogue Wave software purchases, and
invokes the mechanism that builds installed software.
working repository: A data file describing the state of a SPM installation
site. A working repository specifies which products have been installed,
and which parts have been built.
workspace: A platform-specific directory hierarchy containing built, readyto-use software, such as libraries and the headers needed to use them, and
executables. It may also contain the sources necessary for building libraries
or executables. A workspace resembles the rogue tree of Rogue Wave’s old
build model.
6 Introduction
Tools.h++ Build Guide
2.
Compiling Tools.h++
Section
This section describes compilation procedures for Tools.h++. These
instructions assume that you have already unlocked and installed Tools.h++
through Software Parts Manager, or have installed a product from floppy
disk using the scripts provided. In either case, the part should appear in the
Installed Parts folder on the BuildInfo tab.
This distribution of Tools.h++ includes:
•
Source code
•
Examples
•
Documentation
Rogue Wave's Software Parts Manager distinguishes between the process
of installing software and the process of building software. Installing
software means transferring software from its compressed form on a
delivery media, be that a CD, a floppy disk, or a web distribution file, to an
organized set of files in predictable directories on your own hard drive.
This installation directory is also called a product tree. When SPM builds a
library, its configuration and build mechanism creates the library and the
object files, and exports these, along with the header files and other items
such as example source code, to a designated workspace. (We provide a
description of the workspace directory in Section 2.3.1.) Upon completion
of the installation and build processes you will have two distinct directory
structures on your hard drive.
The product tree that the installation process creates contains software,
documentation, and information that SPM uses when compiling your
product. Table 2 shows the installation directory structure, using <rw_root>
to indicate the directory in which you installed SPM. In the installation
directory name, <os> is replaced by a character indicating the operating
system family: w for Windows, u for UNIX.
Tools.h++ Build Guide
Compiling Tools.h++ 7
Table 2. Tools.h++ directory structure
Directory
Description
Note: UNIX users should read "\" as "/" in this table.
<rw_root>\parts\tls0706<os>\source\src
Tools.h++ source code
<rw_root>\parts\tls0706<os>\source\etc
Files used by the
configuration and build
model to build the
Tools.h++ source code.
<rw_root>\parts\tls0706<os>\source\src\r Tools.h++ header files.
w
<rw_root>\parts\tls0706<os>\docs
Tools.h++ readme files.
<rw_root>\parts\tls0706<os>\examples
Tools.h++ examples
\src
<rw_root>\parts\tls0706<os>\examples
\etc
Files used by the SPM
configuration and build
model to build the
Tools.h++ examples.
2.1 Product Dependencies
This version of Tools.h++ works with Rogue Wave's Standard C++ Library
v1.2.1, and with the version of the Standard C++ Library shipped with
MSVC 4.2. If you want to use features in Tools.h++, such as the Standard
C++ Library-based collections, and extended regular expressions, you must
have a working version of the Standard C++ Library available before you
compile Tools.h++. If you do not have the Standard C++ Library on your
system, you will not be able to use all the features of Tools.h++.
Note: If you build Tools.h++ with Rogue Wave's Standard C++ Library,
you should build both libraries with compatible build options. In
particular, the attributes for shared/static and single
threaded/multithreaded should match.
2.2 Compilation Procedures
Note: Before you attempt to compile a library through the Software Parts
Manager, you must make sure that all compiler-specific environment
variables and system settings are properly defined.
8 Compiling Tools.h++
Tools.h++ Build Guide
2.2.1 Compile the Source Code
The following procedure describes how to run the process that compiles
Tools.h++. Section 2.3 describes how the resulting library names are
encoded.
1.
From the Installed Parts folder on the Build Info tab, select
Tools_0706_<os> as the part you're working on. Click the Build
button. The build dialog will appear on your screen.
2.
Select the source folder as the part you wish to build.
3.
Choose the configuration you want to use to compile your library. A
configuration specifies the environment and build options that SPM will
use to compile Tools.h++. The configuration file's name indicates the
environment and build options available in that file. See the SPM
online help for more information about configurations.
•
Remember: If you are building Tools.h++ with the Standard C++
Library, you should use compatible configurations for both
libraries. In particular, the static/shared and single/multithreaded
attributes should be the same.
•
To build the library for an environment that is not shown, or to
specify build or link options that are not described by any of the
configurations on your screen, you must create a new configuration.
Review the SPM online help for information about how to add or
edit configurations.
4.
After selecting a configuration, click on OK.
5.
During the build process, SPM may display questions that provide
important information about various features of the build. The
questions include information about the values you must set or select.
Additional information about the questions and answers appears in the
toolread.doc file.
After you answer the questions, SPM will finish building the library and
will export the built libraries, the examples and the header files to a
workspace directory. Sections 2.3 describes the resulting library names and
the workspace.
2.2.2 Compile the Examples
Compile and run the Tools.h++ examples.
1.
From the Installed Parts folder on the Build Info tab, select
Tools_0706_<os> as the part you're working on. Click the Build
button. The build dialog will appear on your screen.
2.
Select the examples folder as the part you wish to build.
Tools.h++ Build Guide
Compiling Tools.h++ 9
3.
Select a configuration to build the examples. You should select a
configuration for the examples that corresponds to the configuration of
an existing Tools.h++ library.
4.
After selecting a configuration, click on OK.
5.
During the build process, SPM may display questions that provide
important information about various features of the build. The
questions include information about the values you must set or select.
Additional information about the questions and answers appears in the
toolread.doc file.
SPM will build the examples you selected. A makefile for the compiled
examples is stored in the workspace directory structure. See Table 4 in 2.3
for a description of the workspace.
2.3 Resulting Library Names and Workspace
Libraries are named according to the following encoding scheme:
(lib)tls(#)[t][b].[ext]
Table 3 describes the encoding scheme used to name Tools.h++ libraries.
For example, if you use a SunPro compiler to build a single-threaded, static
library, that provides symbolic debugging and assertions, the resulting
library name is:
libtls3s.a
The same library built using any compiler on Windows NT or Windows 95
is named:
tls3s.lib
Table 3. Library name decoder
Code
(lib)
tls
(#)
10 Compiling Tools.h++
Meaning
Indicates that this is a library.
Indicates that this is a Tools.h++ part.
Used for a Windows DLL only. Indicates the version number.
Tools.h++ Build Guide
Code
[t]
[b]
[ext]
Meaning
Indicates the basic build type. Possible build type numbers and
the build that they specify appear below:
0 = no stdlib, single thread, no debugging features
3 = no stdlib, single thread, symbolic debugging and assertions
4 = no stdlib, multithread, no debugging features
7 = no stdlib, multithread, symbolic debugging and assertions
8 = stdlib, single thread, no debugging features
11 = stdlib, single thread, symbolic debugging and assertions
12 = stdlib, multithread, no debugging features
15 = stdlib, multithread, symbolic debugging and assertions
Indicates the library binding.
s = static
d = dynamic (DLL) /shared
Indicates the extension. For Windows static libraries, the
extension will be:
lib
For Windows DLLs, the extension will be:
dll
The extension naming convention will vary from one UNIX
platform to another. Here are some possible values:
.a = static library, or, for AIX, also a shared library
.so, .sl, etc. = shared library, depending upon the compiler
Note: The library binding character mentioned above indicates
whether a library is static or shared.
2.3.1 The Workspace Directory Structure
The workspace directory structure resembles the rogue tree of Rogue
Wave’s old build model. Table 4 describes the workspace organization for
Tools.h++.
SPM uses the following convention to name the workspace:
<rw_root>\workspaces\<OPSYS>\<COMPILER>\…
For example, if the root directory is c:\rwav, the workspace for MSVC on
Windows NT is named:
c:\rwav\workspaces\WINNT\MSVC\
In Table 4, <os> is used as a placeholder for the operating system family
mnemonic: w for Windows, u for UNIX.
Tools.h++ Build Guide
Compiling Tools.h++ 11
Table 4. Organization of the workspace
Directory
Description
Note: UNIX users should read "\" as "/" in this table.
<workspace>\docs
Tools.h++ readme file.
<workspace>\lib
Tools.h++ library.
Header files for the library.
<workspace>\rw
<workspace>\rw\stdex
<workspace>\examples
<workspace>\examples\tls0706<os>
<workspace>\examples\tls0706<os>\
<bt>
Tools.h++ extensions to the
Standard C++ Library.
Subdirectories for Rogue
Wave product examples
Tools.h++ examples, and
subdirectories for build
type specific makefiles
Make file for examples that
use build type <bt> where b
is the binding (s=static,
d=dynamic/shared) and t
is the build type number.
(See the library name
encoding in Table 3.)
2.4 Source File Location
The Tools.h++ source files do not get copied to the Rogue Wave workspace
at the end of the build. Instead they are located in a directory equivalent to
the following:
<rw_root>\parts\tls0706<os>\source\src
Replace <os> with the abbreviation for your operating system: w for
Windows, u for UNIX.
You must provide the location of the library source files to your debugger.
when you debug your programs.
2.5 Makefile Location
Each time you build a new version of a Tools.h++ library, SPM creates a
makefile and puts a copy of that makefile into a location in the product tree:
<rw_root>\parts\tls####<os>\source\obj\<OPSYS>\<COMPILER>\<bt>
where:
•
12 Compiling Tools.h++
<rw_root> is the SPM root directory;
Tools.h++ Build Guide
•
tls####<os> stands for the name and version of the library: tls is the
library mnemonic, #### is the version, and<os> is the operating system:
w for Windows, u for UNIX;
•
<OPSYS> and <COMPILER> are mnemonics for the operating system
and compiler you built on;
•
<bt> is the build type with b as the binding (s=static,
d=dynamic/shared) and t as the build type number. (See the library
name encoding in Table 3.)
For example, if you use MSVC on Windows NT to build a single threaded,
static version of the Tools.h++ library, that does not use the Standard C++
Library, and that does provide symbolic debugging and assertions, the
resulting makefile is located in the following directory:
<rw_root>\parts\tls0706w\source\obj\WINNT\MSVC\s3
Tools.h++ Build Guide
Compiling Tools.h++ 13
3.
Compiling with Tools.h++
Section
This section contains information about compiling and linking your
programs with Tools.h++ libraries.
If you have compiled the Tools.h++ examples, it may be helpful to review
the makefiles in the directory:
<rw_root>\workspaces\<OPSYS>\<COMPILER>\examples\tls0706<os>\<bt>
where, <rw_root> is the root directory, <OPSYS> and <COMPILER> are the
operating system and compiler used to compile the examples, <os>is w for
Windows and u for UNIX, and <bt> is the build type with b as the
binding (s=static, d=dynamic/shared) and t as the build type number.
(See the library name encoding in Table 3.)
3.1 IDE and Makefile Changes Required by the New
Build Model
This information applies to all compilers and operating systems.
The SPM configuration and build mechanism generates different library
names and a different directory structure than previous Tools.h++ build
methods. This means that if you plan to use this version of Tools.h++ with
applications that formerly used an older version of the library, you must
change include path, library path, and link library information in your IDE
project files or in your makefiles.
3.1.1 Include Path
The include path for Tools.h++ header files is:
<rw_root>\workspaces\<OPSYS>\<COMPILER>
Where:
•
<rw_root> is the root directory that contains the workspaces, parts, and
htmldocs directories.
Tools.h++ Build Guide
Compiling with Tools.h++ 15
•
workspaces is the name of the directory that contains all Rogue Wave
compiled libraries (in \lib), header files (in \rw), and examples (in
\examples). Notice that workspaces is plural.
•
<OPSYS> is a mnemonic for the operating system used for a particular
build.
•
<COMPILER> is the mnemonic for the compiler used for a particular
build.
UNIX users: note that in the INCLUDE path, the operating system and
compiler mnemonics must be UPPERCASE.
Appendix A lists the mnemonics for all the compilers and operating
systems that Rogue Wave supports. Here are a few sample include paths,
using c:\rwav as the <rw_root> directory.
•
MSVC on NT:
c:\rwav\workspaces\WINNT\MSVC
•
Borland on Windows 95:
c:\rwav\workspaces\WIN95\BORLAND
•
Cygnus G++ compiler on SGI Irix:
rwav/workspaces/IRIX/CYGNUS
You must change the include path for header files in all your project files if
you're using an IDE and in any relevant scripts or files that contain path
information. In addition, be sure to use the proper path if you run your
compiler from the command line.
Note that all Rogue Wave header files are specified with a leading rw/. For
example, the RWCString header file is included in source as:
#include <rw/cstring.h>
This convention avoids potential naming conflicts with similarly named
header files from other libraries. By qualifying with rw/, we indicate that
the header file is part of a Rogue Wave library. This means that the include
path that you specify for your compiler will look something like this:
cl -I<rw_root>\workspaces\<OPSYS>\<COMPILER> test.cpp…
and not like this
cl -I<rw_root>\workspaces\<OPSYS>\<COMPILER>\rw test.cpp…
WRONG!
16 Compiling with Tools.h++
#
Tools.h++ Build Guide
3.1.2 Library Path
The library path for Tools.h++ is:
<rw_root>\workspaces\<OPSYS>\<COMPILER>\lib
Where:
•
<rw_root> is the root directory that contains the workspaces, parts, and
htmldocs directories.
•
workspaces is the name of the directory that contains all Rogue Wave
compiled libraries , header files, and examples. Notice that workspaces
is plural.
•
<OPSYS> is a mnemonic for the operating system used for a particular
build.
•
<COMPILER> is the mnemonic for the compiler used for a particular
build.
•
lib is the directory that actually contains the library.
UNIX users: note that in the LIB path, the operating system and compiler
mnemonics must be UPPERCASE.
Appendix A lists the mnemonics for all the compilers and operating
systems that Rogue Wave supports. Here are a few sample library paths,
using c:\rwav as the <rw_root> directory.
•
MSVC on NT:
c:\rwav\workspaces\WINNT\MSVC\lib
•
Borland on Windows 95:
c:\rwav\workspaces\WIN95\BORLAND\lib
•
Cygnus g++ compiler on SGI Irix:
rwav/workspaces/IRIX/GNU/lib
You must change the library path in all your project files if you're using an
IDE and in any relevant scripts or files that contain path information. In
addition, be sure to use the proper path if you run your compiler from the
command line.
Some compilers require the library name in the library path. Library
naming conventions are described in Section 2.3, and Section 3.1.3
provides a mapping from old library names to new. Check your compiler
documentation for accurate information for your compiler.
Tools.h++ Build Guide
Compiling with Tools.h++ 17
3.1.3 Library Names
The SPM configuration and build process uses a new library name
encoding. To use the version of Tools.h++ installed through SPM, you must
edit your IDEs, makefiles, and other files used in compilation, changing the
link library names that use the pre-SPM naming conventions to the current
naming conventions. Section 2.3 describes the current naming convention.
Table 5 lists the new library names and their old-style counterparts for
Windows libraries, and Table 6 lists the new and the old libraries for UNIX.
In the old library name column in Table 5, the symbol C
Table 5. Windows library names
New Library Name
Old Library Name*
* Replace the leading character <C> in the old library named with b for
Borland, m for MSVC, or v for VisualAge.
tls0s.lib or
<C>tlw.lib
tls8s.lib
tls3s.lib or
tls11s.lib
<C>tlwg.lib
tls4s.lib or
tls12s.lib
<C>tlwmt.lib
tls7s.lib or
tls15s.lib
<C>tlwgmt.lib
tls0d.lib or
tls8d.lib
<C>tld.lib
tls3d.lib or
tls11d.lib
<C>tldg.lib
tls4d.lib or
tls12d.lib
<C>tldmt.lib
tls7d.lib or
tls15d.lib
<C>tldgmt.lib
In Table 6, UNIX library names, the library name extension, *, remains the
same when converting from the new to old library name convention.
Table 6. UNIX library names
New Library Name
Old Library Name
libtls0s.* or libtls8s.*
librwtool.*
libtls3s.* or libtls11s.*
librwtoolg.*
libtls4s.* or libtls12s.*
librwtool_mt.*
libtls7s.* or libtls15s.*
librwtoolg_mt.*
libtls0d.* or libtls8d.*
librwtool.*
18 Compiling with Tools.h++
Tools.h++ Build Guide
New Library Name
Old Library Name
libtls3d.* or libtls11d.*
librwtoolg.*
libtls4d.* or libtls12d.*
librwtool_mt.*
libtls7d.* or libtls15d.*
librwtoolg_mt.*
3.1.4 Source File Location
You must provide the location of the library source files to your debugger
when you debug your programs.
The Tools.h++ source files are located in a directory equivalent to the
following, which uses <rw_root> as the root directory for SPM.
<rw_root>\parts\tls0706<os>\source\src
UNIX users, please read "\" as "/". Replace <os> with the abbreviation for
your operating system: w for Windows, u for UNIX.
3.2 Using Your Own RWCollectables in a DLL
Note: This section applies to user compiling DLLs on Win 32 only.
There's something that you need to look out for when you include your own
classes derived from RWCollectable in your DLL. Using the
RWDEFINE_COLLECTABLE macro in your own DLL that uses the Tools.h++
DLL may not produce the required results.
RWDEFINE_COLLECTABLE works by placing dummy variables at file scope.
The purpose of these variables is to initialize RWFactory through the side
effects of their constructors. Every process that attaches to the DLL gets its
own RWFactory, but the constructors for the dummy variables only get
called once, for the first process that happens to cause the DLL to get
loaded into Windows memory. Therefore, only this first process will have
its RWFactory properly initialized.
You know that you have this problem when you get a NOCREATE error while
restoring a persisted object. This error occurs when an RWFactory is faced
with restoring an object with an unfamiliar RWClassIDdue, in this case,
to its not being initialized via the aforementioned constructors.
The solution to this problem is to manually initialize the factory for each
process that attaches to your DLL by using:
RWFactory::addFunction(RWUserCreator, RWClassID)
See the Tools.h++ Class Reference for more information.
Tools.h++ Build Guide
Compiling with Tools.h++ 19
3.3 Compiling with Borland
This section describes how to use Borland's C++ compilers to compile
programs that use Rogue Wave's Tools.h++ class library.
3.3.1 Using a Static Version of Tools.h++ with Borland
These instructions assume that the Borland include files and libraries are in
the locations specified by the file bcc32.cfg for 32-bit compiles. If not, you
will have to specify -I and -L flags as well, or change your configuration
file (see the Borland User’s Guide for instructions).
Let's say that you have a file named test.cpp and that you are compiling it
in a Windows NT MS-DOS command prompt. Let's also say that your
Tools.h++ files are located in<rw_root>\workspaces\WINNT\BORLAND\lib,
and that you built a static version of Tools.h++ named tls0s.lib Then you
can compile test.cpp with the Borland C++ compiler with the following
command (all on one line):
bcc32 -I<rw_root>\workspaces\WINNT\BORLAND test.cpp
<rw_root>\workspaces\WINNT\BORLAND\lib\tls0s.lib user32.lib
This command will compile and link in one step.
•
The -I option describes the location of the Rogue Wave header files;
•
<rw_root>\workspaces\WINNT\BORLAND\lib\tls0s.lib is the full path
name for no debugging, single threaded, static Tools.h++ library for
Borland C++ (substitute as appropriate).
•
The user32.lib is the library for message-boxes and other widgets.
Note: Even if you are compiling a Windows NT or Windows 95 console
program that uses Tools.h++, you will still have to link in the user32.lib
library. Tools.h++ uses the Windows message box to report errors.
3.3.1.1 Using Tools.h++ with the Borland C++ IDE
When using the Borland C++ Integrated Development Environment (IDE),
you must add the Rogue Wave include path for Borland to every project,
for example, <rw_root>\workspaces\WINNT\BORLAND. Use menu selection
Options | Project | Directories.
You should also add the appropriate Tools.h++ library to your Project
Window. See the Borland User's Guide for instructions.
20 Compiling with Tools.h++
Tools.h++ Build Guide
3.3.2 Using the Tools.h++ DLL with Borland C++
Tools.h++ can be built as a DLL using Borland C++ under Windows 95 and
Windows NT. Be sure to review the documentation in the readme file for
additional tips on using the DLL.
See the dlldemo demonstration program in the directory
<workspace>\examples\tls0706w\ for an example of using and linking
with the DLL. See the DDE demonstration for an example of using the DLL
with DDE. Finally, be sure to review the documentation in the Tools.h++
User's Guide section entitled Dynamic Link Library, and the tooldll readme
for additional tips on using the DLL.
In order to use the 32-bit DLL version of Tools.h++, you must:
1.
Use the Borland run time library (RTL) DLL.
2.
Define the macros _RWTOOLSDLL and _RTLDLL on the compiler command
line. If Tools.h++ is using the Standard C++ Library, you must also
define _RWSTDDLL.
3.
You must link your program with the import library. The names of the
Borland C++ import library and DLL are:
Import library:
DLL:
tls#d.lib
tls70#d.dll
70 is the version number for the DLL, while # is a placeholder for the
basic build type. See Table 3.
4.
When you run your program, the Tools.h++ DLL and the Borland RTL
DLL must be in one of the following places:
•
The current directory;
•
The \WINDOWS directory;
•
The \WINDOWS\SYSTEM directory;
•
The directory containing the executable file for your program;
•
The directories listed in the PATH environment variable;
•
The list of directories mapped in a network.
If you get exceptions, especially in *.DLLs, and you can't figure out
where they're coming from, you may have incompatible *.DLL's
running. Check for incompatible DLLs in the indicated directories.
3.4 Compiling with MSVC
This section describes how to use Microsoft Visual C++ compilers to
compile programs that use Rogue Wave's Tools.h++ class library.
Tools.h++ Build Guide
Compiling with Tools.h++ 21
3.4.1 Using a Static Version of Tools.h++ with MSVC
Before starting, be sure that the Microsoft environment variables INCLUDE
and LIB are set to the proper search path for system #includes and
libraries, respectively.
Let's say that we have a file named test.cpp and that we are compiling it in
a Windows NT MS-DOS command prompt. Let's also say that our
Tools.h++ and Tools.h++ header files are located in
<rw_root>\workspaces\WINNT\MSVC\lib, and that we built a static version
of Tools.h++ named tls0s.lib Then we can compile test.cpp with the
Microsoft C++ compiler with the following command(all on one line):
cl -I<rw_root>\workspaces\WINNT\MSVC test.cpp
<rw_root>\workspaces\WINNT\MSVC\lib\tls0s.lib user32.lib
This command will compile and link in one step.
•
The -I option tells the compiler where to find the Rogue Wave header
files;
•
The entry <rw_root>\workspaces\WINNT\MSVC\lib\tls0s.lib is the
full path name for a no debugging, single threaded, static Tools.h++
library for MSVC (substitute as appropriate).
•
The user32.lib is the library for message-boxes and other widgets.
Even if you are compiling a Tools.h++ Windows NT or Windows 95
console program, you still need to link in the user32.lib library, because
Tools.h++ uses the Windows message box to report errors.
3.4.2 Using the Tools.h++ DLL with MSVC
Microsoft Visual C++ allows you to create a Tools.h++ DLL for 32-bit
Windows; that is, for Windows 95 and Windows NT.
See the dlldemo demonstration program in the directory
<workspace>\examples\tls0706w\ for an example of using and linking
with the DLL. See the DDE demonstration for an example of using the DLL
with DDE. Finally, be sure to review the documentation in the Tools.h++
User's Guide section entitled Dynamic Link Library, and the tooldll readme
for additional tips on using the DLL.
In order to use the 32-bit DLL version of Tools.h++, you must:
1.
22 Compiling with Tools.h++
Define the macro _RWTOOLSDLL on the compiler command line. If
Tools.h++ is using the Standard C++ Library, you must also define
_RWSTDDLL.
Tools.h++ Build Guide
2.
Use the -MD option on the compiler command line in order to use the
DLL version of Microsoft's runtime library.
3.
You must link your program with the import library. The name of the
Microsoft Visual C++ import library and DLL is:
Import library:
DLL:
tls#d.lib
tls70#d.dll
70 is the version number for the DLL, while # is a placeholder for the
basic build type. See Table 3.
4.
When you run your program, the Tools.h++ DLL and the DLL version
of Microsoft's runtime library must be in one of the following places:
•
The current directory;
•
The \WINDOWS directory;
•
The \WINDOWS\SYSTEM directory;
•
The directory containing the executable file for the current task;
•
The directories listed in the PATH environment variable;
•
The list of directories mapped in a network.
If you get exceptions, especially in *.DLLs, and you can't figure out
where they're coming from, you may have incompatible *.DLLs
running. Check for incompatible DLLs in your path.
3.5 Compiling in UNIX
To use the Tools.h++ library in your own program, simply add the directory
containing the Tools.h++ header files to your include list, and link to the
appropriate library.
For instance, to build a program called my_app you might use the following
command line (all on one line):
CC -I<rw_root>/workspaces/IRIX/CYGNUS my_app.cpp
<rw_root>/workspaces/IRIX/CYGNUS/lib/libtls0s.a
The example assumes that the built libraries were exported to the
<rw_root>/workspaces/IRIX/CYGNUS directory.
3.5.1 Shared Libraries
To compile using shared libraries, review toolread.doc.
Before running the resulting program, be sure to add the path to where
your library is installed to your LD_LIBRARY_PATH. This step is required
when compiling with SGI and is recommended for all shared UNIX
libraries. For example, if your library is installed in the
Tools.h++ Build Guide
Compiling with Tools.h++ 23
<rw_root>/workspaces/IRIX/CYGNUS directory, use the following command
(all on one line):
export LD_LIBRARY_PATH=\
"<rw_root>/workspaces/IRIX/CYGNUS:$LD_LIBRARY_PATH"
If you are running in other than a Bourne or Korn shell, the command is:
setenv LD_LIBRARY_PATH \
"<rw_root>/workspaces/IRIX/CYGNUS:$LD_LIBRARY_PATH"
24 Compiling with Tools.h++
Tools.h++ Build Guide
Appendix: Mnemonics
In order to ensure consistency of information across products, mnemonics
have been created for all Rogue Wave products, operating systems,
compilers, and build options. The Software Parts Manager uses these
mnemonics to name files and directories
Rogue Wave Products
Mnemonic
Rogue Wave Product
BCH
C++ Booch
DBF
DBFactory
DBT
DBTools.h++ Core
INF
DBTools.h++ Informix
ING
DBTools.h++ Ingress
ODB
DBTools.h++ ODBC
ORA
DBTools.h++ Oracle
CTL
DBTools.h++ SybCT
SDB
DBTools.h++ SybDB
MSQ
DBTools.h++ MSSQL
HEP
Heap.h++
JFY
JFactory
JLB
JLibraries
JMY
JMoney
JTS
JTools
JWS
JWidgets
JCT
JChart
LPK
LaPack.h++
LPT
LaPackPro.h++
LNK
LinPack.h++
LNT
LinPackPro.h++
MAA
Math Accelerator
MTH
Math.h++
Tools.h++ Build Guide
Appendix: Mnemonics 25
Mnemonic
Rogue Wave Product
DBT
Money.h++
MEM
Memento Style Libraries
NET
Net.h++
INT
InterNet.h++
ORB
ORBstreams.h++
OBF
Object Factory (the application)
OSD
Object Factory Source Driver
Libraries
STD
Standard Library
STT
Test Suite for Std. Lib.
THR
Threads.h++
TLS
Tools.h++
TLT
Test Suite for Tools.h++
TLO
ToolsObjStore
VIW
View.h++
ZAP
zApp
ZFY
zApp Factory
ZHP
zApp Help
ZPK
zApp Interface Pack
ZDP
zApp Data Pack
Operating System Families
Mnemonic
Platform
M
PowerPC Macintosh
68K Macintosh
O
OS/2
U
General UNIX
HP-UX UNIX
Solaris UNIX
SunOS UNIX
DEC UNIX
NCR SVR4
SCO 3.0
OSF 1.3x
IBM/AIX
26 Appendix: Mnemonics
Tools.h++ Build Guide
Mnemonic
Platform
Irix 5.x
Linux
W
Windows 3.x/NT/95
Windows 3.x
Windows NT/95
Windows NT
Windows 95
Operating Systems
Short mnemonic
Long mnemonic
Operating System
A
AIX
IBM AIX
H
HPUX
HP Unix
I
IRIX
SGI Irix
IRIX64
SGI Irix 64-bit
N
NCR
NCR SVR4 PC Unix
D
DIGITAL
Digital Unix (formally
OSF/1)
O
OS2
IBM OS/2
OS2WIN
IBM OS/2 for MS
Windows
SCO
SCO PC Unix
S
SOLARIS
SunSparc Solaris
Z
SUNOS
SunSparc SunOS
4
WINNT
MS Windows NT
WINNTDEC
MS Windows NT for
DEC
2
WIN31
MS Windows 3.1
4
WIN32S
MS Windows 32s OS
API
4
WIN95
MS Windows 95
M
MAC
MAC OS
Tools.h++ Build Guide
Appendix: Mnemonics 27
Compilers
28 Appendix: Mnemonics
Mnemonic
Compiler
BORLAND
Borland
CLINE
Centerline
CLS
C++ Language System
CSET
IBM Cset++
CWARRIOR
Code Warrior
CYGNUS
Cygnus GNU
DEC
DEC
HP
HP
METROWKS
Metroworks
MPWPRO
MPW Pro
MSVC
Microsoft Visual C++
SGICC32
SGI C++ Compiler with -n32
SGICC64
SGI C++ Compiler with -64
SGICFRNT
SGI Cfront
SGIDELTA
SGI Delta Compiler
SUNCFRNT
Sun Cfront
SUNPRO
SunPro
SYMANTEC
Symantec
VISAGE
IBM Visual Age
WATCOM
Watcom
Tools.h++ Build Guide