3.5 General Buildspec Questions
Two question types exist in RCB: general and module-specific. Whenever you create a buildspec, you must always answer the general questions. Module-specific questions depend on the modules selected on the Select Components screen.
The following sections explain the general and module-specific questions you may encounter while creating a buildspec.
Section 3.5 explains general buildspec questions.
Section 3.6 explains module-specific questions.
The descriptions assume that the default option
Restrict available answers to support matrix is turned on, as explained in
Section 3.4.4.
3.5.1 Select Buildspec
You must specify whether you want to create a new buildspec file or edit an existing buildspec file. If there are no buildspec files available to RCB, you can only create a new buildspec file.
Three options are available:
Create a new buildspec from scratch.Go through the whole buildspec creation process and specify all build options.
Edit an existing buildspec: Go directly to build queue screen: Jump to the build queue to execute one or more buildspecs.
If you have never created a buildspec, you must choose Create a new buildspec from scratch. If previously created buildspecs are available to RCB, you can choose to edit those buildspecs or go directly to the Build Queue screen.
3.5.2 Select Buildspace
A buildspace is the location where SourcePro components are installed and buildspecs are stored. RCB provides two buildspace options: local and export. This section explains local and export buildspaces. Additional information on buildspaces is in Chapter 4.
In RCB, you must specify the Local buildspace, the directory that contains all the Rogue Wave components used in the creation of the buildspec. The results of executed buildspecs are also placed here unless otherwise stated. Optionally, you can select an Export Buildspace, a separate location where you want the executed buildspecs to be stored.
RCB does not support symbolic links. If you use symbolic links, you are likely to see this error message when you submit a buildspec: “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. RCB then aborts the build.
3.5.2.1 Local Buildspace
The local buildspace must be a directory into which the installation scripts have installed Rogue Wave components. RCB will not accept other selections.
The choice you make determines
where the buildspec will be stored.
the components you can build (only those that have been installed into the designated buildspace).
the target for build results, if you did not check the
Export the build box.
3.5.2.2 Copying Buildspecs
Running the RCB GUI across a network can be slow. Also, certain combinations of Java Virtual Machine implementations and display environments do not seam together well, sometimes yielding bugs in the GUI rendering process.
RCB allows a buildspec file to be created on one RCB installation and then executed on another. This allows you to work around the GUI rendering problems.
You can copy a local build or an export build. An example of each is listed below. For the purposes of the example, two definitions must be defined:
Local Installation: The on site installation of RCB, preferably displayed on the same machine it is being run on.
Remote Installation: The installation of RCB in which builds need to be executed.
Copying Local Buildspecs
This example assumes that you are working on a Windows platform.
Install RCB and SourcePro C++ components in both the local and remote installations. Both installations must have the same products installed.
Create a new buildspec in the local RCB installation.
On the
Select Buildspace screen, use the local buildspace value that is appropriate for the local installation.
On the
Select Operating System screen, specify the operating system that is appropriate for the remote environment where the buildspec will be executed.
On the
Select Compiler screen, specify the compiler that is appropriate for the remote environment where the buildspec will be executed.
On the
Select Naming Convention screen, add a user-tag to help identify the buildspec. This makes it easier to handle the buildspec files directly.
On the
Build Queue screen, create all required buildspecs, then exit RCB. These buildspecs will automatically be added to the Build Queue screen. Do
not launch the builds locally.
Copy the newly created buildspec files (recognized by the
.bsf extension) from
<buildspace_of_local_installation>\records\specs\ to a location accessible by the remote system.
Execute the copied buildspec files on the remote machine via a command line build.
For this copy attempt to work, the buildspace value in the buildspec must be appropriate for the machine it will build on. To make the buildspace value appropriate, it must be changed or overridden. Rogue Wave recommends using the existing RCB command line option (-S) to override the buildspace value at build time:
rcb build -b <desired_buildspec> -S <buildspace_of_remote_installation>
Note that this does not replace the buildspace value in the buildspec file itself. For more help on the override options available in RCB, type:
rcb build -help
Copying Export Buildspecs
This example assumes that you are working on a Windows platform.
Install RCB and SourcePro C++ components in both the local and remote installations. Both installations must have the same products installed.
Create a new buildspec in the local RCB installation.
On the
Select Buildspace screen, use the local buildspace value that is appropriate for the local installation.
On the
Select Operating System screen, specify the operating system that is appropriate for the remote environment where the buildspec will be executed.
On the
Select Compiler screen, specify the compiler that is appropriate for the remote environment where the buildspec will be executed.
On the
Select Naming Convention screen, add a user-tag to help identify the buildspec. This makes it easier to handle the buildspec files directly.
On the
Build Queue screen, create all required buildspecs, then exit RCB. These buildspecs will automatically be added to the Build Queue screen. Do
not launch the builds locally.
Copy the newly created buildspec files (recognized by the
.bsf extension) from
<export_buildspace_of_local_installation>\records\specs\ to a location accessible by the remote system.
Execute the copied buildspec files on the remote machine via a command line build.
For this copy attempt to work, the buildspace value in the buildspec must be appropriate for the machine it will build on. To make the buildspace value appropriate, it must be changed or overridden. Rogue Wave recommends using the existing RCB command line option (-S) and (-E) to override the buildspace value at build time:
rcb build -b <desired_spec> -S <local_buildspace_of_remote_installation>
-E <export_buildspace_of_remote_installation>
Note that this does not replace the buildspace value in the buildspec file itself. For more help on the override options available in RCB, type:
rcb build -help
When transferring export buildspecs, ensure that all specs transferred into a given export_buildspace_of_remote_installation have consistent settings for the “which files to copy” setting (headers vs. headers and source).
3.5.2.3 Export Buildspace
To place the build results in a buildspace different than the local buildspace, click Export the build and specify a path in Export buildspace field. This is the buildspace where buildspec results will be placed from now on.
If you choose to export the build, all of the resources needed for the build — buildspec, source code, component data — are still taken from the local buildspace, but the build results — compiled components, object files and makefiles — are placed in the specified export buildspace. By default, RCB also copies the header files to the export buildspace. If you select Headers and source from the Copy these files pulldown menu, the source code is copied as well.
If you select a preexisting location as the export buildspace, and that location already contains Rogue Wave source code, RCB forces Headers and Source to be selected in the Copy these files pulldown menu. This requirement prevents a situation where the source code in a buildspace is not the same code used to create the built components in that buildspace. Likewise, you cannot export into an existing export buildspace that was created from a different source buildspace.
3.5.3 Select Components
In RCB, the components you can build are listed in a tree structure with clickable boxes. Components that can be installed include products, modules, libraries, and examples. To select a component for installation, click the box beside it to create a check mark. At build time, makefiles are created for all components with check marks beside them.
The components that appear on this screen reflect the products installed into the selected buildspace.
Selecting a higher-level check box results in a black check mark, indicating that all subordinate items have been automatically selected.
Selecting some but not all lower-level items results in a grey check mark in the higher-level check boxes.
3.5.3.1 Dependency Checking
RCB checks that all dependent components are installed before continuing with the buildspec question sequence. A popup screen appears to inform you of the additional necessary components.
Dependency checking requires that all needed components be checked, even if you have installed and built some of these components previously.
RCB arrives at this decision based on its detailed knowledge of Rogue Wave components and their requirements. If previously built components are safe to use, RCB will use these components. If there is a risk of compatibility problems with the selected component, it will rebuild that component.
3.5.4 Select Build Action
When you have selected the components that you want to build, select the build action to be followed by the build manager when processing the buildspec.
Three choices are available:
Build libraries and examples Build all selected components.
Build libraries only Produce makefiles for the libraries and examples selected in the component tree, but only build the libraries. This option lets you build the examples on your own by typing make (or nmake) in the appropriate directory.
Create makefiles only Stop after creating the makefiles. This option supports situations where you want to invoke make (or nmake) on the makefile from the command line.
3.5.5 Select Operating System
The drop-down list of operating systems makes available only those systems for which all selected components have been certified. If your operating system does not appear on the list or is greyed out, go back to the component selection screen and check the selected components against the Rogue Wave support matrix. The support matrix is available from your account representative and in your CD release notes.
If all selected components appear to be certified but the operating system is still not available, please contact Rogue Wave Technical Services as explained in
Section 1.8, “Technical Support,” in the
Introduction to SourcePro C++.
3.5.6 Select Compiler
The drop-down list of compiler versions contains only those compilers for which all selected components have been certified. If your compiler version does not appear on the list, go back to the component selection screen and check the selected components against the Rogue Wave support matrix. The support matrix is available from your account representative and in your CD release notes.
If all selected components appear to have been certified but the compiler is still not available, please contact Rogue Wave Technical Services as explained in
Section 1.8, “Technical Support,” in the
Introduction to SourcePro C++.
3.5.7 Select Bitwidth
This option allows you to select whether the libraries and executables resulting from the build are compatible with 32-bit or 64-bit systems. The default value is 32-bit. If only a single choice is available, it is because the platform supports only that choice.
3.5.8 Select Linking
The choices are static and dynamic (also known as shared or DLL). If only a single choice is available, it is because your response to an earlier question either requires or forbids dynamic linking.
3.5.9 Select Threading
If you choose None, a single-threaded build is created. The other choices available depend on the threading libraries supported by your choice of operating system (for example, Windows supports only Win32, but Solaris supports posix, and solaris threads).
If None is missing or the only choice, it is because a response to an earlier question either requires or forbids multithreading.
3.5.10 Select Debugging
Selecting No indicates you do not want debugging enabled. Disabling debugging signals the creation of a release version of the component. In this case, the compiler’s default level of optimization is enabled. Selecting Yes indicates you want debugging enabled.
If only one choice is available, it is because your response to some earlier question either requires or forbids debugging.
3.5.11 C++ Standard Library Selection Screen
This screen appears only if you have selected one of the Solaris operating systems, in which case it follows the Debugging Options screen.
Two choices are available:
Native Use the system default C++ Standard Library implementation.
STLPort Use the STLPort implementation.
3.5.12 Select Compile and Link Options
Specify the compile and link options that you want to use. Options can be added to the compile, link, and library creation command lines. In each case, you can add your options either before or after the options specified by the RCB build manager.
This is an advanced question that is visible only when the Show advanced questions box is selected on the Options dialog’s Advanced Questions tab.
If any of your options conflict with those specified by the build manager, the location of options specified on this screen determines which specification takes precedence. Order of precedence is compiler-specific. Consult your compiler documentation to determine how your compiler behaves.
3.5.13 Select Naming Convention
These questions determine the string that is used in the built component names to indicate the build type. For example, in the library name tls12s.lib, the build tag part is 12s.
When you select a convention, the Build tag and Description fields are filled in automatically based on answers to previous questions. The User-defined tag field allows you to add your own identifier to the component name.
The build tag also determines the buildspec name; that is, a build tag of 12s creates a buildspec of the name 12s.bsf. If your buildspace already contains a buildspec for the configuration you are defining, the new buildspec will overwrite the existing one unless you specify a different naming convention or supply a user-defined tag.
The easiest solution is to define a user-defined tag, which becomes part of the buildspec name, making it different from the existing one. For example, the user-defined tag “_solaris” would change the buildspec name 12s.bsf to 12s_solaris.bsf, thus preserving the existing buildspec.
3.5.13.1 Naming Conventions
The
Select a naming convention drop-down menu offers three choices.
Table 3 summarizes the types of build tags each choice generates.
Table 3 – RCB component naming conventions
Convention | Description |
SPM | Tags used by Software Parts Manager (SPM), such as the 12s tag shown above. This choice is provided for backwards compatibility so you can produce components through RCB with the same naming conventions as those produced through SPM. |
RCB | A system of one-letter codes to indicate certain build options. The advantage is concise component names, but a drawback is the need to remember the codes. The codes are explained in Table 4. |
Verbose RCB | A long but clear sequence of strings, delimited by underscores, for indicating a component’s build characteristics. |
Table 4 lists the codes used in the RCB convention.
Table 4 – Codes used in the abbreviated RCB build tag convention
Code | Meaning |
s
no code | Using STLPort on Solaris platforms
Using the compiler’s native standard library |
m
no code | Multithreaded build
Single-threaded build |
s
no code | Static binding
Dynamic binding (also called shared or DLL) |
d
no code | Debugging build
Release build |
Note that there is some ambiguity due to the use of ‘s’ to denote either static builds or the use of STLPort on Solaris. However, in practice the chance for confusion is minimal. Solaris is the only platform where the ambiguity might occur, and even there the library extension should disambiguate whether a lone ‘s’ in the library name stands for a static build (.a extension) or the use of STLPort (.so extension).
3.5.13.2 Build Tags
Table 5 summarizes the build tags created by the different conventions.
Table 5 – Summary of build tags
Build Options | Build Tags |
Dynamic | Threads | Debug | RCB | Verbose RCB | SPM |
N | N | N | s | _NativeStdLib
_NoThrLib_Static_Release | 8s |
Y | N | N | no tag | _NativeStdLib
_NoThrLib_Dynamic_Release | 8d |
N | N | Y | sd | _NativeStdLib
_NoThrLib_Static_Debug | 11s |
Y | N | Y | d | _NativeStdLib
_NoThrLib_Dynamic_Debug | 11d |
N | Y | N | ms | _NativeStdLib
_Win32ThrLib_Static_Release | 12s |
Y | Y | N | m | _NativeStdLib
_Win32ThrLib_Dynamic_Release | 12d |
N | Y | Y | msd | _NativeStdLib
_Win32ThrLib_Static_Debug | 15s |
Y | Y | Y | md | _NativeStdLib
_Win32ThrLib_Dynamic_Debug | 15d |
3.5.14 Select Clean Options
Clean options cause particular items, such as logs and object files, to be removed from the buildspace. You can specify either prebuild clean options, postbuild clean options, or both.
3.5.14.1 Prebuild Clean Optons
The prebuild clean options are:
none Do not remove anything.
all but ch13n results, makefile Remove all except makefiles and the compiler environment characterization.
all but ch13n results Remove all except the compiler environment characterization.
all (default) Remove everything; compiler environment characterization must be rerun.
3.5.14.2 Postbuild Clean Options
The postbuild options available are:
none (default) Do not remove anything.
objects Remove only the object files.
objects, executables Remove object files and executables, such as example programs, created by the build.
full clean for deploy Remove any files not needed for deployment of the built components and executables.
The “full clean for deploy” option removes everything except the compiled libraries and their header files. All source code, makefiles, logs, and other nonessential files are deleted. Before you can rebuild any of the components, you must reload them from the CD.
/images/Select-Buildspec.png)
/images/Select-buildspace.png)
/images/Select-Components.png)
/images/dependency_checking.png)
/images/buildaction.png)
/images/Select-OS.png)
/images/Select-Compiler.png)
/images/Select-bitwidth.png)
/images/Select-Linking.png)
/images/Select-Threading.png)
/images/Select-Debugging.png)
/images/Select-Std-Lib.png)
/images/Select-Compiler-Options.png)
/images/Select-Naming-Convention.png)
/images/Pre-Clean-Option.png)
/images/Post-Clean-Options.png)