Adding first example

This PR includes the source code for the tutorial that is hosted
here: https://bazel-contrib.github.io/SIG-rules-authors/go-tutorial.html

The code for the above html is on the gh-pages branch of the
SIG-rules-authors repository:
https://github.com/bazel-contrib/SIG-rules-authors/tree/gh-pages

This tutorial source code includes:

- basic go rules support
- a basic cobra CLI application
- unit test
- Gazelle support

After this PR is finalized we I will update the tutorial markdown.

We are also adding CI/CD for the example.  This PR modifies the
presubmit.yml file.  This project also uses the words file that
requires the installation of wamerican.

.bazelci/presubmit.yml

@@ -37,6 +37,17 @@ tasks:
       - "@go_sdk//..."
     test_targets:
       - "//..."
+  ubuntu2004_examples:
+    name: Examples test Ubuntu
+    platform: ubuntu2004
+    working_directory: examples/go-code-tutorial
+    shell_commands:
+      - "sudo apt-get update"
+      - "sudo apt-get install wamerican"
+    build_targets:
+      - "//..."
+    test_targets:
+      - "//..."
   macos:
     shell_commands:
       - tests/core/cgo/generate_imported_dylib.sh

.bazelignore

@@ -1 +1,2 @@
 tests/bcr
+examples

.gitignore

@@ -2,3 +2,4 @@
 /tests/core/cgo/libimported.*
 /tests/core/cgo/libversioned.*
 /tests/bcr/bazel-*
