forked from pantsbuild/pantsbuild.github.io
/
first_tutorial.html
622 lines (590 loc) · 34.8 KB
/
first_tutorial.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
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
<!DOCTYPE html>
<html lang="en">
<!--
Copyright 2014 Pants project contributors (see CONTRIBUTORS.md).
Licensed under the Apache License, Version 2.0 (see LICENSE).
-->
<head>
<meta charset="utf-8"/>
<title>Tutorial</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="pants-logo.ico">
<!-- In case this is a "test publish", tell search engines where real version lives: -->
<link rel="canonical" href="http://pantsbuild.org/first_tutorial.html">
<link rel="stylesheet" href="bootstrap-custom.min.css">
<link rel="stylesheet" href="bootstrap-custom-theme.min.css">
<link rel="stylesheet" href="docsite.css">
</head>
<body>
<div class="header">
<nav class="navbar navbar-default navbar-static-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand navbar-brand-img" href="index.html">
<img src="pants-logo.ico" alt="[pantsbuild logo]">
</a>
<a class="navbar-brand" href="index.html">
Pants
</a>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav navbar-right">
<li><a href="/">Docs</a></li>
<li><a href="community.html">Community</a></li>
<li><a href="https://www.github.com/pantsbuild/pants">GitHub</a></li>
<li>
<form class="navbar-form navbar-left search" role="search" action="https://www.google.com/search">
<div class="form-group">
<input type="text" name="as_q" class="form-control query" placeholder="Search">
<input name="as_sitesearch" value="pantsbuild.org" type="hidden">
</div>
</form>
</li>
</ul>
</div><!--/.nav-collapse -->
</div>
</nav>
</div>
<div class="page">
<div class="container-fluid">
<div class="row">
<div class="col-md-1">
</div>
<div class="col-md-2">
<div class="site-toc">
<ul>
<li class="toc-h1 toc-heading">
Getting Started
</li>
<li class="toc-h1 toc-link ">
<a href="install.html">Installing Pants</a>
</li>
<li class="toc-h1 toc-link ">
<a href="setup_repo.html">Setting Up Pants</a>
</li>
<li class="toc-h1 toc-link toc-here">
Tutorial
</li>
<li class="toc-h1 toc-link ">
<a href="common_tasks.html">Common Tasks</a>
</li>
<li class="toc-h1 toc-heading">
Pants Basics
</li>
<li class="toc-h1 toc-link ">
<a href="why_use_pants.html">Why Use Pants?</a>
</li>
<li class="toc-h1 toc-link ">
<a href="first_concepts.html">Pants Concepts</a>
</li>
<li class="toc-h1 toc-link ">
<a href="build_files.html">BUILD files</a>
</li>
<li class="toc-h1 toc-link ">
<a href="target_addresses.html">Target Addresses</a>
</li>
<li class="toc-h1 toc-link ">
<a href="3rdparty.html">Third-Party Dependencies</a>
</li>
<li class="toc-h1 toc-link ">
<a href="options.html">Pants Options</a>
</li>
<li class="toc-h1 toc-link ">
<a href="invoking.html">Invoking Pants</a>
</li>
<li class="toc-h1 toc-link ">
<a href="reporting_server.html">Reporting Server</a>
</li>
<li class="toc-h1 toc-link ">
<a href="ide_support.html">IDE Support</a>
</li>
<li class="toc-h1 toc-heading">
JVM
</li>
<li class="toc-h1 toc-link ">
<a href="jvm_projects.html">JVM Projects with Pants</a>
</li>
<li class="toc-h1 toc-link ">
<a href="3rdparty_jvm.html">JVM 3rdparty Pattern</a>
</li>
<li class="toc-h1 toc-link ">
<a href="scala.html">Scala Support</a>
</li>
<li class="toc-h1 toc-link ">
<a href="publish.html">Publishing Artifacts</a>
</li>
<li class="toc-h1 toc-link ">
<a href="from_maven.html">Pants for Maven Experts</a>
</li>
<li class="toc-h1 toc-heading">
Python
</li>
<li class="toc-h1 toc-link ">
<a href="python_readme.html">Python Projects with Pants</a>
</li>
<li class="toc-h1 toc-link ">
<a href="3rdparty_py.html">Python 3rdparty Pattern</a>
</li>
<li class="toc-h1 toc-heading">
Go
</li>
<li class="toc-h1 toc-link ">
<a href="go_readme.html">Go support for Pants</a>
</li>
<li class="toc-h1 toc-heading">
Codegen
</li>
<li class="toc-h1 toc-link ">
<a href="thrift_deps.html">Thrift</a>
</li>
<li class="toc-h1 toc-heading">
Docgen
</li>
<li class="toc-h1 toc-link ">
<a href="page.html">Markdown</a>
</li>
<li class="toc-h1 toc-heading">
Getting Help
</li>
<li class="toc-h1 toc-link ">
<a href="tshoot.html">Troubleshooting</a>
</li>
<li class="toc-h1 toc-link ">
<a href="community.html">Community</a>
</li>
<li class="toc-h1 toc-heading">
Reference
</li>
<li class="toc-h1 toc-link ">
<a href="build_dictionary.html">Pants BUILD Dictionary</a>
</li>
<li class="toc-h1 toc-link ">
<a href="options_reference.html">Pants Reference</a>
</li>
<li class="toc-h1 toc-heading">
Release Notes
</li>
<li class="toc-h1 toc-link ">
<a href="notes-1.3.x.html">1.3.x Stable Releases</a>
</li>
<li class="toc-h1 toc-link ">
<a href="notes-1.2.x.html">1.2.x Stable Releases</a>
</li>
<li class="toc-h1 toc-link ">
<a href="notes-1.1.x.html">1.1.x Stable Releases</a>
</li>
<li class="toc-h1 toc-link ">
<a href="notes-1.0.x.html">1.0.x Stable Releases</a>
</li>
<li class="toc-h1 toc-link ">
<a href="notes-master.html">Master Pre-Releases</a>
</li>
<li class="toc-h1 toc-heading">
Developer
</li>
<li class="toc-h1 toc-link ">
<a href="dev.html">Pants Developer Center</a>
</li>
<li class="toc-h1 toc-link ">
<a href="export.html">Export Format</a>
</li>
</ul>
</div> <!-- site-toc -->
</div>
<div class="col-md-8">
<div class="content">
<div class="mainflow">
<nav class="pagetoc">
<ul>
<li class="toc-h1"><a href="#pants-command-line">Pants Command Line</a></li>
<li class="toc-h2"><a href="#output">Output</a></li>
<li class="toc-h2"><a href="#multiple-goals-multiple-targets">Multiple Goals, Multiple Targets</a></li>
<li class="toc-h2"><a href="#command-line-options">Command-line Options</a></li>
<li class="toc-h2"><a href="#help">Help</a></li>
<li class="toc-h2"><a href="#pantsini">pants.ini</a></li>
<li class="toc-h1"><a href="#build-files">BUILD Files</a></li>
<li class="toc-h2"><a href="#anatomy-of-a-build-target">Anatomy of a BUILD Target</a></li>
<li class="toc-h1"><a href="#the-usual-commands">The Usual Commands</a></li>
<li class="toc-h1"><a href="#next">Next</a></li>
</ul>
</nav>
<!-- main content start -->
<!-- generated by pants! -->
<style>
.codehilite .hll { background-color: #ffffcc }
.codehilite { background: #f0f0f0; }
.codehilite .c { color: #60a0b0; font-style: italic } /* Comment */
.codehilite .err { border: 1px solid #FF0000 } /* Error */
.codehilite .k { color: #007020; font-weight: bold } /* Keyword */
.codehilite .o { color: #666666 } /* Operator */
.codehilite .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #007020 } /* Comment.Preproc */
.codehilite .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */
.codehilite .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */
.codehilite .gd { color: #A00000 } /* Generic.Deleted */
.codehilite .ge { font-style: italic } /* Generic.Emph */
.codehilite .gr { color: #FF0000 } /* Generic.Error */
.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.codehilite .gi { color: #00A000 } /* Generic.Inserted */
.codehilite .go { color: #808080 } /* Generic.Output */
.codehilite .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.codehilite .gs { font-weight: bold } /* Generic.Strong */
.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.codehilite .gt { color: #0040D0 } /* Generic.Traceback */
.codehilite .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.codehilite .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.codehilite .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
.codehilite .kp { color: #007020 } /* Keyword.Pseudo */
.codehilite .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
.codehilite .kt { color: #902000 } /* Keyword.Type */
.codehilite .m { color: #40a070 } /* Literal.Number */
.codehilite .s { color: #4070a0 } /* Literal.String */
.codehilite .na { color: #4070a0 } /* Name.Attribute */
.codehilite .nb { color: #007020 } /* Name.Builtin */
.codehilite .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
.codehilite .no { color: #60add5 } /* Name.Constant */
.codehilite .nd { color: #555555; font-weight: bold } /* Name.Decorator */
.codehilite .ni { color: #d55537; font-weight: bold } /* Name.Entity */
.codehilite .ne { color: #007020 } /* Name.Exception */
.codehilite .nf { color: #06287e } /* Name.Function */
.codehilite .nl { color: #002070; font-weight: bold } /* Name.Label */
.codehilite .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
.codehilite .nt { color: #062873; font-weight: bold } /* Name.Tag */
.codehilite .nv { color: #bb60d5 } /* Name.Variable */
.codehilite .ow { color: #007020; font-weight: bold } /* Operator.Word */
.codehilite .w { color: #bbbbbb } /* Text.Whitespace */
.codehilite .mf { color: #40a070 } /* Literal.Number.Float */
.codehilite .mh { color: #40a070 } /* Literal.Number.Hex */
.codehilite .mi { color: #40a070 } /* Literal.Number.Integer */
.codehilite .mo { color: #40a070 } /* Literal.Number.Oct */
.codehilite .sb { color: #4070a0 } /* Literal.String.Backtick */
.codehilite .sc { color: #4070a0 } /* Literal.String.Char */
.codehilite .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
.codehilite .s2 { color: #4070a0 } /* Literal.String.Double */
.codehilite .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
.codehilite .sh { color: #4070a0 } /* Literal.String.Heredoc */
.codehilite .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
.codehilite .sx { color: #c65d09 } /* Literal.String.Other */
.codehilite .sr { color: #235388 } /* Literal.String.Regex */
.codehilite .s1 { color: #4070a0 } /* Literal.String.Single */
.codehilite .ss { color: #517918 } /* Literal.String.Symbol */
.codehilite .bp { color: #007020 } /* Name.Builtin.Pseudo */
.codehilite .vc { color: #bb60d5 } /* Name.Variable.Class */
.codehilite .vg { color: #bb60d5 } /* Name.Variable.Global */
.codehilite .vi { color: #bb60d5 } /* Name.Variable.Instance */
.codehilite .il { color: #40a070 } /* Literal.Number.Integer.Long */
</style>
<h1 id="tutorial">Tutorial</h1>
<p>This tutorial walks you through some first steps with Pants.
It assumes you're already familiar with
<a href="first_concepts.html">basic Pants build concepts</a>,
and that you're working in a source tree that already has <code>pants</code> installed (such as
Pants's own repo:
<a href="https://github.com/pantsbuild/pants">pantsbuild/pants</a>).</p>
<p>The first time you run <code>pants</code>, try it without arguments. This makes
Pants "bootstrap" itself, downloading and compiling things it needs:</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants goals
</pre></div>
<p>Now you're ready to invoke pants for more useful things.</p>
<p>You invoke pants with <em>goals</em> (like <code>test</code> or <code>bundle</code>) and the <em>targets</em> to use (like
<code>examples/tests/java/org/pantsbuild/example/hello/greet:greet</code>). For
example,</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants <span class="nb">test </span>examples/tests/java/org/pantsbuild/example/hello/greet:greet
</pre></div>
<p>Goals (the "verbs" of Pants) produce new files from targets (the "nouns").</p>
<p>As a code author, you define your code's build targets in BUILD files. A
build target might produce some output file[s]; it might have sources
and/or depend on other build targets. There might be several BUILD files
in the codebase; a target in one can depend on a target in another.
Typically, a directory's BUILD file defines the target[s] whose sources
are files in that directory.</p>
<h2 id="pants-command-line">Pants Command Line</h2>
<p>Pants knows about goals ("verbs" like <code>bundle</code> and <code>test</code>) and targets
(build-able things in your source code). A typical pants command-line
invocation looks like</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants <span class="nb">test </span>examples/tests/java/org/pantsbuild/example/hello/greet:greet
</pre></div>
<p>Looking at the pieces of this we see</p>
<p><code>./pants</code><br>
That <code>./</code> isn't a typo. A source tree that's been set up with Pants
build has a <code>pants</code> executable in its top-level directory.</br></p>
<p>The first time you run <code>./pants</code>, it might take a while: it will probably auto-update by
downloading the latest version.</p>
<p><code>test</code><br>
<code>test</code> is a <em>goal</em>, a "verb" that Pants knows about. The <code>test</code> goal runs tests and reports results.</br></p>
<p>Some goals are <code>gen</code> (generate code from Thrift, Antlr, Protocol
Buffer), <code>compile</code>, <code>run</code> (run a binary), and <code>test</code> (run tests and report results). Pants
knows that some of these goals depend on each other. E.g., in this
example, before it run tests, it must compile the code.</p>
<p>You can specify more than one goal on a command line. E.g., to run
tests <em>and</em> run a binary, we could have said <code>./pants test run ...</code></p>
<p><code>examples/tests/java/org/pantsbuild/example/hello/greet:greet</code><br>
This is a <em>build target</em>, a "build-able" thing in your source code. To
define these, you set up configuration files named <code>BUILD</code> in your
source code file tree. (You'll see more about these later.)</br></p>
<p>Targets can depend on other targets. E.g., a test target normally depends on another target
containing "library" code to test; to build and run the test code, Pants also first builds the
library code.</p>
<p>You can specify more than one target on a command line. Pants will carry
out its goals on all specified targets. E.g., you might use this to
to run a few directories' worth of tests.</p>
<h3 id="output">Output</h3>
<p>Pants produces files, both build outputs and intermediate files
generated "along the way". These files live in directories under the
top-level directory:</p>
<p><code>dist/</code><br>
By default, build outputs go in the <code>dist/</code> directory. So far, you've
just run the <code>test</code> goal, which doesn't output a file. But if you'd
instead invoked, for example, the <code>bundle</code> goal on a <code>jvm_app</code> target,
Pants would have populated this directory with many JVM <code>.jar</code> files.</br></p>
<p><code>.pants.d/</code><br>
Intermediate files go in the <code>.pants.d/</code> directory. You don't want to
rely on files in there; if the Pants implementation changes, it's likely
to change how it uses intermediate files. You don't want to edit/delete
files in there; you may confuse Pants. But if you want to peek at some
generated code, the code is probably in here somewhere.</br></p>
<h3 id="multiple-goals-multiple-targets">Multiple Goals, Multiple Targets</h3>
<p>You can specify multiple goals and multiple targets. Pants applies all
the goals to all the targets, skipping things that wouldn't make sense.
E.g., you could</p>
<ul>
<li>Invoke <code>test</code> and <code>run</code> goals to both run tests and run a binary.</li>
<li>Specify both test and binary targets.</li>
</ul>
<p>In this example, it doesn't make sense to run a binary target as a test, so
Pants doesn't do that.</p>
<p><a id="tut_goal_target_mismatch" pantsmark="tut_goal_target_mismatch"></a></p>
<p><em>Goal-Target Mismatch</em></p>
<p>One tricky side effect of this is accidental <em>goal-target mismatch</em>: You
can invoke a goal that doesn't make sense for a target. E.g., you can
invoke the <code>test</code> goal on a target that's not actually a test target. Pants won't
complain. It knows that it should compile code before it tests it; it
will happily compile the build targets. If you're not watching closely,
you might see a lot of output scrolling past and think it was running
tests.</p>
<h3 id="command-line-options">Command-line Options</h3>
<p>You can specify some details of Pants' actions by means of command-line options. E.g., you could
tell Pants to "fail fast" on the first <code>junit</code> test failure instead of running and reporting all
<code>junit</code> tests like so:</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants test.junit --fail-fast examples/tests/java/org/pantsbuild/example/hello/greet:greet
</pre></div>
<p>Here, <code>test</code> has become <code>test.junit</code>. The <code>test</code> goal is made up of parts, or <em>tasks</em>: <code>test.junit</code>,
<code>test.pytest</code>, and <code>test.specs</code>. We want to specify a flag to the <code>test.junit</code> task, so we
specify that part on the command line. (Pants still runs the other parts of the <code>test</code> goal.
The dotted notation tells Pants where to apply options.)</p>
<p>We entered the <code>--fail-fast</code> flag after <code>test.junit</code> but before the target. Command-line flags
for a goal or task go immediately after that goal or task.</p>
<p>You can specify options for more than one part of a goal. For example,</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants test.junit --fail-fast test.pytest --options<span class="o">=</span><span class="s1">'-k seq'</span> examples/tests::
</pre></div>
<p>Here, the <code>--fail-fast</code> flag affects <code>test.junit</code> and <code>--options</code> affects <code>test.pytest</code>.</p>
<p>Pants has some global options, options not associated with just one goal. For example,
If you pass the global <code>-ldebug</code> flag after the word <code>goal</code> but before any particular goal or
task, you get verbose debug-level logging for all goals:</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants -ldebug <span class="nb">test </span>examples/tests/java/org/pantsbuild/example/hello/greet:
09:18:53 00:00 <span class="o">[</span>main<span class="o">]</span>
<span class="o">(</span>To run a reporting server: ./pants server<span class="o">)</span>
09:18:53 00:00 <span class="o">[</span>bootstrap<span class="o">]</span>
09:18:54 00:01 <span class="o">[</span>setup<span class="o">]</span>
09:18:54 00:01 <span class="o">[</span>parse<span class="o">]</span>DEBUG<span class="o">]</span> Located Distribution<span class="o">(</span>u<span class="s1">'/Library/Java/JavaVirtualMachines/jdk1.7.0_60.jdk/Contents/Home/bin'</span>, <span class="nv">minimum_version</span><span class="o">=</span>None, <span class="nv">maximum_version</span><span class="o">=</span>None <span class="nv">jdk</span><span class="o">=</span>False<span class="o">)</span> <span class="k">for </span>constraints: minimum_version None, maximum_version None, jdk False
DEBUG<span class="o">]</span> Selected protoc binary bootstrapped to: /Users/lhosken/.pants.d/bin/protobuf/mac/10.9/2.4.1/protoc
DEBUG<span class="o">]</span> Selected thrift binary bootstrapped to: /Users/lhosken/.pants.d/bin/thrift/mac/10.9/0.5.0-finagle/thrift
...lots of build output...
</pre></div>
<p>For details about the Pants command line, see <a href="invoking.html">Invoking Pants</a>.</p>
<h3 id="help">Help</h3>
<p>To get help about a Pants goal, invoke <tt>./pants <em>goalname</em> -h</tt>. This lists
command-line options for that goal. E.g.,</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants <span class="nb">test</span> -h
cache.test options:
--<span class="o">[</span>no-<span class="o">]</span>cache-test-read <span class="o">(</span>default: True<span class="o">)</span>
Read build artifacts from cache, <span class="k">if </span>available.
--<span class="o">[</span>no-<span class="o">]</span>cache-test-write <span class="o">(</span>default: True<span class="o">)</span>
Write build artifacts to cache, <span class="k">if </span>available.
test.go options:
Runs <span class="sb">`</span>go <span class="nb">test</span><span class="sb">`</span> on Go packages.
--<span class="o">[</span>no-<span class="o">]</span><span class="nb">test</span>-go-remote <span class="o">(</span>default: False<span class="o">)</span>
Enables running tests found in go_remote_libraries.
--test-go-build-and-test-flags<span class="o">=</span><str> <span class="o">(</span>default: <span class="o">)</span>
Flags to pass in to <span class="sb">`</span>go <span class="nb">test</span><span class="sb">`</span> tool.
...more <span class="nb">test </span>options...
test.junit options:
--test-junit-confs<span class="o">=</span><span class="s2">"['str1','str2',...]"</span> <span class="o">(</span>--test-junit-confs<span class="o">=</span><span class="s2">"['str1','str2',...]"</span><span class="o">)</span> ... <span class="o">(</span>default: <span class="o">[</span><span class="s1">'default'</span><span class="o">])</span>
Use only these Ivy configurations of external deps.
--<span class="o">[</span>no-<span class="o">]</span><span class="nb">test</span>-junit-skip <span class="o">(</span>default: False<span class="o">)</span>
Skip running junit.
--<span class="o">[</span>no-<span class="o">]</span><span class="nb">test</span>-junit-fail-fast <span class="o">(</span>default: False<span class="o">)</span>
Fail fast on the first <span class="nb">test </span>failure in a suite.
...many more <span class="nb">test </span>options...
</pre></div>
<p>The <code>test</code> goal is made up of parts, or <em>tasks</em> such as <code>test.junit</code> and <code>test.pytest</code>.
Command-line options apply to those tasks. The goal's help groups options by task. E.g., here, it
shows the <code>test.go</code> <code>--test-go-build-and-test-flags</code> option with <code>test.go</code>.</p>
<p>For a list of available goals, <code>./pants goals</code>.</p>
<p>For help with things that aren't goals (global options, other kinds of help), use</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants -h
</pre></div>
<p>If you want help diagnosing some strange Pants behavior, you might want verbose output.
To get this, instead of just invoking <code>./pants</code>, set some environment variables and request
more logging: <code>PEX_VERBOSE=5 ./pants -ldebug</code>.</p>
<h3 id="pantsini">pants.ini</h3>
<p>Pants allows you to also specify options in a config file. If you want to always run pants
with a particular option, you can configure it in a file at the root of the repo named <code>pants.ini</code></p>
<div class="codehilite"><pre><span class="k">[default]</span>
<span class="na">jvm_options: ["-Xmx1g", "-Dfile.encoding</span><span class="o">=</span><span class="s">UTF8"]</span>
<span class="k">[test.junit]</span>
<span class="err">fail-fast:</span> <span class="err">True</span>
</pre></div>
<p>For more information on the <code>pants.ini</code> file format, see
<a href="invoking.html">Invoking Pants</a>.</p>
<h2 id="build-files">BUILD Files</h2>
<p>When we ran the <code>pants test</code> goal, we told pants what target to build, but where are these
targets defined? Scattered around the source tree are <code>BUILD</code> files. These <code>BUILD</code> files
define targets. For example, this code snippet of <code>java/org/pantsbuild/example/hello/main/BUILD</code>
defines two targets: the app we ran and the binary that contains its code.
These targets are named <code>main</code> (of type <code>jvm_app</code>) and and <code>main-bin</code> (of type <code>jvm_binary</code>):</p>
<p>
<div class="md-included-snippet"><div class="codehilite"><pre><span class="c"># Note that the target has no explicit name, so it defaults to the name</span>
<span class="c"># of the directory, in this case 'main'.</span>
<span class="n">jvm_app</span><span class="p">(</span>
<span class="n">basename</span> <span class="o">=</span> <span class="s">'hello-example'</span><span class="p">,</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">':main-bin'</span>
<span class="p">],</span>
<span class="n">bundles</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">bundle</span><span class="p">(</span><span class="n">relative_to</span><span class="o">=</span><span class="s">'config'</span><span class="p">,</span> <span class="n">fileset</span><span class="o">=</span><span class="n">globs</span><span class="p">(</span><span class="s">'config/*'</span><span class="p">))</span>
<span class="p">]</span>
<span class="p">)</span>
<span class="c"># The binary, the "runnable" part:</span>
<span class="n">jvm_binary</span><span class="p">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">'main-bin'</span><span class="p">,</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">'examples/src/java/org/pantsbuild/example/hello/greet'</span><span class="p">,</span>
<span class="s">'examples/src/resources/org/pantsbuild/example/hello'</span><span class="p">,</span>
<span class="p">],</span>
<span class="n">source</span> <span class="o">=</span> <span class="s">'HelloMain.java'</span><span class="p">,</span>
<span class="n">main</span> <span class="o">=</span> <span class="s">'org.pantsbuild.example.hello.main.HelloMain'</span><span class="p">,</span>
<span class="n">basename</span> <span class="o">=</span> <span class="s">'hello-example'</span><span class="p">,</span>
<span class="p">)</span>
</pre></div></div>
</p>
<p>Those <code>dependencies</code> statements are interesting.
The <code>main-bin</code> build target depends on other build targets;
its <code>dependencies</code> lists those.
To build a runnable Java binary, we need to first compile its dependencies.
The <code>main-bin</code> binary's dependency,
<code>'examples/src/java/org/pantsbuild/example/hello/greet'</code>, is the <em>address</em> of
another target. Addresses look, roughly, like <code>path/to/dir:targetname</code>. We can see this build
target in the <code>.../hello/greet/BUILD</code> file:</p>
<p>
<div class="md-included-snippet"><div class="codehilite"><pre><span class="c"># Note that the target has no explicit name, so it defaults to the name</span>
<span class="c"># of the directory, in this case 'greet'.</span>
<span class="c"># It also has no explicit sources, so it defaults to the sources implied</span>
<span class="c"># by the target type, in this case "globs('*.java')".</span>
<span class="n">java_library</span><span class="p">(</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">[],</span> <span class="c"># A more realistic example would depend on other libs,</span>
<span class="c"># but this "hello world" is pretty simple.</span>
<span class="n">provides</span> <span class="o">=</span> <span class="n">artifact</span><span class="p">(</span><span class="n">org</span><span class="o">=</span><span class="s">'org.pantsbuild.example'</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="s">'hello-greet'</span><span class="p">,</span>
<span class="n">repo</span><span class="o">=</span><span class="n">public</span><span class="p">,),</span>
<span class="p">)</span>
</pre></div></div>
</p>
<p>Pants uses dependency information to figure out how to build your code.
You might find it useful for other purposes, too. For example, if you
change a library's code, you might want to know which test targets
depend on that library: you might want to run those tests to make sure
they still work.</p>
<h3 id="anatomy-of-a-build-target">Anatomy of a <code>BUILD</code> Target</h3>
<p>A target definition in a <code>BUILD</code> file looks something like</p>
<div class="codehilite"><pre><span class="n">java_library</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">'util'</span><span class="p">,</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">'3rdparty:commons-math'</span><span class="p">,</span>
<span class="s">'3rdparty:thrift'</span><span class="p">,</span>
<span class="s">'src/java/org/pantsbuild/auth'</span><span class="p">,</span>
<span class="s">':base'</span>
<span class="p">],</span>
<span class="n">sources</span><span class="o">=</span><span class="n">globs</span><span class="p">(</span><span class="s">'*.java'</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
<p>Here, <code>java_library</code> is the target's <em>type</em>. Different target types
support different arguments. The following arguments are pretty common:</p>
<p><strong>name</strong><br>
We use a target's name to refer to the target. If you omit the name,
it defaults to the name of the directory the <code>BUILD</code> file is in.</br></p>
<p>You use names on the command line to specify which targets to operate on.
You also use names in <code>BUILD</code> files when one target refers to another,
e.g. in <code>dependencies</code>:</p>
<p><strong>dependencies</strong><br>
List of things this target depends upon. If this target's code imports
code that "lives" in other targets, list those targets here. If this
target imports code that "lives" in <code>.jar</code>s/<code>.egg</code>s from elsewhere,
refer to them here.</br></p>
<p><strong>sources</strong><br>
List of source files, which must be under the directory tree rooted
at the BUILD file's directory.</br></p>
<p>You can provide an explicit list, e.g.,
<code>sources=['Foo.java', 'Bar.java']</code>, or use the <code>globs</code> function
to glob over files, e.g., <code>sources=globs('*.java')</code>. Similarly,
<code>rglobs</code> will apply the glob pattern recursively in all subdirectories
of the BUILD file's directory.</p>
<p>If you omit <code>sources</code> in a target, Pants will attempt to apply a
sensible default that depends on the target type.
E.g., <code>junit_tests</code> will default to globbing over <code>*Test.java</code>,
<code>java_library</code> will default to globbing over <code>*.java</code>, minus the
test files, and so on.</p>
<h2 id="the-usual-commands">The Usual Commands</h2>
<p><strong>Make sure code compiles and tests pass:</strong><br>
Use the <code>test</code> goal with the targets you're interested in. If they are
test targets, Pants runs the tests. If they aren't test targets, Pants
will still compile them since it knows it must compile before it can
test.</br></p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants <span class="nb">test </span>src/java/com/myorg/myproject tests/java/com/myorg/myproject
</pre></div>
<p><strong>Run a binary</strong><br>
Use pants to execute a binary target. Compiles the code first if it is not up to date.</br></p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants run examples/src/java/org/pantsbuild/example/hello/simple
</pre></div>
<p><strong>Get Help</strong><br>
Get the list of goals:</br></p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants goals
</pre></div>
<p>Get help for one goal, e.g., test:</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants <span class="nb">test</span> -h
</pre></div>
<h2 id="next">Next</h2>
<p>To learn more about working with Python projects, see the
<a href="python_readme.html">Python Tutorial</a>.</p>
<p>To learn more about working with Java/JVM projects, see the
<a href="jvm_projects.html">Java Tutorial</a></p>
<!-- main content end -->
<div class="generated">
Generated by <a href="docs.html">publish_docs</a>
from dist/markdown/html/src/docs/first_tutorial.html 2017-05-29T10:30:50.821996
</div>
</div> <!-- mainflow -->
</div> <!-- content -->
</div>
<div class="col-md-1">
</div>
</div> <!-- row -->
</div> <!-- container-fluid -->
</div> <!-- page -->
<script src="https://code.jquery.com/jquery-2.2.3.min.js" integrity="sha384-I6F5OKECLVtK/BL+8iSLDEHowSAfUo76ZL9+kGAgTRdiByINKJaqTPH/QVNS1VDb" crossorigin="anonymous"></script>
<script src="bootstrap-custom.min.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-78111411-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>