Creating Buildspecs

Buildspecs are the heart of the build process. A buildspec contains details regarding desired components, the compiler environment, and the location where built components should be placed.

To complete a buildspec, you must

This screen allows you to choose whether to create or edit a buildspec file.

Three options are available:

Reuse a previous buildspec. For more information on this option, see “Common Buildspec Mistakes.”

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 jump directly to the build queue screen.

This screen allows you to indicate the location of the installed SourcePro C++ components that you want the buildspec to use. It also allows you to specify where you want built components to be placed after a buildspec is executed.

The options on this screen are:

This path tells RCB where to get the source files required for the build. The build results are placed in this same location unless you click Export the build. This field must contain a valid path.

Indicates that you want to store build results in a different directory than specified in Local Buildspace. This checkbox must be selected to make the Export buildspace and Copy these files fields become active.

The path entered for this field indicates where build results will be placed. Use this field only if you want build results to be placed in a directory different than indicated in the Local buildspace field.

Specifies what type of data should be copied into the export buildspace along with the build results. Choosing Headers results in just the header files being copied. Choosing Headers and Source results in both header and source files being copied to the export directory.

If an existing location is the export buildspace and it already contains Rogue Wave source code, Headers and Source is selected automatically. This prevents buildspace cross-contamination where the source code files stored in the buildspace are different than those used to create the built components that also reside in the buildspace.

NOTE >> On UNIX, note that RCB does not support symbolic links. For this reason, buildspace specifications must point to actual directories, not to symbolic links.

For a detailed explanation of this screen, see “Select Buildspace”

This screen allows you to select components. Components are products, modules, and examples made available with the installation of each SourcePro C++ product. Placing a check mark beside a component indicates a selection.

To select components, you have two choices:

• Select individual components within a set. Expanding the component’s tree structure allows you to exercise complete control over the component selection process. This allows you to fine-tune the buildspec that you are creating.

• Select a high‑level checkbox. Selecting an entire product or module indicates that you want to select all items lower in the tree.

RCB enforces component dependencies. In other words, RCB ensures that the buildspec you create has all the components it requires to function properly. If a required component is missing, RCB displays a warning that lists the component and offers two choices: Yes and Cancel.

Selecting Yes causes RCB to automatically select the required products and then continue with the buildspec creation process. Selecting Cancel returns you to the Component Selection screen.

For a detailed explanation, see “Select Components”

After selecting components, the build options screen launches where you must answer a sequence of questions regarding your buildspec. The question sequence varies depending on the components selected and answers provided.

The screen is divided into three panes. In this example, they are called: Left Pane, Right Pane, and Navigation Pane.

This is known as the question list. It indicates your position in the buildspec creation process. The text on the left side represents the questions that RCB asks during the creation process.

Some questions do not appear until certain circumstances are met and RCB is forced to collect more information, as described in the section “Unavailable (Greyed-out) Answers.”).

The text on the right side of the pane represents the answers that you have given so far. These fields remain blank until you have completed them.

You can jump to any location in the question list by clicking that question. Forward jumps cause default values to be used for questions skipped by the jump. Jumping backwards does not affect the answers you have given. Providing a new answer to a previously answered question may affect questions later in the sequence.

Selecting the Done editing options button located just below the question list causes RCB to jump to the Submit Buildspec screen (see “Submit Buildspec to the Build Queue”).

In this pane, RCB poses questions during the buildspec creation process. Questions include pulldown menus for selecting values and/or text boxes for entering data.

For instance, if the question list indicates that you are currently selecting a build action, the Build Action question displays on this pane.

This pane allows you to control your movement through the buildspec creation process. Buttons available are: Help, Options, Previous, Next, and Cancel.

Options launches the Options Dialog window. For more information on available options, see the section “Options Dialog”.

Cancel cancels the buildspec creation process and returns you to the Select Buildspec question.

Once you answer all the questions necessary for the creation of a buildspec, you must submit the buildspec to a build queue. Submitting a buildspec to the build queue saves the buildspec to a file. It also causes RCB to append the file to a queue in the GUI. Once the file is appended to the queue, you can execute the buildspec from within the GUI, or quit the GUI and execute it via the command line.