+/examples/*/bazel-*

examples/go-code-tutorial/.gitignore

@@ -0,0 +1,5 @@
+/bazel-bazel-gazelle
+/bazel-bin
+/bazel-out
+/bazel-go-code-tutorial
+/bazel-testlogs

examples/go-code-tutorial/BUILD.bazel

@@ -0,0 +1,30 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
+load("@bazel_gazelle//:def.bzl", "gazelle")
+
+# gazelle:prefix github.com/bazelbuild/rules_go/examples/go-code-tutorial
+gazelle(name = "gazelle")
+
+# adding rule to update deps
+gazelle(
+    name = "gazelle-update-repos",
+    args = [
+        "-from_file=go.mod",
+        "-to_macro=deps.bzl%go_dependencies",
+        "-prune",
+    ],
+    command = "update-repos",
+)
+
+go_library(
+    name = "go-code-tutorial_lib",
+    srcs = ["main.go"],
+    importpath = "github.com/bazelbuild/rules_go/examples/go-code-tutorial",
+    visibility = ["//visibility:private"],
+    deps = ["//cmd"],
+)
+
+go_binary(
+    name = "go-code-tutorial",
+    embed = [":go-code-tutorial_lib"],
+    visibility = ["//visibility:public"],
+)

examples/go-code-tutorial/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Go Rules Tutorial
+
+## Updates
+
+Please update both the source code here and the tutorial that is on the gh-pages branch here:
+https://github.com/bazel-contrib/SIG-rules-authors/tree/gh-pages.
+
+Updates to this tutorial require two PRs, as there are code block in the gh-pages tutorial mentioned 
+above.

examples/go-code-tutorial/README.md

@@ -0,0 +1,4 @@
+# Go Rules Tutorial
+
+This is the source code for the Go Rules tutorial that is available here:
+https://bazel-contrib.github.io/SIG-rules-authors/go-tutorial.html

examples/go-code-tutorial/WORKSPACE

@@ -0,0 +1,65 @@
+# Load the http ruleset and expose the http_archive rule
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+# Download rules_go ruleset.
+# Bazel makes a https call and downloads the zip file, and then
+# checks the sha.
+http_archive(
+    name = "io_bazel_rules_go",
+    sha256 = "099a9fb96a376ccbbb7d291ed4ecbdfd42f6bc822ab77ae6f1b5cb9e914e94fa",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
+    ],
+)
+
+# Download the bazel_gazelle ruleset.
+http_archive(
+    name = "bazel_gazelle",
+    sha256 = "efbbba6ac1a4fd342d5122cbdfdb82aeb2cf2862e35022c752eaddffada7c3f3",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.27.0/bazel-gazelle-v0.27.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.27.0/bazel-gazelle-v0.27.0.tar.gz",
+    ],
+)
+
+# Load rules_go ruleset and expose the toolchain and dep rules.
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+
+# the line below instructs gazelle to save the go dependency definitions
+# in the deps.bzl file. Located under '//'.
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
+
+############################################################
+# Define your own dependencies here using go_repository.
+# Else, dependencies declared by rules_go/gazelle will be used.
+# The first declaration of an external repository "wins".
+############################################################
+
+# The following line defines the symbol go_dependencies from the deps.bzl file.
+# Having the deps in that file, helps the WORKSPACE file stay less
+# cluttered.  The library symbol go_dependencies is then added to
+# the envionment. The line below calls that function.
+load("//:deps.bzl", "go_dependencies")
+
+# The next comment line includes a macro that gazelle reads.
+# This macro tells Gazelle to look for repository rules in a macro in a .bzl file,
+# and allows Gazelle to find the correct file to maintain the Go dependencies.
+# Then the line after the comment calls go_dependencies(), and that funcation
+# contains calls to various go_repository rules.
+
+# gazelle:repository_macro deps.bzl%go_dependencies
+go_dependencies()
+
+# go_rules_dependencies is a function that registers external dependencies
+# needed by the Go rules.
+# https://github.com/bazelbuild/rules_go/blob/master/go/dependencies.rst#go_rules_dependencies
+go_rules_dependencies()
+
+# The next rule installs the Go toolchains. The Go version is specified
+# using the version parameter. This rule will download the Go SDK.
+# https://github.com/bazelbuild/rules_go/blob/master/go/toolchains.rst#go_register_toolchains
+go_register_toolchains(version = "1.19.1")
+
+# The following call configured the gazelle dependencies, Go environment and Go SDK.
+gazelle_dependencies()

examples/go-code-tutorial/cmd/BUILD.bazel

@@ -0,0 +1,17 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "cmd",
+    srcs = [
+        "roll.go",
+        "root.go",
+        "word.go",
+    ],
+    importpath = "github.com/bazelbuild/rules_go/examples/go-code-tutorial/cmd",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//pkg/roll",
+        "//pkg/word",
+        "@com_github_spf13_cobra//:cobra",
+    ],
+)

examples/go-code-tutorial/cmd/roll.go

@@ -0,0 +1,52 @@
+// Copyright 2022 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/bazelbuild/rules_go/examples/go-code-tutorial/pkg/roll"
+	"github.com/spf13/cobra"
+)
+
+// rollCmd represents the roll command
+var rollCmd = &cobra.Command{
+	Use:   "roll",
+	Short: "A brief description of your command",
+	Long: `A longer description that spans multiple lines and likely contains examples
+and usage of using your command. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("roll called")
+		roll.Roll()
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(rollCmd)
+
+	// Here you will define your flags and configuration settings.
+
+	// Cobra supports Persistent Flags which will work for this command
+	// and all subcommands, e.g.:
+	// rollCmd.PersistentFlags().String("foo", "", "A help for foo")
+
+	// Cobra supports local flags which will only run when this command
+	// is called directly, e.g.:
+	// rollCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}

examples/go-code-tutorial/cmd/root.go

@@ -0,0 +1,57 @@
+// Copyright 2022 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+// rootCmd represents the base command when called without any subcommands
+var rootCmd = &cobra.Command{
+	Use:   "go-code-tutorial",
+	Short: "A brief description of your application",
+	Long: `A longer description that spans multiple lines and likely contains
+examples and usage of using your application. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	// Uncomment the following line if your bare application
+	// has an action associated with it:
+	// Run: func(cmd *cobra.Command, args []string) { },
+}
+
+// Execute adds all child commands to the root command and sets flags appropriately.
+// This is called by main.main(). It only needs to happen once to the rootCmd.
+func Execute() {
+	err := rootCmd.Execute()
+	if err != nil {
+		os.Exit(1)
+	}
+}
+
+func init() {
+	// Here you will define your flags and configuration settings.
+	// Cobra supports persistent flags, which, if defined here,
+	// will be global for your application.
+
+	// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.go-example-code.yaml)")
+
+	// Cobra also supports local flags, which will only run
+	// when this action is called directly.
+	rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}

examples/go-code-tutorial/cmd/word.go

@@ -0,0 +1,52 @@
+// Copyright 2022 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/bazelbuild/rules_go/examples/go-code-tutorial/pkg/word"
+	"github.com/spf13/cobra"
+)
+
+// wordCmd represents the word command
+var wordCmd = &cobra.Command{
+	Use:   "word",
+	Short: "A brief description of your command",
+	Long: `A longer description that spans multiple lines and likely contains examples
+and usage of using your command. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("word called")
+		fmt.Println(word.GenerateWord())
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(wordCmd)
+
+	// Here you will define your flags and configuration settings.
+
+	// Cobra supports Persistent Flags which will work for this command
+	// and all subcommands, e.g.:
+	// wordCmd.PersistentFlags().String("foo", "", "A help for foo")
+
+	// Cobra supports local flags which will only run when this command
+	// is called directly, e.g.:
+	// wordCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}