docs/quickstart-bazel.md

   1 # Quickstart: Building with Bazel
   2
   3 This tutorial aims to get you up and running with GoogleTest using the Bazel
   4 build system. If you're using GoogleTest for the first time or need a refresher,
   5 we recommend this tutorial as a starting point.
   6
   7 ## Prerequisites
   8
   9 To complete this tutorial, you'll need:
  10
  11 *   A compatible operating system (e.g. Linux, macOS, Windows).
  12 *   A compatible C++ compiler that supports at least C++14.
  13 *   [Bazel](https://bazel.build/), the preferred build system used by the
  14     GoogleTest team.
  15
  16 See [Supported Platforms](platforms.md) for more information about platforms
  17 compatible with GoogleTest.
  18
  19 If you don't already have Bazel installed, see the
  20 [Bazel installation guide](https://bazel.build/install).
  21
  22 {: .callout .note} Note: The terminal commands in this tutorial show a Unix
  23 shell prompt, but the commands work on the Windows command line as well.
  24
  25 ## Set up a Bazel workspace
  26
  27 A
  28 [Bazel workspace](https://docs.bazel.build/versions/main/build-ref.html#workspace)
  29 is a directory on your filesystem that you use to manage source files for the
  30 software you want to build. Each workspace directory has a text file named
  31 `WORKSPACE` which may be empty, or may contain references to external
  32 dependencies required to build the outputs.
  33
  34 First, create a directory for your workspace:
  35
  36 ```
  37 $ mkdir my_workspace && cd my_workspace
  38 ```
  39
  40 Next, you’ll create the `WORKSPACE` file to specify dependencies. A common and
  41 recommended way to depend on GoogleTest is to use a
  42 [Bazel external dependency](https://docs.bazel.build/versions/main/external.html)
  43 via the
  44 [`http_archive` rule](https://docs.bazel.build/versions/main/repo/http.html#http_archive).
  45 To do this, in the root directory of your workspace (`my_workspace/`), create a
  46 file named `WORKSPACE` with the following contents:
  47
  48 ```
  49 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
  50
  51 http_archive(
  52   name = "com_google_googletest",
  53   urls = ["https://github.com/google/googletest/archive/5ab508a01f9eb089207ee87fd547d290da39d015.zip"],
  54   strip_prefix = "googletest-5ab508a01f9eb089207ee87fd547d290da39d015",
  55 )
  56 ```
  57
  58 The above configuration declares a dependency on GoogleTest which is downloaded
  59 as a ZIP archive from GitHub. In the above example,
  60 `5ab508a01f9eb089207ee87fd547d290da39d015` is the Git commit hash of the
  61 GoogleTest version to use; we recommend updating the hash often to point to the
  62 latest version. Use a recent hash on the `main` branch.
  63
  64 Now you're ready to build C++ code that uses GoogleTest.
  65
  66 ## Create and run a binary
  67
  68 With your Bazel workspace set up, you can now use GoogleTest code within your
  69 own project.
  70
  71 As an example, create a file named `hello_test.cc` in your `my_workspace`
  72 directory with the following contents:
  73
  74 ```cpp
  75 #include <gtest/gtest.h>
  76
  77 // Demonstrate some basic assertions.
  78 TEST(HelloTest, BasicAssertions) {
  79   // Expect two strings not to be equal.
  80   EXPECT_STRNE("hello", "world");
  81   // Expect equality.
  82   EXPECT_EQ(7 * 6, 42);
  83 }
  84 ```
  85
  86 GoogleTest provides [assertions](primer.md#assertions) that you use to test the
  87 behavior of your code. The above sample includes the main GoogleTest header file
  88 and demonstrates some basic assertions.
  89
  90 To build the code, create a file named `BUILD` in the same directory with the
  91 following contents:
  92
  93 ```
  94 cc_test(
  95   name = "hello_test",
  96   size = "small",
  97   srcs = ["hello_test.cc"],
  98   deps = ["@com_google_googletest//:gtest_main"],
  99 )
 100 ```
 101
 102 This `cc_test` rule declares the C++ test binary you want to build, and links to
 103 GoogleTest (`//:gtest_main`) using the prefix you specified in the `WORKSPACE`
 104 file (`@com_google_googletest`). For more information about Bazel `BUILD` files,
 105 see the
 106 [Bazel C++ Tutorial](https://docs.bazel.build/versions/main/tutorial/cpp.html).
 107
 108 {: .callout .note}
 109 NOTE: In the example below, we assume Clang or GCC and set `--cxxopt=-std=c++14`
 110 to ensure that GoogleTest is compiled as C++14 instead of the compiler's default
 111 setting (which could be C++11). For MSVC, the equivalent would be
 112 `--cxxopt=/std:c++14`. See [Supported Platforms](platforms.md) for more details
 113 on supported language versions.
 114
 115 Now you can build and run your test:
 116
 117 <pre>
 118 <strong>my_workspace$ bazel test --cxxopt=-std=c++14 --test_output=all //:hello_test</strong>
 119 INFO: Analyzed target //:hello_test (26 packages loaded, 362 targets configured).
 120 INFO: Found 1 test target...
 121 INFO: From Testing //:hello_test:
 122 ==================== Test output for //:hello_test:
 123 Running main() from gmock_main.cc
 124 [==========] Running 1 test from 1 test suite.
 125 [----------] Global test environment set-up.
 126 [----------] 1 test from HelloTest
 127 [ RUN      ] HelloTest.BasicAssertions
 128 [       OK ] HelloTest.BasicAssertions (0 ms)
 129 [----------] 1 test from HelloTest (0 ms total)
 130
 131 [----------] Global test environment tear-down
 132 [==========] 1 test from 1 test suite ran. (0 ms total)
 133 [  PASSED  ] 1 test.
 134 ================================================================================
 135 Target //:hello_test up-to-date:
 136   bazel-bin/hello_test
 137 INFO: Elapsed time: 4.190s, Critical Path: 3.05s
 138 INFO: 27 processes: 8 internal, 19 linux-sandbox.
 139 INFO: Build completed successfully, 27 total actions
 140 //:hello_test                                                     PASSED in 0.1s
 141
 142 INFO: Build completed successfully, 27 total actions
 143 </pre>
 144
 145 Congratulations! You've successfully built and run a test binary using
 146 GoogleTest.
 147
 148 ## Next steps
 149
 150 *   [Check out the Primer](primer.md) to start learning how to write simple
 151     tests.
 152 *   [See the code samples](samples.md) for more examples showing how to use a
 153     variety of GoogleTest features.