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++14.
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://bazel.build/install).
21
22{: .callout .note} Note: The terminal commands in this tutorial show a Unix
23shell prompt, but the commands work on the Windows command line as well.
24
25## Set up a Bazel workspace
26
27A
28[Bazel workspace](https://docs.bazel.build/versions/main/build-ref.html#workspace)
29is a directory on your filesystem that you use to manage source files for the
30software you want to build. Each workspace directory has a text file named
31`WORKSPACE` which may be empty, or may contain references to external
32dependencies required to build the outputs.
33
34First, create a directory for your workspace:
35
36```
37$ mkdir my_workspace && cd my_workspace
38```
39
40Next, you’ll create the `WORKSPACE` file to specify dependencies. A common and
41recommended way to depend on GoogleTest is to use a
42[Bazel external dependency](https://docs.bazel.build/versions/main/external.html)
43via the
44[`http_archive` rule](https://docs.bazel.build/versions/main/repo/http.html#http_archive).
45To do this, in the root directory of your workspace (`my_workspace/`), create a
46file named `WORKSPACE` with the following contents:
47
48```
49load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
50
51http_archive(
52  name = "com_google_googletest",
53  urls = ["https://github.com/google/googletest/archive/5ab508a01f9eb089207ee87fd547d290da39d015.zip"],
54  strip_prefix = "googletest-5ab508a01f9eb089207ee87fd547d290da39d015",
55)
56```
57
58The above configuration declares a dependency on GoogleTest which is downloaded
59as a ZIP archive from GitHub. In the above example,
60`5ab508a01f9eb089207ee87fd547d290da39d015` is the Git commit hash of the
61GoogleTest version to use; we recommend updating the hash often to point to the
62latest version. Use a recent hash on the `main` branch.
63
64Now you're ready to build C++ code that uses GoogleTest.
65
66## Create and run a binary
67
68With your Bazel workspace set up, you can now use GoogleTest code within your
69own project.
70
71As an example, create a file named `hello_test.cc` in your `my_workspace`
72directory with the following contents:
73
74```cpp
75#include <gtest/gtest.h>
76
77// Demonstrate some basic assertions.
78TEST(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
86GoogleTest provides [assertions](primer.md#assertions) that you use to test the
87behavior of your code. The above sample includes the main GoogleTest header file
88and demonstrates some basic assertions.
89
90To build the code, create a file named `BUILD` in the same directory with the
91following contents:
92
93```
94cc_test(
95  name = "hello_test",
96  size = "small",
97  srcs = ["hello_test.cc"],
98  deps = ["@com_google_googletest//:gtest_main"],
99)
100```
101
102This `cc_test` rule declares the C++ test binary you want to build, and links to
103GoogleTest (`//:gtest_main`) using the prefix you specified in the `WORKSPACE`
104file (`@com_google_googletest`). For more information about Bazel `BUILD` files,
105see the
106[Bazel C++ Tutorial](https://docs.bazel.build/versions/main/tutorial/cpp.html).
107
108{: .callout .note}
109NOTE: In the example below, we assume Clang or GCC and set `--cxxopt=-std=c++14`
110to ensure that GoogleTest is compiled as C++14 instead of the compiler's default
111setting (which could be C++11). For MSVC, the equivalent would be
112`--cxxopt=/std:c++14`. See [Supported Platforms](platforms.md) for more details
113on supported language versions.
114
115Now 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>
119INFO: Analyzed target //:hello_test (26 packages loaded, 362 targets configured).
120INFO: Found 1 test target...
121INFO: From Testing //:hello_test:
122==================== Test output for //:hello_test:
123Running 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================================================================================
135Target //:hello_test up-to-date:
136  bazel-bin/hello_test
137INFO: Elapsed time: 4.190s, Critical Path: 3.05s
138INFO: 27 processes: 8 internal, 19 linux-sandbox.
139INFO: Build completed successfully, 27 total actions
140//:hello_test                                                     PASSED in 0.1s
141
142INFO: Build completed successfully, 27 total actions
143</pre>
144
145Congratulations! You've successfully built and run a test binary using
146GoogleTest.
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.
154