-
Notifications
You must be signed in to change notification settings - Fork 6
/
bazel.html
535 lines (398 loc) · 28.4 KB
/
bazel.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta name="msapplication-config" content="/browserconfig.xml"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta charset="utf-8"/>
<link rel="apple-touch-icon" type="image/png" href="/apple-touch-icon.png"/>
<link rel="manifest" type="application/manifest+json" href="/site.webmanifest"/>
<link rel="mask-icon" type="image/svg+xml" href="/mask-icon.svg" color="#990000"/>
<link rel="shortcut icon" type="image/png" href="/favicon.png"/>
<title>Drake: Bazel build system</title>
<meta
name="description"
content="Drake ("dragon" in Middle English) is a C++ toolbox started by the Robot
Locomotion Group at the MIT Computer Science and Artificial Intelligence
Lab (CSAIL). The development team has now grown significantly, with core
development led by the Toyota Research Institute. It is a collection of
tools for analyzing the dynamics of our robots and building control
systems for them, with a heavy emphasis on optimization-based design/
analysis.
"/>
<!--
The "Work Sans" font is licensed under the SIL Open Font License (OFL). For
more information, see:
- https://fonts.google.com/specimen/Work+Sans?preview.text_type=custom#about
- https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL
-->
<link href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Work+Sans:wght@300;400;600;700;800&display=swap" rel="stylesheet"/>
<link rel="stylesheet" href="/third_party/github-styling/github-markdown.css"/>
<link rel="stylesheet" href="/third_party/dracula/syntax.css"/>
<link rel="stylesheet" href="/third_party/pylons/pylons.css"/>
<link rel="stylesheet" href="/assets/css/main.css"/>
</head>
<body>
<header class="site-header">
<div class="site-header-inner contain">
<a href="/" class="drake-logo">
<img src="/images/drake-logo-white.svg">
</a>
<div class="menu-mobile-toggle">
<span></span>
</div>
<nav class="site-menu">
<ul>
<li class="site-menu-item site-menu-item-main">
<a href="/" class="site-menu-item">Home</a>
</li>
<li class="site-menu-item site-menu-item-main">
<a href="/installation.html" class="site-menu-item">Installation</a>
</li>
<li class="site-menu-item site-menu-item-main">
<a href="/gallery.html" class="site-menu-item">Gallery</a>
</li>
<li class="site-menu-item site-menu-item-main">
API Documentation
<div class="sub">
<a href="/doxygen_cxx/index.html" class="site-menu-item">C++</a>
<a href="/pydrake/index.html" class="site-menu-item">Python</a>
</div>
</li>
<li class="site-menu-item site-menu-item-main">
Resources
<div class="sub">
<a href="/getting_help.html" class="site-menu-item">Getting Help</a>
<a href="https://deepnote.com/workspace/Drake-0b3b2c53-a7ad-441b-80f8-bf8350752305/project/Tutorials-2b4fc509-aef2-417d-a40d-6071dfed9199/%2Findex.ipynb" class="site-menu-item">Tutorials</a>
<a href="/python_bindings.html" class="site-menu-item">Python Bindings</a>
<a href="/developers.html" class="site-menu-item">For Developers</a>
<a href="/credits.html" class="site-menu-item">Credits</a>
</div>
</li>
<li class="search">
<div class="search-icon">
<!-- This is an inline SVG image of a magnifying glass. -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 374.9 374.84">
<path d="M235 270a148.74 148.74 0 1 1 35-35l97.74 97.74a24.37 24.37 0 0 1 0 34.58l-.4.4a24.47 24.47 0 0 1-34.58 0L235 270Zm-86.22-7.47A113.75 113.75 0 1 0 35 148.75 113.75 113.75 0 0 0 148.75 262.5Z"/>
</svg>
</div>
<div class="search-bar">
<form id="search_form" action="https://google.com/search" method="get">
<input type="text" name="q" placeholder="Search all of Drake…" />
<input type="hidden" name="q" value="site:drake.mit.edu OR site:underactuated.csail.mit.edu OR site:manipulation.csail.mit.edu" />
</form>
<div class="search-close">
<!-- This is an inline SVG image of an "X". -->
<svg height="20" width="20" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 373.61 373.57">
<path d="M219.71 186.77 366.71 40a23.43 23.43 0 1 0-33.13-33.13l-146.77 147-146.77-147A23.43 23.43 0 0 0 6.9 40l147 146.77-147 146.77a23.43 23.43 0 1 0 33.14 33.13l146.77-147 146.77 147a23.43 23.43 0 1 0 33.13-33.13Z"/>
</svg>
</div>
</div>
<ul id="results-container"></ul>
</li>
<li class="github-link">
<a href="https://github.com/RobotLocomotion/drake" class="site-menu-item">GitHub <img src="/third_party/images/GitHub-Mark-Light-64px.png" /></a>
</li>
</ul>
</nav>
</div>
</header>
<div class="page">
<div class="content">
<div class="drake-page">
<header class="drake-page-header">
<div class="contain">
<h1>Bazel build system</h1>
</div>
</header>
<section class="padding">
<div class="contain">
<article class="markdown-body">
<p>Drake’s primary build system is Bazel. For more information about Bazel, see
<a href="https://bazel.build/">https://bazel.build/</a>.</p>
<p>Drake also offers a CMake build system wrapper that invokes Bazel under the
hood.</p>
<h1 id="bazel-installation">Bazel Installation</h1>
<p>Follow Drake’s
<a href="/from_source.html#mandatory-platform-specific-instructions">platform-specific setup instructions</a>
to install bazelisk at <code class="language-plaintext highlighter-rouge">/usr/bin/bazel</code>, which will then automatically
download the correct version of Bazel necessary for the build.</p>
<h1 id="drake-clone-and-platform-setup">Drake clone and platform setup</h1>
<ul>
<li>Start with a <strong>git clone</strong> of drake, per the <a href="/from_source.html#getting-drake">Getting Drake</a>
instructions.</li>
<li>Continue with the <em>“Mandatory platform-specific instructions”</em> on the same
page.</li>
</ul>
<h1 id="developing-drake-using-bazel">Developing Drake using Bazel</h1>
<p>To build or test Drake, run <strong>bazel build</strong> or <strong>bazel test</strong> with the desired
target label (and optional configuration options if desired). We give some
typical examples below; for more reading about target patterns, see:
<a href="https://docs.bazel.build/versions/main/user-manual.html#target-patterns">https://docs.bazel.build/versions/main/user-manual.html#target-patterns</a>.</p>
<p>On Ubuntu, the default compiler is the first <code class="language-plaintext highlighter-rouge">gcc</code> compiler in the <code class="language-plaintext highlighter-rouge">PATH</code>.
On macOS, the default compiler is the Apple LLVM compiler. To use Clang on
Ubuntu, add <code class="language-plaintext highlighter-rouge">--config=clang</code> after any <strong>bazel build</strong>, <strong>bazel test</strong> or any
other <strong>bazel</strong> commands.</p>
<p>Cheat sheet for operating on the entire project:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd /path/to/drake
bazel build //... # Build the entire project.
bazel test //... # Build and test the entire project.
bazel build --config=clang //... # Build using Clang on Ubuntu.
bazel test --config=clang //... # Build and test using Clang on Ubuntu.
</code></pre></div></div>
<ul>
<li>The “<code class="language-plaintext highlighter-rouge">//</code>” means “starting from the root of the project”.</li>
<li>The “<code class="language-plaintext highlighter-rouge">...</code>” means “everything including the subdirectories’ <code class="language-plaintext highlighter-rouge">BUILD</code> files”.
<ul>
<li>Contrast with, e.g., the “<code class="language-plaintext highlighter-rouge">bazel build common:*</code>” explained below, where
only targets declared <em>directly</em> in <code class="language-plaintext highlighter-rouge">drake/common/BUILD</code> are compiled,
and not the targets in <code class="language-plaintext highlighter-rouge">drake/common/trajectories/BUILD</code>. The “<code class="language-plaintext highlighter-rouge">*</code>”
matches targets in that directory; the “<code class="language-plaintext highlighter-rouge">...</code>” also matches down into
subdirectories.</li>
</ul>
</li>
</ul>
<p>You may use relative pathnames if your shell’s working directory is not at the
project root:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd /path/to/drake/common
bazel build ... # Build everything in common and its child subdirectories.
bazel test ... # Test everything in common and its child subdirectories.
bazel build //... # Build the entire project.
bazel test //... # Build and test the entire project.
</code></pre></div></div>
<ul>
<li>As before, the “<code class="language-plaintext highlighter-rouge">...</code>” above means “everything including subdirectories”.
<ul>
<li>In the first two lines we did not precede “<code class="language-plaintext highlighter-rouge">...</code>” with “<code class="language-plaintext highlighter-rouge">//</code>”, so the
search begins in the current directory (<code class="language-plaintext highlighter-rouge">common</code>) and not from the
<code class="language-plaintext highlighter-rouge">drake</code> root.</li>
<li>In the second two lines we used the “<code class="language-plaintext highlighter-rouge">//</code>” prefix to specify the project
root, so we’re back to operating on the entire project even though
<code class="language-plaintext highlighter-rouge">common</code> is still our shell’s current working directory.</li>
</ul>
</li>
</ul>
<p>Cheat sheet for operating on specific portions of the project:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd /path/to/drake
bazel build common/... # Build everything in common and its child subdirectories.
bazel build common # Build libcommon.
bazel build common:polynomial # Build libpolynomial.
bazel build common:* # Build everything in common but NOT its children.
bazel test common:polynomial_test # Run one test.
bazel test -c dbg common:polynomial_test # Run one test in debug mode.
bazel test --config=memcheck common:polynomial_test # Run one test under memcheck (valgrind).
bazel test --config=fastmemcheck common:* # Run common's tests under memcheck, with minimal recompiling.
bazel test --config=kcov common:polynomial_test # Run one test under kcov (see instructions below).
bazel build -c dbg common:polynomial_test && \
gdb bazel-bin/common/polynomial_test # Run one test under gdb.
bazel test -c dbg --config=clang --config=asan common:polynomial_test # Run one test under AddressSanitizer.
bazel test --config lint //... # Only run style checks; don't build or test anything else.
</code></pre></div></div>
<ul>
<li>The “<code class="language-plaintext highlighter-rouge">:</code>” syntax separates target names from the directory path of the
<code class="language-plaintext highlighter-rouge">BUILD</code> file they appear in. In this case, for example,
<code class="language-plaintext highlighter-rouge">drake/common/BUILD</code> specifies <code class="language-plaintext highlighter-rouge">cc_test(name = "polynomial_test")</code>.</li>
<li>Note that the configuration switches (<code class="language-plaintext highlighter-rouge">-c</code> and <code class="language-plaintext highlighter-rouge">--config</code>) influence the
entire command. For example, running a test in <code class="language-plaintext highlighter-rouge">dbg</code> mode means that its
prerequisite libraries are also compiled and linked in <code class="language-plaintext highlighter-rouge">dbg</code> mode.</li>
<li>For the definitions of the “<code class="language-plaintext highlighter-rouge">--config</code>” options see <code class="language-plaintext highlighter-rouge">drake/tools/bazel.rc</code>.</li>
</ul>
<h2 id="running-with-flags">Running with Flags</h2>
<h3 id="example-programs">Example programs</h3>
<p>In general, to figure out what binary-specific arguments are available, add
“<code class="language-plaintext highlighter-rouge">-- --help</code>” to your <code class="language-plaintext highlighter-rouge">bazel run</code> command. An an example,</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel run //examples/acrobot:run_passive -- --help
</code></pre></div></div>
<p>The bare <code class="language-plaintext highlighter-rouge">--</code> separates Bazel arguments from the program’s arguments.</p>
<h2 id="unit-tests">Unit tests</h2>
<p>For running tests, you may pass custom arguments to the test program via
<a href="https://docs.bazel.build/versions/main/user-manual.html#flag--test_arg">–test_arg</a>.</p>
<p>For a C++ unittest that uses <code class="language-plaintext highlighter-rouge">drake_cc_googletest</code>, for example:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel test multibody/plant:multibody_plant_test --test_output=streamed --nocache_test_results --test_arg=--gtest_filter='*SimpleModelCreation*'
</code></pre></div></div>
<p>For a Python unittest that uses <code class="language-plaintext highlighter-rouge">drake_py_unittest</code>, for example:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel test bindings/pydrake:py/symbolic_test --test_output=streamed --nocache_test_results --test_arg=--trace=user --test_arg=TestSymbolicVariable
</code></pre></div></div>
<h2 id="debugging-on-macos">Debugging on macOS</h2>
<p>On macOS, DWARF debug symbols are emitted to a <code class="language-plaintext highlighter-rouge">.dSYM</code> file. The Bazel
<code class="language-plaintext highlighter-rouge">cc_binary</code> and <code class="language-plaintext highlighter-rouge">cc_test</code> rules do not natively generate or expose this
file, so we have implemented a workaround in Drake, <code class="language-plaintext highlighter-rouge">--config=apple_debug</code>.
This config turns off sandboxing, which allows a <code class="language-plaintext highlighter-rouge">genrule</code> to access the
<code class="language-plaintext highlighter-rouge">.o</code> files and process them into a <code class="language-plaintext highlighter-rouge">.dSYM</code>. Use as follows:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel build --config=apple_debug path/to/my:binary_or_test_dsym
lldb ./bazel-bin/path/to/my/binary_or_test
</code></pre></div></div>
<p>For more information, see <a href="https://github.com/bazelbuild/bazel/issues/2537">https://github.com/bazelbuild/bazel/issues/2537</a>.</p>
<h1 id="updating-build-files">Updating BUILD files</h1>
<p>Please use the “<code class="language-plaintext highlighter-rouge">buildifier</code>” tool to format edits to <code class="language-plaintext highlighter-rouge">BUILD</code> files (in the
same spirit as <code class="language-plaintext highlighter-rouge">clang-format</code> formatting C++ code):</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd /path/to/drake
bazel-bin/tools/lint/buildifier --all # Reformat all Bazel files.
bazel-bin/tools/lint/buildifier common/BUILD # Only reformat one file.
</code></pre></div></div>
<p>In most cases the <code class="language-plaintext highlighter-rouge">bazel-bin/tools/lint/buildifier</code> will already be compiled
by the time you need it. In case it’s absent, you can compile it via:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd /path/to/drake
bazel build //tools/lint:buildifier
</code></pre></div></div>
<h1 id="proprietary-solvers">Proprietary Solvers</h1>
<p>The Drake Bazel build currently supports the following proprietary solvers:</p>
<ul>
<li>Gurobi 10.0</li>
<li>MOSEK<a href="/tm.html">™</a> 10.0</li>
<li>SNOPT 7.4</li>
</ul>
<h2 id="gurobi-100">Gurobi 10.0</h2>
<h3 id="install-on-ubuntu">Install on Ubuntu</h3>
<ol>
<li>Register for an account on <a href="https://www.gurobi.com">https://www.gurobi.com</a>.</li>
<li>Set up your Gurobi license file in accordance with Gurobi documentation.</li>
<li><code class="language-plaintext highlighter-rouge">export GRB_LICENSE_FILE=/path/to/gurobi.lic</code>.</li>
<li>Download <code class="language-plaintext highlighter-rouge">gurobi10.0.2_linux64.tar.gz</code>. You may need to manually edit the URL to get the correct version.</li>
<li>Unzip it. We suggest that you use <code class="language-plaintext highlighter-rouge">/opt/gurobi1002</code> to simplify working with Drake installations.</li>
<li>If you unzipped into a location other than <code class="language-plaintext highlighter-rouge">/opt/gurobi1002</code>, then call <code class="language-plaintext highlighter-rouge">export GUROBI_HOME=GUROBI_UNZIP_PATH/linux64</code> to set the path you used, where in <code class="language-plaintext highlighter-rouge">GUROBI_HOME</code> folder you can find <code class="language-plaintext highlighter-rouge">bin</code> folder.</li>
</ol>
<p>Drake supports any patch version of Gurobi 10.0. At time of writing, the most
recent available version was 10.0.2; if using a newer patch version, the paths
and file names above should be adjusted accordingly.</p>
<h3 id="install-on-macos">Install on macOS</h3>
<ol>
<li>Register for an account on <a href="http://www.gurobi.com">http://www.gurobi.com</a>.</li>
<li>Set up your Gurobi license file in accordance with Gurobi documentation.</li>
<li><code class="language-plaintext highlighter-rouge">export GRB_LICENSE_FILE=/path/to/gurobi.lic</code></li>
<li>Download and install <code class="language-plaintext highlighter-rouge">gurobi10.0.2_mac64.pkg</code>.</li>
</ol>
<p>To confirm that your setup was successful, run the tests that require Gurobi:</p>
<p><code class="language-plaintext highlighter-rouge">bazel test --config gurobi --test_tag_filters=gurobi //...</code></p>
<p>The default value of <code class="language-plaintext highlighter-rouge">--test_tag_filters</code> in Drake’s <code class="language-plaintext highlighter-rouge">bazel.rc</code> excludes
these tests. If you will be developing with Gurobi regularly, you may wish
to specify a more convenient <code class="language-plaintext highlighter-rouge">--test_tag_filters</code> in a local <code class="language-plaintext highlighter-rouge">.bazelrc</code>.
See <a href="https://docs.bazel.build/versions/main/user-manual.html#bazelrc">https://docs.bazel.build/versions/main/user-manual.html#bazelrc</a>.</p>
<h2 id="mosek">MOSEK</h2>
<p>The Drake Bazel build system downloads MOSEK<a href="/tm.html">™</a> 10.0.18 automatically. No manual
installation is required. Set the location of your license file as follows:</p>
<p><code class="language-plaintext highlighter-rouge">export MOSEKLM_LICENSE_FILE=/path/to/mosek.lic</code></p>
<p>To confirm that your setup was successful, run the tests that require MOSEK<a href="/tm.html">™</a>:</p>
<p><code class="language-plaintext highlighter-rouge">bazel test --config mosek --test_tag_filters=mosek //...</code></p>
<p>The default value of <code class="language-plaintext highlighter-rouge">--test_tag_filters</code> in Drake’s <code class="language-plaintext highlighter-rouge">bazel.rc</code> excludes
these tests. If you will be developing with MOSEK<a href="/tm.html">™</a> regularly, you may wish
to specify a more convenient <code class="language-plaintext highlighter-rouge">--test_tag_filters</code> in a local <code class="language-plaintext highlighter-rouge">.bazelrc</code>.
See <a href="https://docs.bazel.build/versions/main/user-manual.html#bazelrc">https://docs.bazel.build/versions/main/user-manual.html#bazelrc</a>.</p>
<h2 id="snopt">SNOPT</h2>
<p>Drake provides two mechanisms to include the SNOPT sources. One mechanism is
to provide your own SNOPT source archive. The other mechanism is via access to
a private RobotLocomotion git repository.</p>
<h3 id="using-your-own-source-archive">Using your own source archive</h3>
<ol>
<li>Download the SNOPT sources from the distributor in <code class="language-plaintext highlighter-rouge">.tar.gz</code> format (e.g.,
named <code class="language-plaintext highlighter-rouge">snopt7.4.tar.gz</code>).</li>
<li><code class="language-plaintext highlighter-rouge">export SNOPT_PATH=/home/username/Downloads/snopt7.4.tar.gz</code></li>
</ol>
<p>Using the RobotLocomotion git repository</p>
<ol>
<li>Obtain access to the private RobotLocomotion/snopt GitHub repository.</li>
<li><a href="https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/">Set up SSH access to github.com</a>.</li>
<li><code class="language-plaintext highlighter-rouge">export SNOPT_PATH=git</code></li>
</ol>
<p>Test the build (for either mechanism)</p>
<p>To confirm that your setup was successful, run the tests that require SNOPT:</p>
<p><code class="language-plaintext highlighter-rouge">bazel test --config snopt --test_tag_filters=snopt //...</code></p>
<p>The default value of <code class="language-plaintext highlighter-rouge">--test_tag_filters</code> in Drake’s <code class="language-plaintext highlighter-rouge">bazel.rc</code> excludes
these tests. If you will be developing with SNOPT regularly, you may wish
to specify a more convenient <code class="language-plaintext highlighter-rouge">--test_tag_filters</code> in a local <code class="language-plaintext highlighter-rouge">.bazelrc</code>.
See <a href="https://docs.bazel.build/versions/main/user-manual.html#bazelrc">https://docs.bazel.build/versions/main/user-manual.html#bazelrc</a>.</p>
<p>SNOPT support has some known problems on certain programs (see drake issue
<a href="https://github.com/RobotLocomotion/drake/issues/10422">#10422</a> for a summary).</p>
<h1 id="other-optional-dependencies">Other optional dependencies</h1>
<h2 id="openmp">OpenMP</h2>
<p>Drake is
<a href="https://github.com/RobotLocomotion/drake/issues/14858">in the process</a>
of adding support for multiprocessing using
<a href="https://en.wikipedia.org/wiki/OpenMP">OpenMP</a>.
At the moment, that support is experimental and is not recommended for Drake’s
users.</p>
<p>For Drake Developers who wish to enable OpenMP, use this config switch:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel test --config omp //...
</code></pre></div></div>
<p>This switch is enabled in CI under the “Ubuntu Everything” build flavor.</p>
<h1 id="optional-tools">Optional Tools</h1>
<p>The Drake Bazel build system has integration support for some optional
development tools:</p>
<ul>
<li>kcov – test coverage analysis</li>
</ul>
<h2 id="kcov">kcov</h2>
<p><code class="language-plaintext highlighter-rouge">kcov</code> can analyze coverage for any binary that contains DWARF format
debugging symbols, and produce nicely formatted browse-able coverage reports.</p>
<p>Drake’s <code class="language-plaintext highlighter-rouge">kcov</code> build system integration is only supported on Ubuntu, not
macOS.</p>
<p>In some cases, running kcov builds and regular builds from the same source
tree will lead to Bazel error messages like “this rule is missing dependency
declarations”. To resolve that problem, either run the kcov build from a
fresh checkout, or else run a <code class="language-plaintext highlighter-rouge">bazel clean</code>.</p>
<p>To analyze test coverage, run one (or more) tests under <code class="language-plaintext highlighter-rouge">kcov</code>:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel test --config=kcov common:polynomial_test
</code></pre></div></div>
<p>Note that it disables compiler-optimization (<code class="language-plaintext highlighter-rouge">-O0</code>) to have a better and more
precise coverage report. If you have trouble with kcov and unoptimized programs,
you can turn it back on by also supplying <code class="language-plaintext highlighter-rouge">--copt -O2</code>.</p>
<p>For each test program, individual coverage reports are written to per-target
directories. Use the <code class="language-plaintext highlighter-rouge">kcov_tool</code> to merge coverage data into a new directory:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>tools/dynamic_analysis/kcov_tool merge [OUTPUT-DIR]
</code></pre></div></div>
<p>To view the merged data, browse to <code class="language-plaintext highlighter-rouge">index.html</code> in the OUTPUT-DIR.</p>
<p>In a local developer workspace, coverage data may accumulate over successive
build jobs, even if source files or other dependencies have changed. The stale
data would be scattered within the directory tree linked as
<code class="language-plaintext highlighter-rouge">bazel-testlogs</code>. To clear out old data, use <code class="language-plaintext highlighter-rouge">kcov_tool clean</code>:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>tools/dynamic_analysis/kcov_tool clean
</code></pre></div></div>
<h3 id="kcov-and-python">kcov and Python</h3>
<p>Coverage reports for Python sources produced by kcov are useful, but can be
misleading. As of Ubuntu 22.04 and kcov 38, Python reports do not render
coverage for multi-line statements properly. Statements that use delimiter
pairs to span more than two lines, or statements that use string token pasting
across multiple lines may be mistakenly shown as only partially executed.</p>
<h3 id="drake-bazel-rules-and-kcov">Drake bazel rules and kcov</h3>
<p>Some Drake-specific bazel rules (e.g. <code class="language-plaintext highlighter-rouge">drake_cc_google_test</code>) use various
heuristics to skip certain tests in <code class="language-plaintext highlighter-rouge">kcov</code> builds. This may hinder developers
trying to use <code class="language-plaintext highlighter-rouge">kcov</code> locally on specific tests. For example:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel test --config=kcov //common:temp_directory_test
</code></pre></div></div>
<p>results in:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ERROR: No test targets were found, yet testing was requested
</code></pre></div></div>
<p>To force execution with kcov, add an empty <code class="language-plaintext highlighter-rouge">test_tag_filters</code> option:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bazel test --config=kcov --test_tag_filters= //common:temp_directory_test
</code></pre></div></div>
</article>
</div>
</section>
</div>
<footer class="site-footer padding">
<div class="contain">
<a href="/" class="drake-logo">
<img src="/images/drake-logo.svg">
</a>
<div class="footer-menu">
<ul>
<li>
<a href="/doxygen_cxx/index.html" class="site-menu-item">C++</a>
</li>
<li>
<a href="/pydrake/index.html" class="site-menu-item">Python</a>
</li>
<li class="github-link">
<a href="https://github.com/RobotLocomotion/drake" class="site-menu-item">GitHub <img src="/third_party/images/GitHub-Mark-64px.png" /></a>
</li>
</ul>
</div>
</div>
<!-- TODO(eric.cousineau): Consider placing copyright here. -->
</footer>
</div>
</div>
<script src="/assets/js/mobile.js"></script>
<!-- Search -->
<script src="/assets/js/search.js"></script>
</body>
</html>