Fix build error at cmake 3.21.3
[platform/upstream/gtest.git] / 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++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/master/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/master/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/master/external.html)
44 via the
45 [`http_archive` rule](https://docs.bazel.build/versions/master/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 Bazel also needs a dependency on the
66 [`rules_cc` repository](https://github.com/bazelbuild/rules_cc) to build C++
67 code, so add the following to the `WORKSPACE` file:
68
69 ```
70 http_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
77 Now you're ready to build C++ code that uses GoogleTest.
78
79 ## Create and run a binary
80
81 With your Bazel workspace set up, you can now use GoogleTest code within your
82 own project.
83
84 As an example, create a file named `hello_test.cc` in your `my_workspace`
85 directory with the following contents:
86
87 ```cpp
88 #include <gtest/gtest.h>
89
90 // Demonstrate some basic assertions.
91 TEST(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
99 GoogleTest provides [assertions](primer.md#assertions) that you use to test the
100 behavior of your code. The above sample includes the main GoogleTest header file
101 and demonstrates some basic assertions.
102
103 To build the code, create a file named `BUILD` in the same directory with the
104 following contents:
105
106 ```
107 load("@rules_cc//cc:defs.bzl", "cc_test")
108
109 cc_test(
110   name = "hello_test",
111   size = "small",
112   srcs = ["hello_test.cc"],
113   deps = ["@com_google_googletest//:gtest_main"],
114 )
115 ```
116
117 This `cc_test` rule declares the C++ test binary you want to build, and links to
118 GoogleTest (`//:gtest_main`) using the prefix you specified in the `WORKSPACE`
119 file (`@com_google_googletest`). For more information about Bazel `BUILD` files,
120 see the
121 [Bazel C++ Tutorial](https://docs.bazel.build/versions/master/tutorial/cpp.html).
122
123 Now you can build and run your test:
124
125 <pre>
126 <strong>my_workspace$ bazel test --test_output=all //:hello_test</strong>
127 INFO: Analyzed target //:hello_test (26 packages loaded, 362 targets configured).
128 INFO: Found 1 test target...
129 INFO: From Testing //:hello_test:
130 ==================== Test output for //:hello_test:
131 Running 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 ================================================================================
143 Target //:hello_test up-to-date:
144   bazel-bin/hello_test
145 INFO: Elapsed time: 4.190s, Critical Path: 3.05s
146 INFO: 27 processes: 8 internal, 19 linux-sandbox.
147 INFO: Build completed successfully, 27 total actions
148 //:hello_test                                                     PASSED in 0.1s
149
150 INFO: Build completed successfully, 27 total actions
151 </pre>
152
153 Congratulations! You've successfully built and run a test binary using
154 GoogleTest.
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.