forked from pantsbuild/pantsbuild.github.io
/
publish.html
702 lines (672 loc) · 40.5 KB
/
publish.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
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
<!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>Publishing Artifacts</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/publish.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 ">
<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 toc-here">
Publishing Artifacts
</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="#enabling-pants-publish">Enabling Pants Publish</a></li>
<li class="toc-h2"><a href="#tell-pants-about-your-artifact-repository">Tell Pants about your Artifact Repository</a></li>
<li class="toc-h2"><a href="#restricting-publish-to-release-branch">Restricting Publish to "Release Branch"</a></li>
<li class="toc-h2"><a href="#task-to-publish-extra-artifacts">Task to Publish "Extra" Artifacts</a></li>
<li class="toc-h1"><a href="#life-of-a-publish">Life of a Publish</a></li>
<li class="toc-h1"><a href="#how-to">How To</a></li>
<li class="toc-h1"><a href="#restricting-to-release-branch">Restricting to "Release Branch"</a></li>
<li class="toc-h1"><a href="#authenticating-to-the-artifact-repository">Authenticating to the Artifact Repository</a></li>
<li class="toc-h1"><a href="#troubleshooting">Troubleshooting</a></li>
<li class="toc-h2"><a href="#versioned-artifact-already-exists">Versioned Artifact Already Exists</a></li>
<li class="toc-h2"><a href="#failed-to-push-to-origin">Failed to Push to Origin</a></li>
<li class="toc-h2"><a href="#does-not-provide-an-artifact">Does not provide an artifact</a></li>
<li class="toc-h2"><a href="#silently-does-not-publish">Silently does not publish</a></li>
<li class="toc-h1"><a href="#want-to-publish-something-publish-many-things">Want to Publish Something? Publish Many Things</a></li>
<li class="toc-h1"><a href="#test-with-a-fake-local-publish">Test with a Fake Local "Publish"</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="publishing-artifacts">Publishing Artifacts</h1>
<p>A JVM library owner/maintainer can <em>publish</em> versioned JARs and other artifacts that
other repos can fetch and import as third-party dependencies.</p>
<p>A <a href="build_dictionary.html#bdict_java_library" pantsref="bdict_java_library"><code>java_library</code></a> target can have a <code>provides</code> parameter of type
<a href="build_dictionary.html#bdict_artifact" pantsref="bdict_artifact"><code>artifact</code></a>. The <code>artifact</code> specifies the published artifact's
coordinates, except that it does <em>not</em> specify a version; that changes each time you publish.
For an example, see
<a href="https://github.com/pantsbuild/pants/blob/master/examples/src/java/org/pantsbuild/example/hello/greet/BUILD">examples/src/java/org/pantsbuild/example/hello/greet/BUILD</a>:</p>
<p>
<div class="md-included-snippet"><div class="codehilite"><pre><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>(That <code>repo=</code> parameter assumes someone has set up your Pants configuration to know about that
artifact repository. If that assumption is false, keep reading to find out how to set this up.)</p>
<p>Pants' <code>publish</code> goal builds the library, bumps the library's version
number, and uploads the library to its repository.</p>
<p>The publishing mechanism uses <a href="http://semver.org/">Semantic Versioning ("semver")</a> for
versioning. Versions are dotted number triples (e.g., 2.5.6); when Pants
bumps a version, it specifically bumps the patch number part. Thus, if
the current version is 2.5.6, Pants bumps to 2.5.7. To publish a minor
or major version instead of a patch, you override the version number on
the command line.</p>
<p><strong>The pushdb:</strong> To "remember" version numbers, Pants uses the <em>pushdb</em>.
The pushdb is a text file under source control. It lists artifacts with
their current version numbers and SHAs. When you publish artifacts,
pants edits this file and pushes it to the origin.</p>
<p><a id="setup_publish" pantsmark="setup_publish"></a></p>
<h2 id="enabling-pants-publish">Enabling Pants Publish</h2>
<h3 id="tell-pants-about-your-artifact-repository">Tell Pants about your Artifact Repository</h3>
<p>To tell Pants which artifact repository to publish to, <a href="howto_plugin.html">Create a
plugin</a> if you haven't already. Register it with Pants.</p>
<p>In the plugin, define and register at least one <code>Repository</code> object in a <code>BUILD</code> file alias as
shown in
<a href="https://github.com/pantsbuild/pants/blob/master/src/python/internal_backend/repositories/register.py"><code>src/python/internal_backend/repositories/register.py</code></a>.</p>
<p><code>BUILD</code> targets can use this Repository's alias as the <code>repo</code> parameter to an <a href="build_dictionary.html#bdict_artifact" pantsref="bdict_artifact"><code>artifact</code></a>. For example,
<a href="https://github.com/pantsbuild/pants/blob/master/examples/src/java/org/pantsbuild/example/hello/greet/BUILD">examples/src/java/org/pantsbuild/example/hello/greet/BUILD</a>
refers to the <code>public</code> repository defined above. (Notice it's a Python object, not a string.)</p>
<p>
<div class="md-included-snippet"><div class="codehilite"><pre><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>If you get an error that the repo name (here, <code>public</code>) isn't defined, your plugin didn't register
with Pants successfully. Make sure you bootstrap Pants in a way that loads your <code>register.py</code>.</p>
<p>In your <code>pants.ini</code> file, set up a <code>[publish.jar]</code> section. In that section,
create a <code>dict</code> called <code>repos</code>. It should contain a section for each <code>Repository</code> object that you
defined in your plugin:</p>
<div class="codehilite"><pre><span class="k">[publish.jar]</span>
<span class="err">repos:</span> <span class="err">{</span>
<span class="err">'public':</span> <span class="err">{</span> <span class="c"># must match the name of the `Repository` object that you defined in your plugin.</span>
<span class="err">'resolver':</span> <span class="err">'maven.example.com',</span> <span class="c"># must match hostname in ~/.netrc and the <url> parameter</span>
<span class="c"># in your custom ivysettings.xml.</span>
<span class="err">'auth':</span> <span class="err">'build-support:netrc',</span> <span class="c"># Pants spec to a 'credentials()' or</span>
<span class="c"># 'netrc_credentials()' object.</span>
<span class="err">'help':</span> <span class="err">'Configure</span> <span class="err">your</span> <span class="err">~/.netrc</span> <span class="err">for</span> <span class="err">maven.example.com</span> <span class="err">access.'</span>
<span class="err">},</span>
<span class="err">'testing':</span> <span class="err">{</span>
<span class="err">'resolver':</span> <span class="err">'artifactory.example.com',</span>
<span class="err">'auth':</span> <span class="err">'build-support:netrc',</span>
<span class="err">'help':</span> <span class="err">'Configure</span> <span class="err">your</span> <span class="err">~/.netrc</span> <span class="err">for</span> <span class="err">artifactory.example.com</span> <span class="err">access.'</span>
<span class="err">},</span>
<span class="err">}</span>
</pre></div>
<p>If your repository requires authentication, add a <code>~/.netrc</code> file. Here is a sample file, that
matches the <code>repos</code> specified above:</p>
<div class="codehilite"><pre>machine maven.example.com
login someuser
password password123
machine artifactory.example.com
login someuser
password someotherpassword123
</pre></div>
<p>And place the following in a <code>BUILD</code> file somewhere in your repository (<code>build-support/BUILD</code> is a
good place, and is used in the example above):</p>
<div class="codehilite"><pre>netrc_credentials(name = 'netrc')
</pre></div>
<p>Next, tell Ivy how to publish to your repository. Add a new <code>ivysettings.xml</code> file to your repo
with the additional information needed to publish artifacts. Here is an example to get you started:</p>
<div class="codehilite"><pre><span class="cp"><?xml version="1.0"?></span>
<span class="nt"><ivysettings></span>
<span class="nt"><settings</span> <span class="na">defaultResolver=</span><span class="s">"chain-repos"</span><span class="nt">/></span>
<span class="c"><!-- The ${login} and ${password} values come from a netrc_credentials() object in a BUILD</span>
<span class="c"> file, which is fed by '~/.netrc'. There must be a '~/.netrc' machine entry which</span>
<span class="c"> matches a resolver in the "repos" object in 'pants.ini', which also matches the 'host' in</span>
<span class="c"> this XML block.</span>
<span class="c"> machine <hostname></span>
<span class="c"> login <login></span>
<span class="c"> password <password></span>
<span class="c"> The realm must match the kind of repository you are publishing to. For Sonotype Nexus, use:</span>
<span class="c"> realm="Sonatype Nexus Repository Manager"</span>
<span class="c"> --></span>
<span class="nt"><credentials</span> <span class="na">host=</span><span class="s">"artifactory.example.com"</span>
<span class="na">realm=</span><span class="s">"Artifactory Realm"</span>
<span class="na">username=</span><span class="s">"${login}"</span>
<span class="na">passwd=</span><span class="s">"${password}"</span><span class="nt">/></span>
<span class="nt"><resolvers></span>
<span class="nt"><chain</span> <span class="na">name=</span><span class="s">"chain-repos"</span> <span class="na">returnFirst=</span><span class="s">"true"</span><span class="nt">></span>
<span class="nt"><ibiblio</span> <span class="na">name=</span><span class="s">"artifactory.example.com"</span>
<span class="na">m2compatible=</span><span class="s">"true"</span>
<span class="na">usepoms=</span><span class="s">"true"</span>
<span class="na">root=</span><span class="s">"https://artifactory.example.com/content/groups/public/"</span><span class="nt">/></span>
<span class="nt"></chain></span>
<span class="nt"><url</span> <span class="na">name=</span><span class="s">"artifactory.example.com"</span> <span class="na">m2compatible=</span><span class="s">"true"</span><span class="nt">></span>
<span class="nt"><artifact</span> <span class="na">pattern=</span><span class="s">"https://artifactory.example.com/libs-releases-local/[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]"</span><span class="nt">/></span>
<span class="nt"></url></span>
<span class="nt"></resolvers></span>
<span class="nt"></ivysettings></span>
</pre></div>
<p>With this file in place, add a <code>[publish.jar]</code> section to <code>pants.ini</code>, and tell pants to use
the custom Ivy settings when publishing:</p>
<div class="codehilite"><pre><span class="k">[publish.jar]</span>
<span class="err">ivy_settings:</span> <span class="err">%(pants_supportdir)s/ivy/ivysettings_for_publishing.xml</span>
</pre></div>
<p><a id="setup_publish_restrict_branch" pantsmark="setup_publish_restrict_branch"> </a></p>
<h3 id="restricting-publish-to-release-branch">Restricting Publish to "Release Branch"</h3>
<p>Your organization might have a notion of a special "release branch": you want publishing
to happen on this source control branch, which you maintain extra-carefully.
You can set this branch using the <code>restrict_push_branches</code> option in the
<code>[publish.jar]</code> section of your <code>pants.ini</code> file.</p>
<h3 id="task-to-publish-extra-artifacts">Task to Publish "Extra" Artifacts</h3>
<p>Pants supports "publish plugins", which allow end-users to add additional, arbitrary files to be
published along with the primary artifact. For example, let's say that along with publishing your
jar full of class files, you would also like to publish a companion file that contains some
metadata -- code coverage info, source git repository, java version that created the jar, etc. By
<a href="dev_tasks.html">developing a task</a> in a
<a href="howto_plugin.html">plugin</a>, you give Pants a new ability. <a href="dev_tasks_publish_extras.html">Develop a
Task to Publish "Extra" Artifacts</a> to find
out how to develop a special Task to include "extra" data with published artifacts.</p>
<h2 id="life-of-a-publish">Life of a Publish</h2>
<p>To publish a library's artifact, Pants bumps the version number and
uploads the artifact to a repository. When things go smoothly, that's
all you need to know. When things go wrong, it's good to know details.</p>
<ul>
<li>
<p>Pants decides the version number to use based on pushdb's state.</p>
<p>You can override the version number[s] to use via a command-line
flag. Pants does some sanity-checking: If you specify an override
version less than or equal to the last-published version (as noted
in the pushdb), Pants balks.</p>
</li>
<li>
<p>For each artifact to be published, it prompts you for confirmation.
(This is a chance for you to notice that you want to, e.g., bump an
artifact's minor revision instead of patch revision.)</p>
</li>
<li>
<p>Invokes a tool to upload the artifact to a repository. (For JVM
artifacts, this tool is Ivy.)</p>
</li>
<li>
<p>Commits pushdb.</p>
</li>
</ul>
<p>Things can go wrong; you can recover:</p>
<ul>
<li>Uploading the artifact can fail for reasons you might expect for an
upload: authentication problems, transient connection problems, etc.</li>
<li>
<p>Uploading the artifact can fail for another reason: that
artifact+version already exists on the server. <em>In theory</em>, this
shouldn't happen: Pants bumps the version it found in the pushdb.
But in practice, this can happen.</p>
<div class="codehilite"><pre>Exception in thread "main" java.io.IOException: destination file exists and overwrite == false
...
FAILURE: java -jar .../ivy/lib/ivy-2.2.0.jar ... exited non-zero (1) 'failed to push com.twitter#archimedes_common;0.0.42'
</pre></div>
<p>This is usually a sign that something strange happened in a
<em>previous</em> publish. Perhaps someone published an artifact "by hand"
instead of using Pants. Perhaps someone used Pants to publish an
artifact but it failed to update the pushdb in source control. E.g.,
merge conflicts can happen, and folks don't always recover from them
correctly.</p>
<p>In this situation, you probably want to pass <code>publish --overrride=<version></code> to specify a
version to use instead of the automatically-computed already-existing version. Choose a version
that's not already on the server. Pants records this version in the pushdb, so hopefully the
next publisher won't have the same problem.</p>
<p>Perhaps you are "racing" a colleague and just lost the race: they
published an artifact with that name+version.</p>
<p>In this situation, you probably want to refresh your source tree
(<code>git pull</code> or equivalent) to get the latest version of the pushdb
and try again.</p>
</li>
<li>
<p>Pushing the pushdb to origin can fail, even though
artifact-uploading succeeded. Perhaps you were publishing at about
the same time someone else was; you might get a merge conflict when
trying to push.</p>
<p>(There's a temptation to ignore this error: the artifact uploaded
OK; nobody expects a git merge conflict when publishing. Alas,
ignoring the error now means that your <em>next</em> publish will probably
fail, since Pants has lost track of the current version number.)</p>
<p>See: <a href="publish.html#publish_pushdb_push" pantsref="publish_pushdb_push">Troubleshoot a Failed Push to Origin</a></p>
</li>
</ul>
<h2 id="how-to">How To</h2>
<ul>
<li>Does your organization enforce a special branch for publishing?
(E.g., perhaps publishing is only allowed on the <code>master</code> branch.)
If so, be on that branch with no changes.</li>
<li>Consider trying a local publish first. This lets you test the
to-be-published artifact. See
<a href="publish.html#publish_local_test" pantsref="publish_local_test">Test with a Fake Local "Publish"</a>.</li>
<li>Start the publish:
<code>./pants publish.jar --no-dryrun [target]</code> Don't wander
off; Pants will ask for confirmation as it goes (making sure you
aren't publishing artifact[s] you didn't mean to).</li>
</ul>
<h2 id="restricting-to-release-branch">Restricting to "Release Branch"</h2>
<p>Your organization might have a notion of a special "release branch": you
want all publishing to happen on this source control branch, which you
maintain extra-carefully. You can
<a href="publish.html#setup_publish_restrict_branch" pantsref="setup_publish_restrict_branch">configure your repo so that the
<code>publish</code> goal only allows <code>publish</code>-ing from this special branch</a>.</p>
<h2 id="authenticating-to-the-artifact-repository">Authenticating to the Artifact Repository</h2>
<p>Your artifact repository probably doesn't accept anonymous uploads; you probably need to
authenticate to it (prove that you are really you). Depending on how the artifact repository is
configured, Pants might need to interact with an authentication system. (Or it might not. E.g., if
your system uses Kerberos, when Pants invokes artifact-upload commands, Kerberos tickets should
work automatically).</p>
<p>Your Pants administrator will handle configuring Pants to submit credentials to the artifact
repository. As a user, if Pants needs to provide your username and password, you can enable this
via Pants' <code>.netrc</code> support. Pants can parse <a href="http://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-File.html">.netrc
files</a> to get your
username and password to an artifact repository server. Here is an example file:</p>
<div class="codehilite"><pre>machine maven.example.com
login sandy
password myamazingpa$sword
</pre></div>
<p>Check with your Pants administrator for the proper hostname to use for the "machine" entry.</p>
<h2 id="troubleshooting">Troubleshooting</h2>
<p>Sometimes publishing doesn't do what you want. The fix usually involves publishing again, perhaps
passing <code>--override</code> (override the version number to use), <code>--force</code>, and/or <code>--restart-at</code>. The
following are some usual symptoms/questions:</p>
<p><a id="publish_version_exists" pantsmark="publish_version_exists"></a></p>
<h3 id="versioned-artifact-already-exists">Versioned Artifact Already Exists</h3>
<p>Pants attempted to compute the new version number to use based on the
contents of the pushdb; but apparently, someone previously published
that version of the artifact without updating the pushdb.</p>
<p>Examine the publish repo to find out what version number you actually
want to use. E.g., if you notice that versions up to 2.5.7 exist and you
want to bump the patch version, you want to override the default version
number and use 2.5.8 instead.</p>
<p>Try publishing again, but pass <code>--override</code> to specify the version number to use instead of
incrementing the version number from the pushdb. Be sure to use a version number that has not
already been published this time. For example, to override the default publish version number for
the <code>org.archie</code> buoyancy artifact, you might pass
<code>publish --override=org.archie#buoyancy=2.5.8</code>.</p>
<p><a id="publish_pushdb_push" pantsmark="publish_pushdb_push"></a></p>
<h3 id="failed-to-push-to-origin">Failed to Push to Origin</h3>
<p>You might successfully publish your artifact but then fail to push your pushdb change to origin:</p>
<div class="codehilite"><pre>To https://git.archimedes.org/owls
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'https://git.archimedes.org/owls'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
</pre></div>
<p>For some reason, git couldn't merge your branch (with the pushdb change)
to the branch on origin. This might happen, for example, if you were
"racing" someone else; they perhaps pushed their change to master's
pushdb before you could. But it can also happen for other reasons; any
local change that can't be merged to the branch on origin.</p>
<p>You are now in a bad state: you've pushed some artifacts, but the pushdb
doesn't "remember" them.</p>
<ul>
<li>Look at the pushdb's source control history to if someone made a
conflicting publish. If so, contact them. (You're about to try to
fix the problem; if they also encountered problems, they are
probably also about to fix the problem. You might want to coordinate
and take turns.)</li>
</ul>
<p><strong>Resetting to try again</strong></p>
<p>In git, this might mean:</p>
<div class="codehilite"><pre>git reset origin/master # (if ``master`` is your release branch)
git pull origin master
./pants publish.jar <your previous args>
</pre></div>
<p>Since you uploaded new versioned artifacts but the reset pushdb doesn't "remember" that, you might
get "Versioned Artifact Already Exists" errors: see the section above and use <code>--override</code> to
set version numbers to avoid these.</p>
<p><a id="publish_no_provides" pantsmark="publish_no_provides"></a></p>
<h3 id="does-not-provide-an-artifact">Does not provide an artifact</h3>
<p>A published artifact lives at a set of coordinates. For Pants to publish
an artifact, it needs to know the artifact's coordinates. Pants gets the
coordinates from the target's <code>provides</code> parameter. Thus, if you try to
publish a target that depends on a target that has no <code>provides</code>, Pants
doesn't know what to do. It stops:</p>
<div class="codehilite"><pre>FAILURE: The following errors must be resolved to publish.
Cannot publish BuildFileAddress(/Users/archie/workspace/buoyancy/client/src/main/scala/com/bu
oyancy/client/BUILD, client) due to:
BuildFileAddress(/Users/archie/workspace/buoyancy/client/src/main/scala/com/buoyancy/client
/model/BUILD, model) - Does not provide an artifact.
</pre></div>
<p>The solution is to add a <code>provides</code> to the target that lacks one.</p>
<p>Remember, to publish a target, the target's dependencies must also be
published. If any of those dependencies have changed since their last
publish, Pants tries to publish them before publishing the target you
specify. Thus, you might need to add a <code>provides</code> to one or more of
these.</p>
<h3 id="silently-does-not-publish">Silently does not publish</h3>
<p>A published artifact lives at a set of coordinates. For Pants to publish
an artifact, it needs to know the artifact's coordinates. Pants gets the
coordinates from the target's <code>provides</code> parameter. Thus, if you try to
publish a target that has no <code>provides</code>, Pants doesn't try. If the
target depends on <em>other</em> targets that <em>do</em> provide artifacts, Pants
might publish those. This is a case of
<a href="first_tutorial.html#tut_goal_target_mismatch" pantsref="tut_goal_target_mismatch">goal-target mismatch</a>
To fix this, set <code>provides</code> correctly.</p>
<h2 id="want-to-publish-something-publish-many-things">Want to Publish Something? Publish Many Things</h2>
<p>If you publish a library that depends on others, you want to publish
them together. Conversely, if you publish a low-level library that other
libraries depend upon, you want to publish those together, too. Thus, if
you want to publish one thing, you may find you should publish many
things. Pants eases <em>part</em> of this: if you publish a library, it
automatically prompts you to also publish depended-upon libraries whose
source code changed. However, Pants does <em>not</em> automatically publish
dependees of a depended-upon library. If you know you're about to
publish a low-level library (perhaps via a "dry run" publish), you can
use Pants' <code>dependees</code> to find other things to publish.</p>
<p>For example, suppose your new library <code>high-level</code> depends on another
library, <code>util</code>. If you tested <code>high-level</code> with <code>util</code> version 1.2, you
want <code>util</code> 1.2 published and available to <code>high-level</code> consumers. Once
you publish <code>util</code> version 1.2, people might use it. If you previously
published your <code>another-high-level</code> library library depending on <code>util</code>
version 1.1, <code>another-high-level</code> consumers (who might also consume
<code>high-level</code>) might pick up version 1.2 and be sad to find out that
<code>other-high-level</code> doesn't work with the new <code>util</code>.</p>
<p>In this example, when you publish <code>high-level</code>, Pants knows to also
publish <code>util</code>. If Pants publishes <code>util</code>, it does <em>not</em> automatically
try to publish <code>high-level</code> or <code>other-high-level</code>.</p>
<p><a id="publish_local_test" pantsmark="publish_local_test"></a></p>
<h2 id="test-with-a-fake-local-publish">Test with a Fake Local "Publish"</h2>
<p>The whole reason you publish an artifact so that other codebases can use
it. Before you really publish, you might want to fake-publish an
artifact: generate it and put it someplace a place in your development
machine; then use that artifact from another codebase.</p>
<p>For example, your other codebase might use Maven to build, perhaps with
Maven configured to use <code>~/.m2/repository</code> as a local repo. You can make
pants publish to that local repo with:</p>
<div class="codehilite"><pre>./pants publish.jar --no-dryrun --local<span class="o">=</span>~/.m2/repository
</pre></div>
<p>In the other codebase, change the dependencies to pull in the new
artifact.</p>
<p>If your other codebase <em>also</em> uses Pants build, you can depend on the
locally-published artifact. If the artifact is a jar, then in the
3rdparty
<a href="build_dictionary.html#bdict_jar" pantsref="bdict_jar"><code>jar</code> target</a>, set <code>mutable=True</code> and change the
version number.</p>
<!-- main content end -->
<div class="generated">
Generated by <a href="docs.html">publish_docs</a>
from dist/markdown/html/examples/src/java/org/pantsbuild/example/publish.html 2017-05-29T10:30:50.875576
</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>