If you are moving from SPM to RCB, to use RCB, you must do the following:
Build your components. Section 5.4.1
Rebuild your legacy applications. Section 5.4.2
Consider backward compatibility issues. Section 5.4.3
The easiest way to build your new SourcePro C++ components in RCB is explained in Chapter 2.
As an alternative to simply installing your components into the RCB directory structure as explained in Chapter 2, you can use RCB to build Rogue Wave components with the same name and directory locations they had when built with SPM.
The following example shows the procedure for using your existing SPM directory structure.
You do not have to use this procedure. You only need to use this procedure if you want to imitate your existing SPM directory structure instead of using the default RCB directory structure.
This example assumes the following SPM structure:
spm_root
workspace
/SOLARIS56
/SUNPRO5
/12s
/lib
/rw
/15d
/lib
/rw
|
Assuming you have installed the Essential Tools Module into an arbitrary RCB buildspace, you would do the following:
Rename existing workspace directories to 12s.old and 15d.old.
Create new, empty 12s and 15d directories.
If your SPM workspaces make use of symbolic links, you will probably need to eliminate them before you can direct RCB builds to those workspaces. Otherwise, those builds may fail with the error message "Unable to verify Buildspace is properly homed." This means RCB cannot verify that the buildspec being processed is correctly located in the buildspace it specifies, a consequence of RCB being unable to follow the symbolic link.
In RCB, create a buildspec that does the following. Chapter 2 explains how to create buildspecs.
Uses the export buildspace option, specifying the path to the 12s directory for the export buildspace.
Specifies Headers for the Copy these files option.
Specifies the appropriate build options for a 12s build (standard library, single-threaded, static, release).
Uses the SPM build tag naming convention.
Create a buildspec for the 15d configuration by repeating Step 3 and specifying the appropriate build options for a 15d build.
Click Done editing buildspec to submit the buildspec to the build queue.
The result should be Essential Tools Module builds that create appropriately named libraries in .../12s/lib and .../15d/lib, and that place the header files in .../12s/rw and .../15d/rw. The source code remains in the RCB buildspace, which is similar to the SPM case where the source code was stored separately in the parts directory tree.
Dynamically linked libraries on UNIX platforms now include the major and minor version number in the name. Section 5.4.3 explains details.
With SPM, when building an application that linked in Rogue Wave components, you needed to do four things on the build command line:
Specify an include path to the appropriate Rogue Wave workspace, and indicate the path to the Rogue Wave components to be linked in
Declare a number of Rogue Wave command line macros
Declare system compiler flags, libraries, and macros appropriate to the build type
This section shows how these issues worked on an SPM command line, what to do now, and what the functionally equivalent RCB command line looks like.
To help illustrate these issues, let's start by looking at this example of a command line invocation under the SPM model, for an application that links to Tools.h++ built in the 12s configuration:
cl -Ic:\rwav\workspaces\WINNT4\MSVC60\12s -nologo -DWIN32 -DNOMINMAX -DRW_NO_STL=1 -GX -MD -W3 myapp.cpp c:\rwav\workspaces\WINNT4\MSVC60\12s\lib\tls12s.lib user32.lib |
You do not need to change the first requirement, include path and component paths, if you have chosen to place your RCB build results into your legacy SPM workspaces. If you have chosen instead to build into the RCB buildspace, you may need to alter any makefiles and automation scripts to point to the new locations.
The second requirement, command line macros, was a ready source of errors with SPM because it was often difficult to determine the correct set of macros to declare.
With RCB, this has been greatly simplified. Rather than declaring a string of command line macros, you need define only a single macro, _RWCONFIG=buildtag, where buildtag is the build type tag generated by the build of the SourcePro C++ components plus an optional user tag.
So, for the Essential Tools Module built in a 12s configuration, the macro declaration would be _RWCONFIG=12s, assuming the user specified no user tag.
The inner workings of the _RWCONFIG=buildtag macro are explained in Building Your Applications, listed in Section 1.6.
The third requirement, system compiler flags, libraries, and macros, was also tricky with SPM since there was no easy source of information on what the appropriate flags were.
Be aware that with RCB, compiler flags required for certain build configurations on Windows have changed, as explained in Section 5.4.3.4.
To find the system libraries, compiler flags, and macros, look in one of these places:
Build logs, located at buildspace\records\results\buildtag\index.html (the best, most reliable starting point), buildspace\examples\module-name\buildtag, and buildspace\source\module-name\buildtag
Example for a 12s build: buildspace\records\results\12s\index.html
The best choice is the log file for one of the example applications. The log file shows all the actual command line build invocations used, any of which shows the system compiler flags and macros used. The link command line near the end of the log file shows any system libraries included.
Makefiles, located at buildspace\examples\module-name\buildtag, or buildspace\source\module-name\buildtag
Essential Tools Module example: buildspace\examples\tools\12s\makefile
Look at one of the makefiles generated for the build configuration you are using. The best makefile to consult is one for an example application, because this most closely resembles your situation. Search on CPPFLAGS, which defines the variable used to insert the required system compiler flags and macros onto the command line. Then search on LINKLIBS to see whether any system libraries were included at link time.
Note that a few system macros — non-Rogue Wave macros outside the scope of the _RWCONFIG=buildtag macro — are defined through CPPFLAGS and end up directly on the command line. These include _REENTRANT for multithreaded builds on UNIX, WIN32_LEAN_AND_MEAN for Essential Networking Module builds on Windows, and some standard Windows macros such as NOMINMAX and WIN32.
For more complete information on meeting system requirements, see Building Your Applications, listed in Section 1.6.
Here is the example command line given for SPM, modified to reflect RCB:
cl -Ic:\RW_buildspace -D_RWCONGIF=12s -nologo -DNOMINMAX -DWIN32 -MD -GX -W3 -O2 -GA myapp.cpp c:\RW_buildspace\lib\tls12s.lib user32.lib |
There are a number of specific issues to consider when rebuilding legacy applications that depend on Rogue Wave libraries. The final three items may require changes to your makefiles or automation scripts.
Link compatibility
Dynamic library naming on UNIX platforms
Other library name issues
Changed compiler options on Windows platforms
All products in the current release break link compatibility with previous Rogue Wave products. Before rebuilding your legacy applications, rebuild all Rogue Wave libraries on which they depend.
On UNIX platforms, dynamically linked library names formerly had no product version information. For example, a dynamically linked version of Rogue Wave Tools.h++ on Solaris had a name such as tls15d.so.
To support the use of multiple versions of dynamically linked libraries, the library names now include the major and minor version numbers. So the Essential Tools Module library would have a name such as tls7515d.so.
The functionality that used to reside in the int and net libraries of Tools.h++ Professional is now contained in the Internet Protocols and Essential Networking modules of SourcePro Net. The implications are:
If your legacy applications linked to the net library, they must now link to the network library of the Essential Networking Module. So, for example, if your legacy applications linked to net15s.lib, they must now link to network15s.lib.
If your legacy applications linked to the int library, they must now link to one or more packages of the Internet Protocols Module. See the Modules tab of the SourcePro C++ API Reference Guide for information on which classes reside in which packages. So, for example, if your legacy applications linked to int15s.lib, they must now link to one or more of the following: internet15s.lib, ftp15s.lib, http15s.lib, pop315s.lib, and smtp15s.lib.
The Threads Module of SourcePro Core incorporates the functionality of the previous Rogue Wave product Threads.h++. The point at which Threads.h++ was divided into packages, release of Threads.h++ 2.x, addressed backwards compatibility. It did so by providing a thr library that included all the classes of Threads.h++. A full build of the Threads Module does not produce a thr library, but only the individual package libraries.
Similar to the case of the Internet Protocols Module described above, refer to the Modules tab of the SourcePro C++ API Reference Guide for information on which classes reside in which packages, and then link your legacy applications to the required package libraries.
Static builds on Microsoft Visual C++ were changed to use the runtime library options /MD or /MDd. This decision was necessary to accommodate user needs and third-party library requirements. As a result, the Rogue Wave static libraries, and applications built with them, are now dependent on the Microsoft C Runtime Library DLLs (MSVCRT.DLL for release-mode, and MSVCRTD.DLL for debug-mode).
If you are upgrading from Rogue Wave products that used the Microsoft static runtime libraries, you must switch to the DLL runtime libraries. You can use one of the following methods:
If you work in the Visual Studio environment, choose Project | Settings..., click the C++ tab of the settings window, choose Code Generation from the Category drop-down box, and choose Multithreaded DLL or Debug Multithreaded DLL, for release or debug mode builds, respectively.
If you invoke the compiler directly (for example, through a makefile), replace the /ML and /MT flags with /MD for release mode builds, or replace the /MLd and /MTd with /MDd for debug mode builds.
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.