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/) 7.0 or higher, the preferred build system used 14 by the 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`MODULE.bazel` 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 `MODULE.bazel` file to specify dependencies. As of Bazel 417.0, the recommended way to consume GoogleTest is through the 42[Bazel Central Registry](https://registry.bazel.build/modules/googletest). To do 43this, create a `MODULE.bazel` file in the root directory of your Bazel workspace 44with the following content: 45 46``` 47# MODULE.bazel 48 49# Choose the most recent version available at 50# https://registry.bazel.build/modules/googletest 51bazel_dep(name = "googletest", version = "1.15.2") 52``` 53 54Now you're ready to build C++ code that uses GoogleTest. 55 56## Create and run a binary 57 58With your Bazel workspace set up, you can now use GoogleTest code within your 59own project. 60 61As an example, create a file named `hello_test.cc` in your `my_workspace` 62directory with the following contents: 63 64```cpp 65#include <gtest/gtest.h> 66 67// Demonstrate some basic assertions. 68TEST(HelloTest, BasicAssertions) { 69 // Expect two strings not to be equal. 70 EXPECT_STRNE("hello", "world"); 71 // Expect equality. 72 EXPECT_EQ(7 * 6, 42); 73} 74``` 75 76GoogleTest provides [assertions](primer.md#assertions) that you use to test the 77behavior of your code. The above sample includes the main GoogleTest header file 78and demonstrates some basic assertions. 79 80To build the code, create a file named `BUILD` in the same directory with the 81following contents: 82 83``` 84cc_test( 85 name = "hello_test", 86 size = "small", 87 srcs = ["hello_test.cc"], 88 deps = [ 89 "@googletest//:gtest", 90 "@googletest//:gtest_main", 91 ], 92) 93``` 94 95This `cc_test` rule declares the C++ test binary you want to build, and links to 96the GoogleTest library (`@googletest//:gtest"`) and the GoogleTest `main()` 97function (`@googletest//:gtest_main`). For more information about Bazel `BUILD` 98files, see the 99[Bazel C++ Tutorial](https://docs.bazel.build/versions/main/tutorial/cpp.html). 100 101{: .callout .note} 102NOTE: In the example below, we assume Clang or GCC and set `--cxxopt=-std=c++14` 103to ensure that GoogleTest is compiled as C++14 instead of the compiler's default 104setting (which could be C++11). For MSVC, the equivalent would be 105`--cxxopt=/std:c++14`. See [Supported Platforms](platforms.md) for more details 106on supported language versions. 107 108Now you can build and run your test: 109 110<pre> 111<strong>$ bazel test --cxxopt=-std=c++14 --test_output=all //:hello_test</strong> 112INFO: Analyzed target //:hello_test (26 packages loaded, 362 targets configured). 113INFO: Found 1 test target... 114INFO: From Testing //:hello_test: 115==================== Test output for //:hello_test: 116Running main() from gmock_main.cc 117[==========] Running 1 test from 1 test suite. 118[----------] Global test environment set-up. 119[----------] 1 test from HelloTest 120[ RUN ] HelloTest.BasicAssertions 121[ OK ] HelloTest.BasicAssertions (0 ms) 122[----------] 1 test from HelloTest (0 ms total) 123 124[----------] Global test environment tear-down 125[==========] 1 test from 1 test suite ran. (0 ms total) 126[ PASSED ] 1 test. 127================================================================================ 128Target //:hello_test up-to-date: 129 bazel-bin/hello_test 130INFO: Elapsed time: 4.190s, Critical Path: 3.05s 131INFO: 27 processes: 8 internal, 19 linux-sandbox. 132INFO: Build completed successfully, 27 total actions 133//:hello_test PASSED in 0.1s 134 135INFO: Build completed successfully, 27 total actions 136</pre> 137 138Congratulations! You've successfully built and run a test binary using 139GoogleTest. 140 141## Next steps 142 143* [Check out the Primer](primer.md) to start learning how to write simple 144 tests. 145* [See the code samples](samples.md) for more examples showing how to use a 146 variety of GoogleTest features. 147