README.chromium 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. Name: Google Test: Google's C++ Testing Framework
  2. Short Name: googletest
  3. URL: https://github.com/google/googletest.git
  4. Version: unknown
  5. License: BSD
  6. License File: NOT_SHIPPED
  7. Security critical: no
  8. Google Test is imported as-is, to facilitate version bumping. However, the
  9. file/directory layout of Google Test is not yet considered stable. Therefore,
  10. until Google Test's layout stabilizes, Chromium code MUST NOT depend on it
  11. directly. Instead, Chromium code MUST:
  12. * #include the headers in testing/gtest and testing/gmock
  13. * use //testing/gtest(:gtest_main) and //testing/gmock(:gmock_main) in BUILD.gn
  14. deps
  15. This will allow us to adapt to Google Test changes with minimal disruption.
  16. ## Resources for Rolling Googletest in Chrome
  17. ### What is Googletest
  18. Googletest is an open source C++ testing framework developed by Google and used
  19. by Chromium. See the [User Guide](https://google.github.io/googletest/).
  20. ### Where is Googletest
  21. Googletest is developed in google3 and uses
  22. [copybara](https://github.com/google/copybara) to sync with the public GitHub
  23. repository.
  24. * Development (Googler only): [google3/third\_party/googletest](http://google3/third_party/googletest/)
  25. * GitHub: https://github.com/google/googletest
  26. * Chromium mirror: https://chromium.googlesource.com/external/github.com/google/googletest/
  27. * Locally, [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
  28. is a copy of Googletest which is updated via `gclient sync` according to the
  29. `googletest revision` commit hash in the
  30. [DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS;l=244?q=DEPS%20googletest)
  31. ### Unblocking Googletest Rolls
  32. 1. Roll Googletest to include the breaking change
  33. * Find the hash (on GitHub) of the offending commit
  34. * If the change came from google3, the CL number can be found in the
  35. `PiperOrigin-RevId` footer of Copybara commits
  36. * On a fresh checkout, pull in the relevant change. Either:
  37. * Sync using the DEPS file
  38. ```
  39. roll-dep --roll-to=commitish src/third_party/googletest/src/
  40. gclient sync
  41. ```
  42. * Check out the commit directly
  43. ```
  44. cd third_party/googletest/src
  45. git remote add up https://github.com/google/googletest.git
  46. git checkout commitish
  47. ```
  48. 2. Observe errors
  49. * Ideally, this can be done by building locally.
  50. If the build is successful, this means the change does not affect your OS or
  51. your compiler flags differ from the trybots
  52. * Upload a CL with the added trybots from
  53. [Testing Changes to Chromium in Chromium](#testing-changes-to-chromium-in-chromium)
  54. 3. Make changes
  55. * To Chromium: create a CL including both the roll and other changes
  56. * To Googletest:
  57. * Make changes to [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
  58. and try building locally. If the fix is successful and you’re confident
  59. this change will work across all the trybots, create a PR on GitHub or a
  60. CL to google3 (Googler only) of the changes you made locally to
  61. [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/).
  62. See [Testing Changes to Googletest in Googletest](#testing-changes-to-googletest-in-googletest)
  63. * What if I need to make a change to Googletest, but I’m not confident it
  64. will work with Chromium? Maybe it has to do with a tricky compiler error
  65. that only affects a specific OS. See
  66. [Testing Changes to Googletest in Chromium](#testing-changes-to-googletest-in-chromium)
  67. * Once your Googletest change lands, create a roll which includes both the
  68. offending commit and your change
  69. ### Testing Changes to Chromium in Chromium
  70. Most changes should only require testing via the trybots,
  71. with the following added:
  72. `Cq-Include-Trybots: luci.chromium.try:android_optional_gpu_tests_rel;luci.chromium.try:mac_optional_gpu_tests_rel;luci.chromium.try:linux_chromium_cfi_rel_ng;luci.chrome.try:win-chrome`
  73. ### Testing Changes to Googletest in Googletest
  74. External: Upload a PR with your proposed changes to GitHub.
  75. This will trigger automated testing.
  76. Googlers: See the [Googletest Developer’s Guide](http://go/gunitdev).
  77. ### Testing Changes to Googletest in Chromium
  78. In most cases, testing locally with changes to
  79. [third\_party/googletest/src/](https://source.chromium.org/chromium/chromium/src/+/master:third_party/googletest/src/)
  80. should be enough. But how can you make sure the changes to Googletest actually
  81. work in Chromium? Sometimes it’s not possible to test these changes locally
  82. (different compiler flags, error that only affects a specific OS, etc).
  83. Insert the pwnall repo:
  84. * Development: https://github.com/pwnall/googletest
  85. * Chromium mirror: https://chromium.googlesource.com/external/github.com/pwnall/googletest/
  86. The pwnall repo allows you to make speculative changes to Googletest and run
  87. them against the Chromium trybots. The flow is as follows:
  88. * Create a local remote to the pwnall repo (alternatively, clone it elsewhere):
  89. ```
  90. cd third_party/googletest/src
  91. git remote
  92. git remote add up https://github.com/google/googletest.git
  93. git remote add pwnall git@github.com:pwnall/googletest.git
  94. ```
  95. * Sync the pwnall repo:
  96. ```
  97. git checkout master
  98. git pull up master
  99. git push pwnall master
  100. ```
  101. * Make changes on a new branch
  102. * `git push pwnall branch-name`
  103. * Update the `googletest revision` in the
  104. [DEPS file](https://source.chromium.org/chromium/chromium/src/+/master:DEPS)
  105. with the commit hash and `/external/github.com/google/googletest.git` to
  106. `/external/github.com/pwnall/googletest.git`
  107. * Upload the CL to run the change against the Chromium trybots
  108. ### Common Problems
  109. * Differences in C++ version and clang compiler flags between Chromium and Googletest
  110. * Chromium is on C++14, though its dependencies,
  111. which may use Googletest, may be further behind
  112. * Look for NACL in build errors. You may need to update your GN args with
  113. `enable_nacl=true` to reproduce these errors locally
  114. * [A Googletest interface is changed](https://github.com/google/googletest/pull/2718/)
  115. * Rolling past the commit will fail, since Chromium still uses the old interface
  116. * Roll past the affecting commit and update uses in Chromium [in one CL](https://crrev.com/c/2709263)
  117. * [A Googletest header is removed](https://github.com/google/googletest/commit/df6b75949b1efab7606ba60c0f0a0125ac95c5af)
  118. * Rolling past the commit will fail, since Chromium still expects the header to exist
  119. * Roll past the affecting commit and updates uses in Chromium [in one CL](https://crrev.com/c/2713029)
  120. * [A new Googletest feature](https://github.com/google/googletest/commit/ec94d9f24c92a5090fda5567156d6dde99cdbf31)
  121. requires [updating tests in Chromium](https://crbug.com/1163396#c8)
  122. ### Other Resources
  123. * [AutoRoller](https://autoroll.skia.org/r/googletest-chromium-autoroll) and
  124. accompanying [configuration file](https://skia.googlesource.com/skia-autoroll-internal-config.git/+/main/skia-public/googletest-chromium.cfg)
  125. * [Bug tracking substantial roll](https://crbug.com/1163396)