Naming Chromium Builders

[TOC]

TLDR -

Name builders as: target ("-" build_descriptor)* "-" build_type ("-" purpose_descriptor)*

Examples: win64-rel, win64-msvc-rel , linux-chromeos-rel, ios-blink-rel-fyi

Introduction and Requirements

Chromium's continuous integration infrastructure is organized around builders. Builders provide a specification for what code to check out, what targets to build, compile arguments to use, and which tests to run. This document provides a naming convention for builders to improve consistency and clarity.

This document only applies to the chromium/chrome projects and their respective branch projects (including perf, memory, etc.); this does not include other projects like Skia, ChromeOS, V8, etc. or the infra projects.

General notes on naming

• Names should use only lowercase letters. Mixed case, while potentially more readable, complicates accurate transcription and requires more rules.
• Names should not have whitespace in them. Spaces make things potentially easier to read, but complicate accurate transcription.
• Use a dash - to separate parts of a name.
• The more consistency you can have between related things, the better. "Linux Builder" and "Linux Tests" vs. "linux_chromium_rel_ng" is bad; "ios-simulator" for both is better though by itself it isn't sufficiently unique.
• The less redundancy and noise you have, the better. If all of your bots have "chromium" in the name (or "_ng", for that matter), you're better off eliminating it.
• Names should generally follow the pattern of identifiers separated by punctuation. Specifically, we should follow the unicode identifier syntax (probably the lowercase ASCII subset, i.e., the [a-z][a-z0-9_] subset that is a legal identifier in C, Java, C++, Go and Python). We should use the dash character to separate identifiers.

Builders

target ("-" build_descriptor)* "-" build_type ("-" purpose_descriptor)*

This can be broken down as:

• target: What to build/test (platform, arch, test suite).
  • linux, win, mac, ios, android, etc.
• build_descriptor: Modifies how to build or test.
  • Any non obvious build descriptions that you wouldn't assume from the target and bucket.
  • This assumes that you will normally be able to either infer about the host configuration, e.g. we can assume that "android" builds run on a linux x64 host. All exceptions can be handled via build_descriptors.
  • An example would be if a builder within the chrome builder group is doing a build on Chromium.
  • i.e {bucket}/{builder} chrome/linux-chromium-rel - Here we specify chromium build, however, if the bucket were chromium, we would just call the builder linux-rel.
• build_type: rel, dbg, official.
  • Release builder (rel) - Builds binaries with default/base level of compiler optimizations.
  • Debug (dbg) - Used for builders run in debug mode. This is typically done by passing in debug flag parameters, often running slower than release but providing more information.
  • Official - Builds binaries with an extra level of compiler optimizations. More information can be found here.
• purpose_descriptor: How to treat the builder (e.g. fyi, rel-ready).
  • A catch all descriptor that would differentiate a builders purpose from its original base name of {target} + {build_descriptor} + {build_type}
  • We should only use this if there is a substantial change on the builder that does not fall within a target, build_descriptor or build_type.
  • An example of this is making a builder fyi (for your information) thus denoting the builder is probably not a gardened builder that is used to provide data.

Examples:

linux-rel: From a quick glance we can see that descriptors cft and no-external-ip are same builders as linux-rel but one builds and tests use Chrome for Testing and another controls the ability for linux-rel builders to show an external ip address.

• linux-rel: Linux builder with a release build type. The omitted descriptor indicates no special configuration.
• linux-rel-cft: A linux-rel builder with the cft (Chrome for testing) purpose descriptor.
• linux-rel-no-external-ip: A linux-rel builder that runs in an environment with no external IP address. Here we can see that no-external-ip changes the nature of the builder but does not fall under build_type, target, or build_descriptor thus it falls under purpose_descriptor.

linux-chromeos: This grouping is easy to understand. We start off with a Linux builder that runs tests for Chrome on ChromeOs. Note, this differs from real CrOS builds. Information on why it's different here. The use of easy to understand descriptors (code-coverage, annotator, archive) tells us information that help us distinguish linux-chromeos builders at a quick glance.

• linux-chromeos-rel: A builder for the linux-chromeos target with a release build.
• linux-chromeos-dbg: A builder for the linux-chromeos target with a debug build.
• linux-chromeos-annotator-rel: A linux-chromeos release builder with the annotator descriptor.
• linux-chromeos-archive-rel: A linux-chromeos release builder that additionally archives the build.
• linux-chromeos-code-coverage: A linux-chromeos builder for code coverage.

win-rel: Notice strong base name win-rel. It is easy to have a regex find all builders related to win-rel with descriptors being concise and clear.

• win-rel: Windows builder with a release build.
• win-msvc-rel: A win-rel builder that uses the Microsoft Visual C compiler.
• win-msvc-dbg: A Windows builder that uses the Microsoft Visual C compiler and has a debug build type.

Testers

Testers are builders that are triggered by another builder. The tester will run tests that were built by the triggering builder.

builder_name ("-" descriptor)* "-tests"

Examples:

• android-cronet-arm-rel-kitkat-tests
• android-cronet-arm-rel-lollipop-tests
• mac-arm64-rel-tests

If there are multiple testers triggered by a single builder, their names must be distinct, so all but one will require descriptors. In such a case, it is recommended that each tester include at least one descriptor unless it is 2 builders and they are differentiated with a boolean descriptor (e.g. noncq).