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