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