This screen summarizes the buildspec and allows you to review your work before submitting it to the build queue. The summary screen will look slightly different, depending on whether you have created a new buildspec or edited an existing one. If you modified an existing buildspec, a list of changes is included with the summary.

Once you are satisfied with your buildspec, select the Done editing buildspec button. This action

• May cause a Platform Information Exchange dialog to pop up, as shown in “Answer Platform Information Exchange Request (optional)”.

• May cause a Platform Information Exchange dialog to pop up, as shown in the topic “Platform Information Exchange”.

• Launches the Build queue screen, as shown in “Consider Build Queue Options”.

If the Platform Information Exchange is installed and your consent setting is set to Maybe, ask me to decide that for each build, RCB asks if it can forward information about your buildspec to Rogue Wave.

The Configuration Parameter and Value sections display the information to be sent. Click Tell me more... for more information about each parameter.

Click Continue to proceed to the Build Queue screen. You must provide an answer to the question before you can continue. The available options are:

This request occurs every time a buildspec is created until you change your consent setting to something other than Maybe, ask me to decide that for each build.

This screen displays buildspecs waiting in the queue. You can continue to manipulate buildspecs on this screen. The screen is divided into two sections: buildspecs that are already part of the Build Queue (top), and Existing buildspec files that are not part of the build queue (bottom).

The box at the top of the screen lists all the buildspecs that are waiting in the build queue. Many options are available when dealing with a buildspec selected in the build queue:

Allows you to see a listing of all the selected buildspec’s build option values.

Allows you to remove a buildspec from the build queue. This will not delete the buildspec file.

Allows you to add the buildspec currently selected in the Existing buildspec files drop-down list to the build queue.

This section of the screen allows you to manipulate buildspecs that are not currently visible in the build queue.

This drop-down list allows you to select a buildspec that RCB knows about, but does not have listed in the build queue.

Allows you to see a listing of all the build option values associated with the buildspec displayed in the Existing buildspec file drop down list.

The navigation buttons allow you to complete the buildspec creation process. Available options are

Returns you to the beginning of the buildspec creation process. You may then choose to create another buildspec, modify a currently existing buildspec, or return to this screen.

Runs all the buildspecs listed in the build queue. Results will be placed in each build’s designated buildspace.

If you choose to execute a buildspec via the GUI, the Build Output screen appears. The Build Output screen displays the execution of a buildspec. At the beginning of a build, the RCB build manager runs a series of characterization tests to determine the capabilities of your compiler environment. It uses the resulting data to further fine-tune the buildspec to your system’s requirements.

For more information on executing buildspecs, see “Executing Buildspecs”.

As RCB builds components, it uses one of three codes to indicate the result of each attempt. The code used appears on both the left and right of the component name.

Information regarding build attempts appears in two places; the first time RCB attempts to compile the component, and the Results section.

The Results section summarizes how each build attempt fared. If a build failed, scroll up the Build Output screen to find the line where RCB attempted to compile the component. The explanation for the failure is located on that line.

RCB uses three codes to help you differentiate the components that you build:

This indicates an error condition. RCB experienced problems while building the component. Go to the line where RCB attempted to build the component to view the error notice.

This is an internal condition that is used for testing purposes. This does not affect your builds.

Click Browse Output to view the Build Report generated during the execution of the buildspec. For more information, see “Build Report”.

Deselect Auto-scrolling enabled to prevent RCB from continually displaying the latest action taken while executing the build.

If you allow the Platform Information Exchange to submit buildspec information to Rogue Wave, one of two messages appears at the bottom of the Build Output screen:

The build information contained in the executed buildspec has been relayed to Rogue Wave via HTTP.

• The build data has been saved in the following file: buildspace\admin\persisteddata\username.dcm

The build information contained in the executed buildspec has been stored in the file username.dcm. Forward the file to Rogue Wave via email, mail or fax.