Using Build Classes

5 minute read

CloudBees Accelerator provides features to organize builds in even the most complex environments. You do not need to create a build class—by default, a simple organizational structure is set up for you. But, if you have diverse product lines, or multiple product releases, you should set up and use build classes.

A build class is a flexible, user-defined classification for a designated group of builds. Using build classes is optional, but if you do not assign a build class, the Cluster Manager assigns the build to a default build class. Build classes help you organize the build management process.

Depending on your company requirements, you might use build classes to organize build groups by version or release, product type, development stage, or platform. You can decide how to use build classes to organize your builds into sets.

Classes have default priorities and boost values. Boost values have a range of -10 to +10 (default 0), where a higher value means that builds in that class can use available agents ahead of builds with the same priority but less boost.

Tag Definitions

Each build in a class is identified by a unique string called a tag . The build tag definition is a template that expands when a new build starts. The tag is user-defined and generally consists of a generic build name appended with build-specific data constructed from the following variables:

Tag Description

GC

Globally unique number (Global Counter)

LC

Number unique to the build class (Local Counter; the build serial number within the class)

BUILD_CLASS

User-defined build class name

BUILD_CLASS_ID

System-generated number that the Cluster Manager uses to identify each class

USER_NAME

Name of the user who invoked eMake

MACHINE_NAME

Name of the machine where eMake was invoked

USER_BUILD_LABEL

Label specified at the eMake command line. For example, --emake-build-label=my_build

BUILD_OS_ID

Operating system ID under which the build was invoked. ( 0 = undefined, 1 = Windows, and 3 = Linux)

DATE

Build start date and time using variables Y, y, m d, H, M, S. Ffor example, 2005-01-18 10:14:32 is 20050118101432

.Y

Year at build start time ( YYYY )

y

Year at build start time ( YY )

m

Sequential month number at build start time ( 1-12 )

d

Sequential day of month at build start time ( 1-31 )

H

Hour of the day at build start time ( 0-23 )

M

Minutes at build start time ( 0-59 )

S

Seconds at build start time ( 0-60 )

a

Abbreviated day of week at build start time ( WED )

A

Full name of the day of week at build start time (such as Wednesday )

b

Abbreviated month name at build start time (such as AUG )

B

Full month name at build start time (such as August )

c

Build start date and time using the variables A, B, d, H, M, S, Y. For example, 2005-01-18 10:14:32 is 18/01/05 10:14:32.

Together, the build name and variables are referred to as the tag definition . Variable names are case-sensitive.

For example, the tag definition %BUILD_CLASS%%LC%%DATE% for a build class named QA_BUILD creates the following build tag:

QA_BUILD_1234_20060123185958

When assigning build class tag definitions, choose from the list of tag variables above.

Build Class Examples

Suppose your company has two major product lines: SuperSoftware and MegaSoftware. SuperSoftware runs on Windows and Linux platforms. MegaSoftware runs on Windows only. You could begin by setting up three classes that include the product name, the platform, and the current version number for each product:

  • You could name the first class SuperSoftware_Win_v.2.1. The tag definition for this class would be:

%BUILD_CLASS%_%LC%_%a%_%b%_%d%_%H%_%M%_%S%

The result would be a series of builds each named, or tagged , with the product name, the platform, the version number, a serial number (unique to the class), and the date for each build. For example:

SuperSoftware_Win_v.2.1_12345_WED_AUG_22_14_37_12
  • The second class could be named SuperSoftware_Lin_v.1.7. The tag definition can be the same as in our first example, because it would be distinguished by the second build class name. Build tags in the second class would look like:

SuperSoftware_Lin_v.1.7_12356_WED_AUG_23_11_14_39
  • The third class could be named MegaSoftware_Win_v.1.3. For this product, the tag definition would be similar to the previous examples but also could include the name of the user who started the build, because the MegaSoftware team is spread over several different locations. For this class, the tag definition might look like:

%BUILD_CLASS%_%LC%_%USER_NAME%_%DATE%
  • As in the first two examples, the result would be a sequentially-numbered series of builds with the product name, platform, version number, name of the user who ran the build, and date of each build assigned through the build class:

MegaSoftware_Win_v.1.3_12356_JSMITH_20050411100838

Additional classes could be created when the development of SuperSoftware or MegaSoftware entered a new phase, such as a new platform release or a new version release. In this way, the builds for each stage of development can be segmented into logical sets for a more manageable and organized workflow.

Creating a New Build Class Using the Cluster Manager

  1. Open a web browser and go to the Cluster Manager host.

  2. Click the Build > Build Classes tab.

    The Build Classes page displays.

  3. Click the New Build Class link.

    A blank class details screen appears.

  4. Click the Show Help link on the right side of the screen to see field descriptions ,and then fill in the fields accordingly.

  5. In the Tag Definition text box, enter the build class tag definition.

To avoid errors, follow standard naming conventions for tag definitions by using numbers, letters, and underscores only without leading or trailing white spaces. Use underscores ( _ ) instead of spaces. Use a percent sign on either side of any variables used. (For example, %DATE% ).

  1. Continue filling in the fields.

    See the online help for more information if needed.

  2. Click OK.

You can add comments to the build class. To do so, click the Build > Build Class tab, then select a build class name. For details about on adding or editing build class comments, adding or editing class properties, or deleting a build class, see the online help.

Using an Existing Build Class

Assign the build’s class name through the --emake-class=<exact build class name> eMake command-line option when the build is invoked. If you do not assign a build class, the Cluster Manager assigns the build to the default class. If the class name typed on the eMake command line does not match a class name already in the Cluster Manager, eMake exits.

Makefile Macros

eMake automatically creates makefile macros ( ECLOUD_BUILD_CLASS and ECLOUD_BUILD_TAG ) from Cluster Manager build class data. These macros can be used to place generated values in your makefiles. For details, see the “ Using eMake Variables ” section.