forked from pantsbuild/pantsbuild.github.io
/
options.html
575 lines (544 loc) · 29.6 KB
/
options.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
<!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>Pants Options</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/options.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 ">
<a href="first_tutorial.html">Tutorial</a>
</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 toc-here">
Pants Options
</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="#option-scopes">Option Scopes</a></li>
<li class="toc-h1"><a href="#basic-vs-advanced-options">Basic vs. Advanced Options</a></li>
<li class="toc-h1"><a href="#recursive-options">Recursive Options</a></li>
<li class="toc-h1"><a href="#option-types">Option Types</a></li>
<li class="toc-h2"><a href="#boolean-options">Boolean Options</a></li>
<li class="toc-h2"><a href="#int-and-float-options">Int and Float Options</a></li>
<li class="toc-h2"><a href="#string-options">String Options</a></li>
<li class="toc-h2"><a href="#list-options">List Options</a></li>
<li class="toc-h2"><a href="#dict-options">Dict Options</a></li>
<li class="toc-h2"><a href="#available-options">Available Options</a></li>
<li class="toc-h1"><a href="#setting-option-values">Setting Option Values</a></li>
<li class="toc-h2"><a href="#command-line-flags">Command Line Flags</a></li>
<li class="toc-h2"><a href="#environment-variables">Environment Variables</a></li>
<li class="toc-h2"><a href="#config-file">Config File</a></li>
<li class="toc-h2"><a href="#overlaying-config-files">Overlaying Config Files</a></li>
<li class="toc-h1"><a href="#troubleshooting-config-files">Troubleshooting Config Files</a></li>
<li class="toc-h2"><a href="#use-the-right-section-name">Use the Right Section Name</a></li>
<li class="toc-h2"><a href="#check-the-formatting">Check the Formatting</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="pants-options">Pants Options</h1>
<p>Pants is very configurable and has literally hundreds of tuneable parameters, known in Pants
parlance as <em>options</em>.</p>
<p>Most options are automatically set to useful defaults. However it is inevitable that sooner or
later you'll need to tweak some of them. For example, you may want <a href="install.html">to pin your Pants version</a>.</p>
<p>The Pants options system is fairly complex. Codebase administrators will need to understand its details
and nuances. End users, however, can usually get by with just a superficial view.</p>
<h2 id="option-scopes">Option Scopes</h2>
<p>Pants has many moving parts, and more can be added via custom plugins. To avoid option naming collisions,
each configurable component is qualified by a <em>scope</em>.</p>
<ul>
<li>Global options belong to the global scope.</li>
<li>Options for task <code>task</code> in goal <code>goal</code> belong to the <code>goal.task</code> scope. E.g., <code>gen.thrift</code> or <code>compile.zinc</code>.
However if the task has the same name as the goal, then the scope is just that name. E.g., <code>./pants list</code>,
not <code>./pants list.list</code>.</li>
<li>Options for the global instance of subsystem <code>subsystem</code> belong to the <code>subsystem</code> scope. E.g., <code>jvm</code> or <code>cache</code>.</li>
<li>Options for the instance of subsystem <code>subsystem</code> belonging to some other task or subsystem with scope <code>scope</code>
belong to the <code>subsystem.scope</code> scope. E.g., <code>cache.compile.zinc</code>.</li>
</ul>
<p>The scope names are used to qualify the option names when setting their values, as explained in
the remainder of this document.</p>
<h2 id="basic-vs-advanced-options">Basic vs. Advanced Options</h2>
<p>Some options, such as <code>-l</code> to control the logging verbosity level, are
expected to be set directly by users, as needed. But most options are
expected to be configured once by a codebase administrator and not
directly modified by users. These latter options are called <em>advanced</em>
options, and are not enumerated in help messages by default. Advanced
options may change the way projects are built and packaged, impact the
build cache or change test behavior. For that reason, they should
usually be set in config files and checked in to the repo so that
build output is consistent, no matter which user invokes it.</p>
<p>To show the full list of options for a goal, including advanced
options, use <code>./pants <goal> --help-advanced</code>. You can view
all options for all scopes with <code>./pants --help-all --help-advanced</code>.</p>
<h2 id="recursive-options">Recursive Options</h2>
<p>A handful of global options, such as <code>-l</code>, are <em>recursive</em>. That is, they have a global value which
can be overridden in each scope. This allows you, for example, to set different logging verbosity
levels in different tasks.</p>
<h2 id="option-types">Option Types</h2>
<p>Option value literal formats are the same on the command-line, environment variables and in <code>pants.ini</code>,
with a couple of extra command-line conveniences.</p>
<h3 id="boolean-options">Boolean Options</h3>
<p>The boolean option values are: <code>false</code>, <code>False</code>, <code>true</code>, <code>True</code>.</p>
<p>On the command line, you can omit the value thus: <code>--foo-bar</code> is the same as <code>--foo-bar=false</code>,
and <code>--no-foo-bar</code> is the same as <code>--foo-bar=false</code>.</p>
<h3 id="int-and-float-options">Int and Float Options</h3>
<p>Specify values in decimal notation: <code>--foo=5</code>, <code>--bar=4.5</code>.</p>
<h3 id="string-options">String Options</h3>
<p>Surround strings with single or double quotes if they contain embedded spaces: <code>--foo="hello, world"</code>.</p>
<h3 id="list-options">List Options</h3>
<p>List options can be appended to and filtered, as well as overridden.
For example, for an option <code>--foo</code> whose default value is <code>[1, 2]</code>, then in <code>pants.ini</code>:</p>
<ul>
<li><code>foo: 3</code> will yield <code>[1, 2, 3]</code>.</li>
<li><code>foo: +[3, 4]</code> will yield <code>[1, 2, 3, 4]</code>.</li>
<li><code>foo: -[1]</code> will yield <code>[2]</code>.</li>
<li><code>foo: [3, 4]</code> will yield <code>[3, 4]</code>.</li>
</ul>
<p>Multiple append and filter expressions may be delimited with commas,
allowing you to append and filter simultaneously:</p>
<ul>
<li><code>foo: +[3,4],-[1]</code> will yield <code>[2, 3, 4]</code>.</li>
</ul>
<p>On the command line you can append single values multiple times:</p>
<ul>
<li><code>--foo=3 --foo=4</code> will yield the value <code>[1, 2, 3, 4]</code>.</li>
</ul>
<p>Note that these command line values will be appended to the value determined from the defaults
plus the values in <code>pants.ini</code>. To override the value, use <code>--foo=[3, 4]</code>.</p>
<p>Filters apply to the entire list constructed so far, and will filter all appearances of the value:</p>
<ul>
<li><code>--foo=1 --foo=1 --foo=2 --foo=-[1]</code> will yield <code>[2, 2]</code>.</li>
</ul>
<p>Filters take precedence over appends, so you cannot "add something back in":</p>
<ul>
<li><code>--foo=-[2] --foo=2</code> will yield <code>[1]</code>.</li>
</ul>
<h3 id="dict-options">Dict Options</h3>
<p>Dict option values are Python-style dict literals: <code>--foo={"a":1,"b":2}</code>.</p>
<h3 id="available-options">Available Options</h3>
<p>The options available in a given Pants-enabled codebase depend on which backends and plugins are activated.</p>
<ul>
<li>View <a href="" title="options_reference.html">all options</a> available in a "vanilla" Pants install.</li>
<li>To see a complete list of all basic options available in a given Pants-enabled codebase, enter <code>./pants help-all</code>.</li>
<li>To see global (or goal-specific) basic options, enter <code>./pants help (goal)</code>.</li>
<li>To see global (or goal-specific) basic and advanced options, enter <code>./pants help-advanced (goal)</code>.</li>
</ul>
<h2 id="setting-option-values">Setting Option Values</h2>
<p>Every Pants option can be set in one three ways, in descending order of precendence:</p>
<ul>
<li>Using a command-line flag.</li>
<li>Using an environment variable.</li>
<li>In a config file.</li>
</ul>
<p>Config files are typically used to set codebase-wide defaults for all users. Individual
users can then override various values using environment variables or command-line flags.</p>
<p>Options that aren't set by one of these three methods will fall back to a sensible default, so
that Pants will work "out of the box" in common scenarios.</p>
<h3 id="command-line-flags">Command Line Flags</h3>
<p>Option <code>option</code> in scope <code>foo.bar</code> can be set using the flag <code>--foo-bar-option=<value></code>.</p>
<p>Global options are set with no scope qualifier, e.g., <code>--pants-workdir=/path/to/workdir</code>.</p>
<p>Values for single-letter flags (those that start with a single dash) can be set without the equals
sign: <code>-ldebug</code> is the same as <code>--level=debug</code> (<code>-l</code> is a synonym for <code>--level</code>). All other flags
must use an equals sign to set a value.</p>
<p>There's a useful shorthand that can save some typing when setting multiple options for a single task:
If you invoke a task explicitly on the command line then you can follow that task with unqualified
options in its scope. E.g., <code>./pants compile.zinc --no-incremental --name-hashing</code>
instead of <code>./pants compile --no-compile-zinc-incremental --compile-zinc-name-hashing</code>.</p>
<p>Note that this shorthand requires you to mention a specific task, not just a goal: <code>./pants compile.zinc</code>
instead of just <code>./pants compile</code> as you would usually enter. All tasks in the <code>compile</code> goal will
still be executed, not just <code>compile.zinc</code>, but the <code>.zinc</code> addition is a convenience to support shorthand options.</p>
<p>Of course this works when specifying multiple goals, e.g.,</p>
<p><code>./pants compile.zinc --no-incremental --name-hashing test.junit --parallel-threads=4</code></p>
<h3 id="environment-variables">Environment Variables</h3>
<p>Option <code>option</code> in scope <code>foo.bar</code> can be set via the environment variable <code>PANTS_FOO_BAR_OPTION</code>.
E.g., <code>PANTS_COMPILE_ZINC_INCREMENTAL=false</code>.</p>
<p>Global options can be set using <code>PANTS_GLOBAL_OPTION</code> as expected, but you can also omit the GLOBAL
and use <code>PANTS_OPTION</code>. E.g., <code>PANTS_LEVEL=debug</code>.</p>
<p>If a global option name itself starts with the word 'pants' then you can omit the repetition. E.g.,
<code>PANTS_WORKDIR</code> instead of <code>PANTS_PANTS_WORKDIR</code>.</p>
<p>Environment variables are overridden by command line flags, but take
precedence over settings in config files.</p>
<h3 id="config-file">Config File</h3>
<p>The main Pants config file location is <code>pants.ini</code> in your source tree's top-level directory.
If you installed pants <a href="install.html">as recommended</a> this file should already exist.</p>
<p>The <code>pants.ini</code> file is an INI file parsed by
<a href="http://docs.python.org/library/configparser.html">ConfigParser</a>. See
<a href="http://tools.ietf.org/html/rfc822.html#section-3.1">RFC #822</a>
section 3.1.1 for the full rules python uses to parse ini file
entries.</p>
<p>A <code>pants.ini</code> file looks something like:</p>
<div class="codehilite"><pre><span class="k">[scope]</span>
<span class="err">option1:</span> <span class="err">value1</span>
<span class="err">option2:</span> <span class="err">value2</span>
</pre></div>
<p>Sections in the <code>.ini</code> file correspond to the task name or
subsystem name, or a combination of both.</p>
<p>The <code>[DEFAULT]</code> section is special: its values are available in all other sections. E.g.,</p>
<div class="codehilite"><pre><span class="k">[DEFAULT]</span>
<span class="err">thrift_workdir:</span> <span class="err">%(pants_workdir)s/thrift</span>
<span class="k">[GLOBAL]</span>
<span class="err">print_exception_stacktrace:</span> <span class="err">True</span>
<span class="k">[gen.thrift]</span>
<span class="err">workdir:</span> <span class="err">%(thrift_workdir)s</span>
<span class="k">[compile.zinc]</span>
<span class="err">args:</span> <span class="err">[</span>
<span class="err">'-C-Tnowarnprefixes',</span> <span class="err">'-C%(thrift_workdir)s',</span>
<span class="err">]</span>
</pre></div>
<p>Note that continuation lines of multiple-line values must be indented. For example, the closing
bracket in the multi-line list above.</p>
<p>Settings in config files are overridden by options specified in the
environment or by command line flags.</p>
<p>There are a few differences in using options in the config file compared to invoking them from the
command line:</p>
<ul>
<li>Omit the leading double dash (<code>--</code>)</li>
<li>Dash characters (<code>-</code>) are transposed to underscores (<code>_</code>).</li>
<li>Boolean flag values are enabled and disabled by setting the value
of the option to <code>True</code> or <code>False</code></li>
<li>The prefix for long form options is not specified. Instead, you must organize the options
into their appropriate sections.</li>
</ul>
<h3 id="overlaying-config-files">Overlaying Config Files</h3>
<p>Sometimes it's convenient to keep <code>.ini</code> settings in more than one file. Perhaps you usually
operate Pants in one "mode", but occasionally need to use a tweaked set of settings.</p>
<p>Use the <code>--pants-config-files</code> command-line option to specify a second <code>.ini</code> file. Each of
this <code>.ini</code> file's values override the corresponding value in <code>pants.ini</code>, if any.
For example, if your <code>pants.ini</code> contains the section</p>
<div class="codehilite"><pre>[test.junit]
coverage_html_open: True
debug: False
</pre></div>
<p>...and you invoke <code>--pants-config-files=quick.ini</code> and your <code>quick.ini</code> says</p>
<div class="codehilite"><pre>[test.junit]
coverage_html_open: False
skip: True
</pre></div>
<p>...then Pants will act as if you specified</p>
<div class="codehilite"><pre>[test.junit]
coverage_html_open: False
skip: True
debug: False
</pre></div>
<p>Note that <code>--pants-config-files</code> is a list-valued option, so all the
idioms of lists work. You can add a third file with another invocation
of <code>--pants-config-files=<path></code>, or you can replace the standard one
entirely with <code>--pants-config-files=[<list>]</code>.</p>
<h2 id="troubleshooting-config-files">Troubleshooting Config Files</h2>
<h3 id="use-the-right-section-name">Use the Right Section Name</h3>
<p>Section names must correspond to actual option scopes. Use the correct section name as specified
in the help output:</p>
<div class="codehilite"><pre><span class="c"># Wrong</span>
<span class="err">[compile]</span> <span class="c"># The correct scope for the 'warnings' option is compile.zinc</span>
<span class="err">zinc_warnings:</span> <span class="err">False</span>
<span class="c"># Right</span>
<span class="k">[compile.zinc]</span>
<span class="err">warnings:</span> <span class="err">False</span>
</pre></div>
<p>When in doubt, the scope is described in the heading for each option in the help output:</p>
<div class="codehilite"><pre><span class="nv">$ </span>./pants compile.zinc --help
compile.zinc options:
Compile Scala and Java code using Zinc.
--<span class="o">[</span>no-<span class="o">]</span>compile-zinc-debug-symbols <span class="o">(</span>default: False<span class="o">)</span>
Compile with debug symbol enabled.
...
</pre></div>
<h3 id="check-the-formatting">Check the Formatting</h3>
<p>Settings that span multiple lines should be indented. To minimize problems, follow these
conventions:</p>
<ul>
<li>Followon lines should be indented four spaces.</li>
<li>The ending bracket for lists and dicts should be indented two spaces.</li>
</ul>
<p>Here are some examples of correctly and incorrectly formatted values:</p>
<div class="codehilite"><pre><span class="c"># Right</span>
<span class="err">jvm_options:</span> <span class="k">[ "foo", "bar" ]</span>
<span class="c"># Right</span>
<span class="err">jvm_options:</span> <span class="err">[</span>
<span class="err">"foo",</span> <span class="err">"bar"</span>
<span class="err">]</span>
<span class="c"># Wrong</span>
<span class="err">jvm_options:</span> <span class="err">[</span> <span class="err">"foo",</span>
<span class="err">"bar"</span> <span class="err">]</span> <span class="c"># Followon line must be indented</span>
<span class="c"># Wrong</span>
<span class="err">jvm_options:</span> <span class="err">[</span>
<span class="err">"foo",</span> <span class="err">"bar"</span>
<span class="err">]</span> <span class="c"># closing bracket must be indented</span>
</pre></div>
<!-- main content end -->
<div class="generated">
Generated by <a href="docs.html">publish_docs</a>
from dist/markdown/html/src/docs/options.html 2017-05-29T10:30:50.990895
</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>