forked from pantsbuild/pantsbuild.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
go_readme.html
596 lines (565 loc) · 31.1 KB
/
go_readme.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
<!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>Go support for Pants</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/go_readme.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 ">
<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 toc-here">
Go support for Pants
</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="#installation">Installation</a></li>
<li class="toc-h1"><a href="#codebase-requirements">Codebase requirements</a></li>
<li class="toc-h1"><a href="#codebase-setup">Codebase setup</a></li>
<li class="toc-h2"><a href="#source-root-configuration">Source root configuration</a></li>
<li class="toc-h2"><a href="#build-seeding">BUILD seeding</a></li>
<li class="toc-h2"><a href="#dependency-metadata-generation">Dependency metadata generation</a></li>
<li class="toc-h1"><a href="#codebase-maintenance">Codebase maintenance</a></li>
<li class="toc-h1"><a href="#building">Building</a></li>
<li class="toc-h1"><a href="#testing">Testing</a></li>
<li class="toc-h1"><a href="#working-with-other-go-ecosystem-tools">Working with other Go ecosystem tools</a></li>
<li class="toc-h2"><a href="#go">go</a></li>
<li class="toc-h2"><a href="#go-env">go-env</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="go-support-for-pants">Go support for Pants</h1>
<p>The Go plugin for Pants supports compilation and testing of Go code as well as third-party versioned
dependency management without vendoring, and other utilities to make working with existing go
tooling easier.</p>
<h2 id="installation">Installation</h2>
<p>Go support is provided by a plugin distributed to
<a href="https://pypi.python.org/pypi/pantsbuild.pants.contrib.go">pypi</a>.
Assuming you have already <a href="http://www.pantsbuild.org/install.html">installed pants</a>, you'll need to
add the Go plugin in your <code>pants.ini</code>, like so:</p>
<div class="codehilite"><pre><span class="k">[GLOBAL]</span>
<span class="err">pants_version:</span> <span class="err">1.0.0</span>
<span class="err">plugins:</span> <span class="err">[</span>
<span class="na">'pantsbuild.pants.contrib.go</span><span class="o">=</span><span class="s">=%(pants_version)s',</span>
<span class="s"> ]</span>
</pre></div>
<p>On your next run of <code>./pants</code> the plugin will be installed and you'll find these new goals:</p>
<div class="codehilite"><pre>./pants goals
Installed goals:
...
go: Runs an arbitrary go command against zero or more go targets.
go-env: Runs an arbitrary command in a go workspace defined by zero or more go targets.
...
</pre></div>
<h2 id="codebase-requirements">Codebase requirements</h2>
<p>Pants aims to control your Go workspace to provide guarantees of pinned 3rdparty dependencies (much
as tools like <a href="https://github.com/tools/godep">GoDep</a>) and proper change invalidation. In order to
do this, there are a few requirements on your code layout and a few changes you'll need to make in
your Go development workflow.</p>
<p>Pants requires:</p>
<ol>
<li>You have one Go source tree.</li>
<li>You tell Pants about your Go source code packages using BUILD file targets.</li>
<li>You declare 3rdparty dependencies in BUILD files that pin the version of the dependency.</li>
</ol>
<p>You likely comply with 1 already, the Go standards push almost all projects in this direction, but 2
and 3 may be new concepts if you haven't used Pants or a tool like it before. You may want to read
up on <a href="build_files.html">BUILD files</a> and the <a href="3rdparty.html">3rdparty pattern</a>
before continuing.</p>
<h2 id="codebase-setup">Codebase setup</h2>
<p>Pants has tooling to help maintain your Go BUILD files, but it may need
some configuration and seeding to work.</p>
<h3 id="source-root-configuration">Source root configuration</h3>
<p>Internally, pants uses the concept of a "source root" to determine the portion of a source file's
path that represents the package for the language in question. </p>
<p>Pants attempts to guess where your source roots are via pattern matching. For example, it assumes
by default that <code>src/*</code> and <code>src/main/*</code>, where <code>*</code> is some language name, are possible source
roots for that language. </p>
<p>However when it comes to Go, <code>src/go</code> is probably not the correct source root. For Go code in a
standard multi-language repo layout, <code>src/go</code> is probably on the $GOPATH, which means that
<code>src/go/src</code> is the actual source root. </p>
<p>Pants corrects for this in the case of its default patterns: It will correctly detect
that <code>src/go/src</code> and <code>src/main/go/src</code> are the possible source roots for Go. </p>
<p>But if your Go code does not live in one of these locations then you'll need to tell Pants where
to find it, e.g., by adding this to <code>pants.ini</code>:</p>
<div class="codehilite"><pre><span class="k">[source]</span>
<span class="err">source_roots:</span> <span class="err">{</span>
<span class="err">'my/custom/path/go/src':</span> <span class="k">['go']</span>
<span class="err">}</span>
</pre></div>
<p>This tells pants that the <code>src/go/src</code> source root houses one type of code, Go code.</p>
<p>You can inspect Pants' source root guesses with:</p>
<div class="codehilite"><pre>./pants roots
src/go/src: go
src/java: java
...
</pre></div>
<p>Unless your Go code has no 3rdparty dependencies, we also need to seed a source root where 3rdparty
dependency version information can be stored. We can seed this with <code>mkdir -p 3rdparty/go</code> and check
Pants knowledge of the new source root:</p>
<div class="codehilite"><pre>src/go/src: go
src/java: java
3rdparty/go: go
</pre></div>
<h3 id="build-seeding">BUILD seeding</h3>
<p>You'll need to write minimal BUILD files for all the root binaries and libraries you intend to
build. For each binary, just place a BUILD file in the <code>main</code>'s package dir with contents
<code>go_binary()</code>. Likewise, for libraries you'll need a BUILD file with contents <code>go_library()</code>. You
might even automate this by running the following from the root of your Go source tree:</p>
<div class="codehilite"><pre><span class="nv">GOPATH</span><span class="o">=</span><span class="nv">$PWD</span> go list -f <span class="s1">'{{.Dir}} {{.Name}}'</span> ./... | <span class="k">while </span><span class="nb">read </span>dir name
<span class="k">do</span>
<span class="k"> if</span> <span class="o">[[</span> <span class="s2">"${name}"</span> <span class="o">==</span> <span class="s2">"main"</span> <span class="o">]]</span>
<span class="k">then</span>
<span class="k"> </span><span class="nb">echo</span> <span class="s2">"go_binary()"</span> > <span class="s2">"${dir}/BUILD"</span>
<span class="k">else</span>
<span class="k"> </span><span class="nb">echo</span> <span class="s2">"go_library()"</span> > <span class="s2">"${dir}/BUILD"</span>
<span class="k">fi</span>
<span class="k">done</span>
</pre></div>
<h3 id="dependency-metadata-generation">Dependency metadata generation</h3>
<p>Now that we have roper source root configuration and skeleton BUILD files, we can proceed to
auto-generate the dependency information pants needs from BUILD files using the <code>buildgen</code> goal.
Here we set options to emit the BUILD files to disk, include 3rdparty remote dependency BUILD
files, and fail if any 3rdparty dependencies have un-pinned versions:</p>
<div class="codehilite"><pre>./pants buildgen.go --materialize --remote --fail-floating
...
12:43:08 00:00 [buildgen]
12:43:08 00:00 [go]..
src/go/src/server/BUILD (server)
3rdparty/go/github.com/gorilla/mux/BUILD (github.com/gorilla/mux) FLOATING
Un-pinned (FLOATING) Go remote library dependencies are not allowed in this repository!
Found the following FLOATING Go remote libraries:
3rdparty/go/github.com/gorilla/mux/BUILD (github.com/gorilla/mux) FLOATING
You can fix this by editing the target in each FLOATING BUILD file listed above to include a `rev` parameter that points to a sha, tag or commit id that pins the code in the source repository to a fixed, non-FLOATING version.
FAILURE: Un-pinned (FLOATING) Go remote libraries detected.
</pre></div>
<p>The output shows one local target was (re)generated and one 3rdparty target was generated, but with
no version picked.</p>
<p>The local target now looks like:</p>
<div class="codehilite"><pre>cat src/go/src/server/BUILD
# Auto-generated by pants!
# To re-generate run: `pants buildgen.go --materialize --remote`
go_binary(
dependencies=[
'3rdparty/go/github.com/gorilla/mux',
]
)
</pre></div>
<p>And the 3rdparty target:</p>
<div class="codehilite"><pre>cat 3rdparty/go/github.com/gorilla/mux/BUILD
# Auto-generated by pants!
# To re-generate run: `pants buildgen.go --materialize --remote`
go_remote_library()
</pre></div>
<p>To fix the <code>FLOATING</code> version error we can edit like so:</p>
<div class="codehilite"><pre>git diff -U1 3rdparty/go/github.com/gorilla/mux/BUILD
<span class="gh">diff --git a/3rdparty/go/github.com/gorilla/mux/BUILD b/3rdparty/go/github.com/gorilla/mux/BUILD</span>
<span class="gh">index 5d283d4..38ed297 100644</span>
<span class="gd">--- a/3rdparty/go/github.com/gorilla/mux/BUILD</span>
<span class="gi">+++ b/3rdparty/go/github.com/gorilla/mux/BUILD</span>
<span class="gu">@@ -3,2 +3,2 @@</span>
<span class="gd">-go_remote_library()</span>
<span class="gi">+go_remote_library(rev='v1.1')</span>
</pre></div>
<p>Here we've used the <code>v1.1</code> tag of the <code>github.com/gorilla/mux</code> project, but we could also use a sha
or branch name (not reccomended since branches can float).</p>
<p>Re-running buildgen finds success:</p>
<div class="codehilite"><pre>./pants buildgen.go --materialize --remote --fail-floating
...
12:53:27 00:00 [buildgen]
12:53:27 00:00 [go]..
src/go/src/server/BUILD (server)
3rdparty/go/github.com/gorilla/mux/BUILD (github.com/gorilla/mux) v1.1
12:53:27 00:00 [complete]
SUCCESS
</pre></div>
<p>A compile fails though!:</p>
<div class="codehilite"><pre>...
22:44:57 00:00 [resolve]
22:44:57 00:00 [ivy]
22:44:57 00:00 [cache]
22:44:57 00:00 [bootstrap-nailgun-server]
22:44:57 00:00 [go]
22:44:57 00:00 [cache]
No cached artifacts for 1 target.
Invalidated 1 target.INFO] Downloading https://github.com/gorilla/mux/archive/v1.1.tar.gz...
22:45:00 00:03 [github.com/gorilla/mux]WARN] Injecting dependency from BuildFileAddress(BuildFile(3rdparty/go/github.com/gorilla/mux/BUILD, FileSystemProjectTree(/home/jsirois/dev/pantsbuild/issues-3417)), mux) on 3rdparty/go/github.com/gorilla/context:context, but the dependency is not in the BuildGraph. This probably indicates a dependency cycle, but it is not an error until sort_targets is called on a subgraph containing the cycle.
3rdparty/go/github.com/gorilla/mux has remote dependencies which require local declaration:
--> github.com/gorilla/context (expected go_remote_library declaration at 3rdparty/go/github.com/gorilla/context)
FAILURE: Failed to resolve transitive Go remote dependencies.
</pre></div>
<p>Here we see a failure resolving the transitive 3rdparty <code>github.com/gorilla/context</code> dependency that
our explicit dependency on <code>github.com/gorilla/mux</code> requires. The lesson here is that <code>buildgen</code>
doesn't attempt to resolve or compile code, it only operates on code and BUILD files already on
disk. We can proceed though by following the instructions in the resolve failure:</p>
<div class="codehilite"><pre>mkdir -p 3rdparty/go/github.com/gorilla/context
echo "go_remote_library()" > 3rdparty/go/github.com/gorilla/context/BUILD
</pre></div>
<p>Since we have not picked a version for this new (transitive) dependency, <code>buildgen</code> will fail,
asking us to pick one:</p>
<div class="codehilite"><pre>./pants buildgen.go --materialize --remote --fail-floating
...
22:45:52 00:00 [buildgen]
22:45:52 00:00 [go].
3rdparty/go/github.com/gorilla/mux/BUILD (github.com/gorilla/mux) v1.1
3rdparty/go/github.com/gorilla/context/BUILD (github.com/gorilla/context) FLOATING
src/go/src/server/BUILD (src/server)
Un-pinned (FLOATING) Go remote library dependencies are not allowed in this repository!
Found the following FLOATING Go remote libraries:
3rdparty/go/github.com/gorilla/context/BUILD (github.com/gorilla/context) FLOATING
You can fix this by editing the target in each FLOATING BUILD file listed above to include a `rev` parameter that points to a sha, tag or commit id that pins the code in the source repository to a fixed, non-FLOATING version.
FAILURE: Un-pinned (FLOATING) Go remote libraries detected.
22:45:53 00:01 [complete]
FAILURE
</pre></div>
<p>And at this point we are back on familiar ground. We can edit
<code>3rdparty/go/github.com/gorilla/context/BUILD</code> and provide a version and repeat <code>compile</code> and
<code>buildgen</code> until we have a fully pinned, explicit 3rparty dependency set and compiling codebase.
At this point the generated BUILD files can be checked in.</p>
<h2 id="codebase-maintenance">Codebase maintenance</h2>
<p>When new packages are added or existing packages' dependencies are modified a similar seeding (only
needed if the packages are new roots), buildgen and compilation can be cycled through. To simplify
the process it's recommended the flags be made defaults for the repo by editing your pants init to
include the following section:</p>
<div class="codehilite"><pre><span class="k">[buildgen.go]</span>
<span class="c"># We always want buildgen to materialize BUILD files on disk as well as handle seeding remotes</span>
<span class="c"># when new ones are encountered. We also never want to allow FLOATING revs, they should be pinned</span>
<span class="c"># right away.</span>
<span class="err">materialize:</span> <span class="err">True</span>
<span class="err">remote:</span> <span class="err">True</span>
<span class="err">fail_floating:</span> <span class="err">True</span>
</pre></div>
<p>Now running buildgen is just <code>./pants buildgen</code>.</p>
<h2 id="building">Building</h2>
<p>You can build your code with <code>./pants compile [go targets]</code>. This will operate in a pants controlled
(and hidden) workspace that knits together your local Go source with fetched, versioned third party
code.</p>
<p>Since the workspaces constructed by pants internally for compilation are hidden, they aren't useful
for retrieving final products. To surface a binary for use in deploys or ad-hoc testing you can
<code>./pants binary [go binary targets]</code>. This will re-use any progress made by <code>./pants compile</code> in its
Pants-controlled workspace and the binaries will be emitted under the <code>dist/go/bin/</code> directory by
default.</p>
<h2 id="testing">Testing</h2>
<p>You can run your Go tests with <code>./pants test [go targets]</code>. Any
<a href="https://golang.org/pkg/testing/">standard Go tests</a> found amongst the targets will be compiled and
run with output sent to the console.</p>
<h2 id="working-with-other-go-ecosystem-tools">Working with other Go ecosystem tools</h2>
<p>Go and the Go ecosystem provide rich tool support. From native Go tools like <code>go list</code> and <code>go vet</code>
to editors like <code>vim</code> and <a href="https://www.sublimetext.com/">Sublime</a> that have plugins supporting Go
symbol resolution and more. These tools all rely on a <code>GOROOT</code> and a <code>GOPATH</code> to know where to find
binaries and code to operate against. Since pants controls the Go workspace these tools are
unuseable without knowledge of the Pants-synthesized workspaces. The <code>./pants go</code> and
<code>./pants go-env</code> goals can help use or integrate with these tools.</p>
<h3 id="go">go</h3>
<p>The <code>./pants go</code> command can be considered the equivalent of running <code>go</code> with a few differences.
This is particularly useful when Pants doesn't provide a goal that maps to the <code>go</code> command you
already know you want to run.</p>
<p>Running the command with no extra arguments is instructive:</p>
<div class="codehilite"><pre>./pants go
FAILURE: The pants `{goal}` goal expects at least one go target and at least one pass-through argument to be specified, call with:
./pants go [missing go targets] -- [missing pass-through args]
FAILURE
</pre></div>
<p>So, where you might run <code>go list -f '{{.Imports}}' server</code> to list the server package's imports, you'd instead run:</p>
<div class="codehilite"><pre>./pants go src/go/src/server -- list -f '{{.Imports}}'
[fmt github.com/gorilla/mux html net/http]
</pre></div>
<p>Currently, although Pants checks go formatting via the <code>checkstyle</code> goal, it doesn't offer a way to
automatically fix formatting. You can work around the lack of Pants support for re-formatting via the
following:</p>
<div class="codehilite"><pre>./pants go src/go:: -- fmt ./...
</pre></div>
<h3 id="go-env">go-env</h3>
<p>The <code>./pants go-env</code> is useful for setting the environment some other binary runs in. If you use
Sublime for example, its Go plugins tend to respect the <code>GOROOT</code> and <code>GOPATH</code> environment variables
as the default configuration for said same (vs manual plugin configuration). To run Sublime against
your Pants-managed Go binary and <code>GOPATH</code>, just:</p>
<div class="codehilite"><pre>./pants go-env src/go/src/server -- subl .
</pre></div>
<p>You'll find that, for example, <a href="https://github.com/DisposaBoy/GoSublime">GoSublime</a> will be able to
browse to both local code symbols, 3rdparty Pants-fetched code symbols, and Go std lib symbols in
the Pants-controlled Go distribution.</p>
<p>As a sanity check you can see exactly what is exported:</p>
<div class="codehilite"><pre>./pants go-env src/go/src/server -- set | grep -E ^GO
GOPATH=/home/jsirois/dev/pantsbuild/jsirois-pants2/.pants.d/go-env/go-env/src.server
GOROOT=/home/jsirois/.cache/pants/bin/go/linux/x86_64/1.6.2/unpacked/go
</pre></div>
<!-- main content end -->
<div class="generated">
Generated by <a href="docs.html">publish_docs</a>
from dist/markdown/html/contrib/go/README.html 2017-05-29T10:30:50.486220
</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>