CBM User Guide
Index
IndexCBM User Guide
This topic discusses how to build Rogue Wave software parts using command line invocation of the configuration and build model (CBM). The major sections are:
Related topics include:
Before proceeding, be sure that:
After the above two actions, you have a CBM directory structure that is very nearly a complete Software Parts Manager directory structure, ready and waiting for the day you obtain the SPM graphical interface, and you have a product tree for the product you are going to build.
The Control Script
rwspm
Rogue Wave provides the control script rwspm for performing command line builds through CBM. We encourage you to conduct your builds using the more flexible Software Parts Manager graphical interface distributed on our CD or from our web site. If you lack access to the GUI, rwspm must be used.
The rwspm script has the following syntax:
rwspm -t<build type> [-d] [-g|-G] [-l] -f<compiler properties file name>
-p<product tree path> [-w<workspace path>]
Do not place any spaces between argument flags and their associated values or errors may result.
The following invocation would create a shared, multithread Tools.h++ library built on the Standard C++ Library, but without symbolic debugging:
rwspm -t12 -d -fw32_msvc.in -pc:\rwav\parts\tls0707w
-wc:\rwav\workspaces\win95\msvc50\12d
The following paragraphs describe each of the arguments.
<SPM_root>/scripts/platform, which contains a file for each of the environments (operating system and compiler combinations) that Rogue Wave supports. The naming convention is <OPSYS>_<COMPILER>.in. For example, the file for Microsoft Visual C++ on Windows 95 would be w32_msvc.in.
w32_msvc.in:
# Shell script used as an input file to rwsetup # Supports "cl" (MSVC) on WINNT # --- Compiler and OS Names --- RWOPSYS=WINNT RWCOMPILER=MSVC # --- Compiler Settings --- RWCPP="cl" RWFIRST_CCOPTS="" RWLAST_CCOPTS="" RWFIRST_LINKOPTS="" RWLAST_LINKOPTS=""
Modifying the platform files may cause CBM not to work. The only modifications you should consider making are:
RWFIRST_CCOPTS, RWLAST_CCOPTS, RWFIRST_LINKOPTS, and RWLAST_LINKOPTS, which allow you to insert within the quotes custom compiler or link arguments. The RWFIRST versions place the arguments before any arguments supplied by CBM; the RWLAST versions place your arguments after those supplied by CBM. How the positioning affects the assigned precedence depends on the compiler you are using. Also, remember that if you specify custom options for a product such as Tools.h++ on which other products depend, you will need to duplicate those custom options when you build the dependent product.
UNIQUE_LIB, which attaches a custom suffix to the library name.
Note that the LINKOPTS specifications apply only to application builds, not to library builds.
The specification -fNULL indicates an unsupported platform and forces the insertion of question and answer breaks in the build to obtain platform-specific configuration data.
rwspm -G, which completes the creation and installation of examples makefiles and source in the workspace after you manually invoke make to build a library.
make to create a C++ library. The rwspm -G invocation continues the interrupted build process with the creation and installation of examples makefiles and the installation of examples source. Normally used subsequent to rwspm -g.
<workspace>/buildloc/<part>. This can be useful in debugging.
<rw_root>/parts/<product name>. For Tools.h++, this would be <rw_root>/parts/tls0708<os>, where <os> is w for Windows, o for OS/2, or u for Unix.
<rw_root>/workspaces/<OPSYS>/<COMPILER>/<BUILDTYPE>. For Tools.h++ compiled for Microsoft Visual C++ on Windows NT with a build type of 3s this would be
<rw_root>/workspaces/WINNT/MSVC/3s
-w option to specify the workspace path. For the above example, if the NT version were 4.0 and the Msvc version were 5.0, you would specify
-w<rw_root>/workspaces/WINNT4/MSVC50/3s
Before running the build process, be sure you have carefully read:
<rw_root>/htmldocs. For Tools.h++, this document would be in the subdirectory tls<ver>in (for example, tls708in), and the home page file would be tindex.html.
rwspm and its arguments. You should know ahead of time the argument specifications you need.
Another good source of information on building your product is the build guide, located in <rw_root>/htmldocs. Look for a directory named with the product mnemonic, a three-digit version number, and the suffix bd, such as tlsnnnbd for Tools.h++, and open the file tindex.html in the HTML browser of your choice. Although written with the assumption that the user has the Software Parts Manager graphical interface, the cautions and warnings about product- or environment-specific requirements are equally applicable to CBM builds.
You should also consult Section 4 of the build guide for advice on compiling applications that link to the Rogue Wave product libraries.
Another thing to consider is whether you want a standard CBM-generated library name (in which case you don't need to do anything special), or you wish to add a custom suffix to the name. A custom suffix helps you to generate distinct library names in special cases where this is necessary.
As an example of an rwspm invocation, let's suppose that you are building Tools.h++ on top of the Rogue Wave Standard C++ Library. (You would need to have already built the Standard C++ Library.) The library is to be shared (DLL), multithreaded, and without debugging. You are compiling for Microsoft Visual C++ on Windows NT, your Rogue Wave root directory is c:\rwav, and you are accepting the default workspace location (so you do not need to specify the -w argument). Your invocation would be:
rwspm -t12 -d -fw32_msvc.in -pc:\rwav\parts\tls0707w
Here is the procedure for running a build:
<spm_root>/scripts. You must be in this directory when running rwspm. If not, it won't work.
rwspm, something on the order of the example above.
The build creates a workspace if one does not already exist. By default the workspace path is based on the operating system, the compiler, and the build type used in the build, unless the -w argument was specified in the build invocation.
In the workspace, a library build creates the directory buildloc/<part> in which to implement the build. The build makefile or makefiles, the resulting object files, and, if requested, the implementation source files end up in this directory. Header files required by applications do not end up here. These are copied to the rw directory within the workspace.
Note that the build does not clean up the object files generated by the build. You must do this yourself by:
buildloc/<part directory (or buildloc in its entirety). But remember that the makefile(s) are there as well and you might want to preserve them.
make clean or other tools native to your environment.
rwclean.
Other topics that might interest you at this point are Library Naming Conventions and Compatibility Issues, which discusses the implications if you have older versions of Rogue Wave products.
Building Examples
The script rwspm cannot be used to compile example code. The good news, however, is that the command line build process sets everything up so you can fairly effortlessly build the examples through your compiler's make command.
When rwspm is used to build a library product, all example source code and makefiles are exported to an examples/<part> directory located in the workspace directory. The default location would be:
<rw_root>/workspaces/<OPSYS>/<COMPILER>/<BUILDTYPE>/examples/<part>
For the Tools.h++ build discussed above, the source would be located by default in
<rw_root>/workspaces/WINNT/MSVC/12d/examples/tls0708w
For some products, the examples/<part> directory has subdirectories containing subsets of the examples.
To compile the examples, therefore, all you have to do is change to the examples source code directory (or directories) and invoke your compiler's make command, either globally by specifying no argument, or for a particular target by specifying a file name argument. Look at the makefile for a listing of the specific example targets available.