Chromium Docs - C++ Version Upgrades (original) (raw)

This describes both “why” and “how” around updating Chrome's C++ version (e.g. “C++17”) to something newer.

Goals

• Minimize toolchain support concerns in Chromium.
  Example: A new feature is known to have edge-case bugs, which developers must be told to avoid.
• Minimize toolchain support concerns in subprojects.
  Example: Code in //base would benefit from some new feature, but is also built (in Cronet) by a toolchain that doesn't support that feature.
• Avoid library incompatibilities.
  Example: A new version of protobuf requires a new C++ version, which Chromium doesn't yet use.
• Benefit from language/library improvements, subject to cost/benefit tests.
  Example: Features like C++11‘s std::move or C++20’s Concepts affect large amounts of code and can be requirements for other features.
• Maintain Chromium's history of being a modern, well-maintained project where engineers feel they have access to the tools they need.
  Example: Abseil supports C++ versions for approximately 10 years, but being limited to ten-year-old standards is too limiting in Chromium.

Non-Goals

• Use new C++ features as quickly as possible.
  • Example: C++23 “deducing this” could be used to simplify some CRTP instances in Chromium, but on its own likely doesn't provide sufficient maintenance benefit to prioritize a rapid version update.
• Precisely match Google's internal C++ version and timelines.
  • Example: Google went directly from C++11 to C++17, while Chromium spent some time on C++14.

Current Strategy

Chrome ATLs are responsible for ensuring “important but not urgent” changes like this are prioritized and staffed appropriately. Their goal will be to upgrade Chrome‘s C++ version about 3 years after the date of the standard (e.g. for “C++35” we’d aim for ~2038).

This amount of lag time is approximately what happened for C++11-20 and is usually a good balance of tradeoffs. Earlier is possible for compelling features, but reducing the delay under two years is usually intractable for toolchain reasons. A bit later might be OK, but since a version update requires several months, it‘s best not to wait until there’s an urgent need.

Playbook

Version updates generally require one engineer, and take between a few weeks and a few months of full-time work (depending on what‘s changed in the standard), along with several months of coordination, rollout, and testing that doesn’t require significant engineering time.

1. Reach out to ATLs to validate proposed timeframes and check for any new external dependencies not listed here.
2. Reach out to other affected projects to alert them and verify they're prepared to upgrade. The two main projects to coordinate with are:
   1. The libchrome team in CrOS, since once Chromium begins using new-version features, it will force libchrome to be built with the new version or else break rolls. In the C++20 timeframe, lokerik@ was a good initial contact.
   2. The Cronet team on the Android side, since they build some Chrome code using a different toolchain and library version. There is a Chromium waterfall bot validating this configuration, so breakage should be visible. In the C++20 timeframe, sporeba@ was a good initial contact.
3. Locally edit //build/config/compiler/BUILD.gn; update flags that reference the current C++ version to refer to the next version.
4. Build locally, fixing compile failures.
   • Fixes in Chromium must compile in both the current and new C++ version.
   • Likely, there will also be failures in various subprojects; these must be fixed by landing changes upstream and rolling in new versions. There is no single way to do this since subprojects are hosted in a variety of places and pulled in via multiple different methods, but generally it requires testing the fix by locally modifying the in-Chromium copy, then doing a standalone checkout of the subproject elsewhere using the upstream contribution instructions in order to actually send the patch.
   • For Google-owned subprojects, even when there is a GitHub repo that claims to accept external contributions, it is usually a mirror of something internal, and it is faster and more likely successful to contribute changes to that internal source of truth and then have them mirrored to GitHub.
5. Once a full local build succeeds, repeat the process on other platforms. This is easiest from a Linux host since Linux can cross-build most other platforms.
   • Note that ChromeOS builds using a different compiler version than the rest of Chrome, rolled on a much less aggressive schedule, and thus may have bugs or support gaps that don't exist for other platforms. If there are problems, reach out to the CrOS toolchain team; in the C++20 timeframe, gbiv@ was a good initial contact.
6. Once things compile, do try runs and investigate any failures. While it may seem like simply changing the C++ version should not cause runtime failures, it's possible, and said failures are often subtle. For example, during the C++20 update, fixes to make more types aggregates also changed the semantics of one type such that it became eligible for moves in more situations, exposing a latent use-after-move bug that had previously “worked” because the attempted std::move had still resulted in a copy.
7. Add PRESUBMITs to prevent usage of all new language/library features, so none is added during the rollout period below. (Partial lists of new features are available from the individual language version pages linked atop https://en.cppreference.com/w/cpp.)
8. Reach out to Chrome release managers to alert them of plans to begin rolling out a new version, in case it leads to bugs.
9. Reach out to the Chrome infrastructure team about potential compile time and binary size impact; in the C++20 timeframe, estaab@ was a good initial contact. Roll out the new version one platform at a time under their supervision, to ensure it behaves as expected. (This will require temporarily adding more conditional logic to the .gn files.) You can crudely estimate build time impact in advance by timing local builds.
10. Determine a launch date and validate with stakeholders. Send a message to chromium-dev@ announcing the date and giving brief instructions on how to share concerns.
11. Make a list of all new language and library features and bucket as “allowed” (clearly safe for Chromium use), “TBD” (needs more investigation/discussion), and “banned” (clearly inappropriate for Chromium). Send this proposal to cxx@ and discuss until there is consensus on how to proceed. Write a CL that updates //styleguide/c++/c++-features.md and the PRESUBMIT checks to match the proposal (and mark the new version “initially allowed”), get it reviewed, but do not submit it.
12. Write a smoketest CL that uses some new feature in somewhere low-level enough to affect all of Chromium and any subprojects (e.g. something core in //base). Land it and ensure it can successfully roll into all dependencies.
13. On launch day, land the styleguide/presubmit update CL, then announce availability of the new version to chromium-dev@.
14. In the months following the release, work with cxx@ to follow up on TBD features, proposing allowing/banning them as support improves and/or we do further necessary research.