Set up minimal Go project (#2)

A simple "Hello world" project. 

We use the popular directory structure of putting all binaries in `cmd/` and library code in `pkg/`. To keep the example simple, the binaries are simply hello world in English and Spanish.

Demos internal and external tests, but not benchmarks and examples (even though these are supported).

Author: Eric-Arellano

.github/workflows/pants.yaml

@@ -29,10 +29,24 @@ jobs:
           ~/.cache/pants/lmdb_store
           ~/.cache/pants/named_caches
         key: ${{ runner.os }}-
+    - name: Install Go
+      uses: actions/setup-go@v2
+      with:
+        go-version: 1.17.1
     - name: Bootstrap Pants
       run: ./pants --version
     - name: Check Pants config files
       run: ./pants tailor --check update-build-files --check
+    - name: Lint and compile
+      run: ./pants lint check '::'
+    - name: Test
+      run: ./pants test '::'
+    - name: Package / Run
+      run: |
+        # We also smoke test that our release process will work by running `package`.
+        ./pants package ::
+        ./pants run cmd/greeter_en:
+        ./pants run cmd/greeter_es:
     - name: Upload Pants log
       uses: actions/upload-artifact@v2
       with:

BUILD

@@ -0,0 +1,7 @@
+# Copyright 2021 Pants project contributors.
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+# This target teaches Pants about our Go module, including its third-party modules.
+go_mod(
+    name="mod",
+)

README.md

@@ -1 +1,115 @@
 # example-golang
+
+An example repository to demonstrate Pants's experimental Golang support.
+
+See [] for some unique benefits Pants brings to Golang repositories, and see
+[pantsbuild.org/docs/go-overview](https://www.pantsbuild.org/v2.8/docs/go-overview) for much more detailed
+documentation.
+
+This is only one possible way of laying out your project with Pants. See 
+[pantsbuild.org/docs/source-roots#examples](https://www.pantsbuild.org/docs/source-roots#examples) 
+for some other example layouts.
+
+Note: for now, Pants only supports repositories using a single `go.mod`. Please comment on 
+[#13114](https://github.com/pantsbuild/pants/issues/13114) if you need support for greater 
+than one `go.mod` so that we can prioritize adding support.
+
+# Running Pants
+
+You run Pants goals using the `./pants` wrapper script, which will bootstrap the
+configured version of Pants if necessary.
+
+# Goals
+
+Pants commands are called _goals_. You can get a list of goals with
+
+```
+./pants help goals
+```
+
+Most goals take arguments to run on. To run on a single directory, use the directory name with 
+`:` at the end. To recursively run on a directory and all its subdirectories, add `::` to the 
+end.
+
+For example:
+
+```
+./pants lint cmd: internal::
+```
+
+You can run on all changed files:
+
+```
+./pants --changed-since=HEAD lint
+```
+
+You can run on all changed files, and any of their "dependees":
+
+```
+./pants --changed-since=HEAD --changed-dependees=transitive test
+```
+
+# Example Goals
+
+Try these out in this repo!
+
+## Run Gofmt
+
+```
+./pants fmt ::  # Format all packages.
+./pants fmt cmd/greeter_en:  # Format only this package.
+./pants lint pkg::  # Check that all packages under `pkg` are formatted.
+```
+
+## Check compilation
+
+```
+./pants check ::  # Compile all packages.
+./pants check cmd/greeter_en:  # Compile only this package and its transitive dependencies.
+```
+
+## Run tests
+
+```
+./pants test ::  # Run all tests in the repository.
+./pants test pkg/uuid:  # Run all the tests in this package.
+./pants test pkg/uuid: -- -run TestGenerateUuid  # Run just this one test.
+```
+
+## Create a binary file
+
+Writes the result to the `dist/` folder.
+
+```
+./pants package cmd/greeter_en:
+./pants package cmd::  # Create all binaries.
+```
+
+## Run a binary
+
+```
+./pants run cmd/greeter_en:
+./pants run cmd/greeter_es: -- --help
+```
+
+## Determine dependencies
+
+```
+./pants dependencies cmd/greeter_en:
+./pants dependencies --transitive cmd/greeter_en:
+```
+
+## Determine dependees
+
+That is, find what code depends on a particular package(s).
+
+```
+./pants dependees pkg/uuid:
+./pants dependees --transitive pkg/uuid: 
+```
+
+## Count lines of code
+
+```
+./pants count-loc '**/*'
+```

cmd/greeter_en/BUILD

@@ -0,0 +1,10 @@
+# Copyright 2021 Pants project contributors.
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+# This target allows us to use `./pants run` and `./pants package` on this `main` Go package.
+#
+# You can optionally set the field `output_path="greeter_en"`, for example, for the binary's name
+# to be different when running `./pants package`.
+go_binary(
+    name="bin",
+)

cmd/greeter_en/main.go

@@ -0,0 +1,25 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+package main
+
+import (
+	"fmt"
+	"github.com/pantsbuild/example-golang/pkg/greeter"
+	"github.com/spf13/pflag"
+	"os"
+)
+
+const version string = "0.1.0"
+
+func main() {
+	versionOpt := pflag.BoolP("version", "V", false, "print the version and exit")
+	pflag.Parse()
+
+	if *versionOpt {
+		fmt.Println(version)
+		os.Exit(0)
+	}
+
+	fmt.Println(greeter.GreetEnglish("Pantsbuild"))
+}

cmd/greeter_es/BUILD

@@ -0,0 +1,10 @@
+# Copyright 2021 Pants project contributors.
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+# This target allows us to use `./pants run` and `./pants package` on this `main` Go package.
+#
+# You can optionally set the field `output_path="greeter_es"`, for example, for the binary's name
+# to be different when running `./pants package`.
+go_binary(
+    name="bin",
+)

cmd/greeter_es/main.go

@@ -0,0 +1,25 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+package main
+
+import (
+	"fmt"
+	"github.com/pantsbuild/example-golang/pkg/greeter"
+	"github.com/spf13/pflag"
+	"os"
+)
+
+const version string = "0.1.0"
+
+func main() {
+	versionOpt := pflag.BoolP("version", "V", false, "imprimir la versión y salir")
+	pflag.Parse()
+
+	if *versionOpt {
+		fmt.Println(version)
+		os.Exit(0)
+	}
+
+	fmt.Println(greeter.GreetSpanish("Pantsbuild"))
+}

go.mod

@@ -0,0 +1,11 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+module github.com/pantsbuild/example-golang
+
+go 1.17
+
+require (
+	github.com/google/uuid v1.3.0
+	github.com/spf13/pflag v1.0.5
+)

go.sum

@@ -0,0 +1,4 @@
+github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
+github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=

pants.toml

@@ -3,7 +3,11 @@
 
 [GLOBAL]
 pants_version = "2.8.0rc3"
+backend_packages = ["pants.backend.experimental.go"]
 
 [anonymous-telemetry]
 enabled = true
 repo_id = "AE018A26-213E-4B18-99A6-6923EC1E16DE"
+
+[golang]
+expected_version = "1.17"

pkg/greeter/greet.go

@@ -0,0 +1,25 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+package greeter
+
+import (
+	"fmt"
+	"github.com/pantsbuild/example-golang/pkg/uuid"
+)
+
+func GreetEnglish(name string) string {
+	return fmt.Sprintf(
+		"Hello %s!\n\nHere's a UUID to brighten your day: %s",
+		name,
+		uuid.Generate(),
+	)
+}
+
+func GreetSpanish(name string) string {
+	return fmt.Sprintf(
+		"¡Hola %s!\n\nEres muy única, así que te regalamos un UUID: %s",
+		name,
+		uuid.Generate(),
+	)
+}

pkg/greeter/greet_test.go

@@ -0,0 +1,24 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+package greeter_test // That is, an "external test"
+
+import (
+	"github.com/pantsbuild/example-golang/pkg/greeter"
+	"strings"
+	"testing"
+)
+
+func TestEnglish(t *testing.T) {
+	result := greeter.GreetEnglish("testing")
+	if !strings.HasPrefix(result, "Hello testing!") {
+		t.Fail()
+	}
+}
+
+func TestSpanish(t *testing.T) {
+	result := greeter.GreetSpanish("testing")
+	if !strings.HasPrefix(result, "¡Hola testing!") {
+		t.Fail()
+	}
+}

pkg/uuid/uuid_gen.go

@@ -0,0 +1,10 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+package uuid
+
+import "github.com/google/uuid"
+
+func Generate() string {
+	return uuid.NewString()
+}

pkg/uuid/uuid_gen_test.go

@@ -0,0 +1,14 @@
+// Copyright 2021 Pants project contributors.
+// Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+package uuid
+
+import "testing"
+
+func TestGenerateUuid(t *testing.T) {
+	uuid1 := Generate()
+	uuid2 := Generate()
+	if uuid1 == uuid2 {
+		t.Fail()
+	}
+}