You can build Objective Toolkit in many different ways to support a variety of operating systems and VC++/MFC configurations. For example, you can build Objective Toolkit for any of the latest Visual Studio compilers. (For a full support matrix, go to the Stingray product page on the Rogue Wave web site, www.roguewave.com/products/stingray.aspx, and click on Supported Platforms.) In addition, your build configuration may specify any combination of build flags such as debug or release, Unicode or ANSI, static or DLL.

You can obtain prebuilt versions of the libraries by request to Rogue Wave technical support. Libraries are available for Windows XP and Vista with the currently supported compilers. We recommend, however, that you build the libraries yourself. The prebuilt libraries are built with a particular instance of Visual Studio and the Windows operating system. Building the libraries yourself ensures that they are compatible with your version of the compiler and the operating system they are built on.

A Build Configuration Wizard is included with Objective Toolkit (utils\ToolkitBuildWiz.exe). The Build Wizard is a powerful tool that allows you to build various versions of the Objective Toolkit library with different configurations. For example, you can build a version of the library that only includes the features that pertain to your project. This is an effective technique for reducing the binary size of the resulting Objective Toolkit libraries and DLLs.

Objective Toolkit is distributed with build files for the default configuration that includes all the Toolkit features. You do not need to run the Build Wizard to build the default configuration.

The SRC subdirectory contains build files for every version of Visual Studio that Objective Toolkit supports. To build Objective Toolkit, open the appropriate build file. After you load it, examine the different build configurations that specify the settings such as debug or release, Unicode or ANSI, static linking or DLL, and more. You can choose a particular configuration and build only that library variant, or select the All configuration and build every variant of the Objective Toolkit library in one build session. To choose a build configuration, select an item from the Set Active Configuration combo box in Visual Studio or start a Batch Build and select several variants to be built at once.

The Build Configuration Wizard is a wizard dialog that allows you to select every feature you want to include in the resulting library. After you answer a few simple questions, the Build Wizard automatically generates a custom tailored makefile that you can build to create the Objective Toolkit library in the configuration you specified. You can customize the names of the libraries to avoid any potential name collisions or versioning problems.

You can generate multiple library configurations with the Build Wizard. For example, you could generate one with just a tree control and another with only the docking windows code. Several different configurations can coexist on your hard disk simultaneously. The Wizard dialogs describe this procedure. Give the target libraries of different build configurations different target names to avoid name collisions.

The Objective Toolkit components are now built into two libraries: Stingray Foundation Library (SFL) and OT. If you want to create a set of libraries with a special configuration, you should run the Build Wizard for both libraries, specifying the same configuration name.

The Build Wizards automatically generate custom linking header files that you can include in your project. These header files are located in the include\toolkit\config directory for the Toolkit library and include\foundation\config directory for the SFL library. The Build Wizard created these files when you rebuilt the library. They have the same name as the library to which they link, with the added prefix sfl_ or ot_ .

To link to the custom configuration in your application, insert the following lines into stdafx, before you include toolkit\secall.h or any Objective Toolkit component headers.

When you build a custom configuration of Objective Toolkit, you must specify a unique DLL target name. When you build a subset of the Objective Toolkit features or make a change to the Objective Toolkit source or header files, the signature of the library changes. So, when you build a DLL that incorporates a subset of Objective Toolkit features or your own changes, you need to treat the target DLL like a completely unique DLL. If you change the signature of Objective Toolkit and do not specify a new DLL target name, other applications that link to the Objective Toolkit DLL may fail.

The Objective Toolkit build files and header files use #ifdef’s on several compiler flags to define the configuration variants described above.

You can use the standard symbols, _DEBUG, _UNICODE, and _AFXDLL, to select support for debugging, Unicode characters, and linking to MFC as a DLL.

The flags in Table 1 are specific to Objective Toolkit.

The library naming conventions are illustrated in Figure 1.

The following table shows the default library names for the various configurations, where <ver> stands for the current product version number. Refer to the naming convention described above.

Whenever you run the Build Wizard, it overwrites sflversion.h in the SFL (include\foundation) include directory or secver.h in the Objective Toolkit (include\toolkit) include directory with the names of the libraries. This information is used to link the libraries to your project automatically.

If you are maintaining more than one library configuration on your system, this can cause problems. Your projects link to whatever configuration was last set up by the Build Wizard.

To avoid problems when switching library configurations, run the Build Wizard specifying the desired configuration for each of the Objective Toolkit libraries.

When you build the Stingray libraries in Visual Studio, Visual Studio invokes make files that ship with the product. For information on these underlying make files, and how to build the libraries by invoking nmake on these files directly, see “Building from the Command Line with nmake” in the Getting Started part.

This section also discusses the issue of building the libraries with 1-byte structure alignment rather than the default 8-byte structure alignment.

Run-Time Type Information (RTTI) support is required for some components. When you run the Build Wizard, RTTI support must be enabled if you include:

To learn more about this requirement, see our Knowledge Base at (kb.roguewave.com/kb/).

Each sample project has a variety of build options to show you how to use the various build configurations. All 32-bit and 64-bit samples build with the following targets:

If you check the Project Settings|C/C++ tab|Preprocessor Definitions for several target configurations, you can see how the compiler flags link to the appropriate Objective Toolkit library variant automatically.

You indicate exactly which Objective Toolkit library you want to link by defining a combination of _DEBUG, _AFXDLL, _UNICODE, and _SECDLL in your project’s preprocessor definitions.

After you build the libraries, you can start using Objective Toolkit classes in your own applications. Follow the steps below to add Objective Toolkit to an existing application.

If you have any problems using a specific class, refer to the online Objective Toolkit Class Reference. Each section of the Class Reference discusses one class or a group of related classes and includes an overview, step-by-step instructions, and important member functions. We also cite Objective Toolkit samples that demonstrate the use and capabilities of the class.

For information on creating an application with our AppWizard, see Chapter 3, “The Objective Toolkit AppWizard.” For information on using component headers, see “The Component Headers”.