docs: first pass for README

.bazelrc

@@ -1,7 +1,7 @@
 # To update these lines, execute 
 # `bazel run @rules_bazel_integration_test//tools:update_deleted_packages`
-build --deleted_packages=examples/bzlmod,examples/bzlmod/Sources/MyExecutable,examples/bzlmod/Sources/MyLibrary,examples/bzlmod/Sources/System,examples/bzlmod/Tests/MyLibraryTests,examples/grpc_example,examples/grpc_example/aaa_test,examples/grpc_example/compilers,examples/grpc_example/protos/echo_service,examples/grpc_example/protos/echo_service/requests,examples/grpc_example/protos/echo_service/responses,examples/grpc_example/sources/client,examples/grpc_example/sources/server,examples/grpc_example/sources/test,examples/grpc_package_example,examples/grpc_package_example/aaa_test,examples/grpc_package_example/compilers,examples/grpc_package_example/protos/echo_service,examples/grpc_package_example/sources/client,examples/grpc_package_example/sources/server,examples/grpc_package_example/sources/test
-query --deleted_packages=examples/bzlmod,examples/bzlmod/Sources/MyExecutable,examples/bzlmod/Sources/MyLibrary,examples/bzlmod/Sources/System,examples/bzlmod/Tests/MyLibraryTests,examples/grpc_example,examples/grpc_example/aaa_test,examples/grpc_example/compilers,examples/grpc_example/protos/echo_service,examples/grpc_example/protos/echo_service/requests,examples/grpc_example/protos/echo_service/responses,examples/grpc_example/sources/client,examples/grpc_example/sources/server,examples/grpc_example/sources/test,examples/grpc_package_example,examples/grpc_package_example/aaa_test,examples/grpc_package_example/compilers,examples/grpc_package_example/protos/echo_service,examples/grpc_package_example/sources/client,examples/grpc_package_example/sources/server,examples/grpc_package_example/sources/test
+build --deleted_packages=examples/bzlmod,examples/bzlmod/Sources/MyExecutable,examples/bzlmod/Sources/MyLibrary,examples/bzlmod/Sources/System,examples/bzlmod/Tests/MyLibraryTests,examples/grpc_example,examples/grpc_example/aaa_test,examples/grpc_example/compilers,examples/grpc_example/protos/echo_service,examples/grpc_example/protos/echo_service/requests,examples/grpc_example/protos/echo_service/responses,examples/grpc_example/sources/client,examples/grpc_example/sources/server,examples/grpc_example/sources/test,examples/grpc_package_example,examples/grpc_package_example/aaa_test,examples/grpc_package_example/compilers,examples/grpc_package_example/protos/echo_service,examples/grpc_package_example/sources/client,examples/grpc_package_example/sources/server,examples/grpc_package_example/sources/test,examples/simple,examples/simple/Sources/MyExecutable,examples/simple/Sources/MyLibrary,examples/simple/Tests/MyLibraryTests
+query --deleted_packages=examples/bzlmod,examples/bzlmod/Sources/MyExecutable,examples/bzlmod/Sources/MyLibrary,examples/bzlmod/Sources/System,examples/bzlmod/Tests/MyLibraryTests,examples/grpc_example,examples/grpc_example/aaa_test,examples/grpc_example/compilers,examples/grpc_example/protos/echo_service,examples/grpc_example/protos/echo_service/requests,examples/grpc_example/protos/echo_service/responses,examples/grpc_example/sources/client,examples/grpc_example/sources/server,examples/grpc_example/sources/test,examples/grpc_package_example,examples/grpc_package_example/aaa_test,examples/grpc_package_example/compilers,examples/grpc_package_example/protos/echo_service,examples/grpc_package_example/sources/client,examples/grpc_package_example/sources/server,examples/grpc_package_example/sources/test,examples/simple,examples/simple/Sources/MyExecutable,examples/simple/Sources/MyLibrary,examples/simple/Tests/MyLibraryTests
 
 # Import Shared settings
 import %workspace%/.bazelrc.shared

.bazelrc.shared

@@ -24,7 +24,7 @@ build:cache --experimental_remote_cache_async
 build:cache --experimental_remote_cache_compression
 
 # Recommended by BuildBuddy
-build --experimental_remote_build_event_upload=minimal
+build --remote_build_event_upload=minimal
 build --noslim_profile 
 build --experimental_profile_include_target_label 
 build --experimental_profile_include_primary_output 

.bazelversion

@@ -1 +1 @@
-7.4.0
+8.0.0

.github/workflows/ci.yml

@@ -53,6 +53,7 @@ jobs:
           - '//examples:bzlmod_test_bazel_.bazelversion'
           - '//examples:grpc_example_test_bazel_.bazelversion'
           - '//examples:grpc_package_example_test_bazel_.bazelversion'
+          - '//examples:simple_test_bazel_.bazelversion'
 
     runs-on: ${{ matrix.runner }}
     env:

README.md

@@ -1,2 +1,116 @@
-# swift_gazelle_plugin
-Gazelle plugin for Swift files.
+# Swift Gazelle Plugin for Bazel
+
+[![Build](https://github.com/cgrindel/swift_gazelle_plugin/actions/workflows/ci.yml/badge.svg?event=schedule)](https://github.com/cgrindel/swift_gazelle_plugin/actions/workflows/ci.yml)
+
+This repository contains a [Gazelle plugin] used to generate [rules_swift] targets based upon your
+Swift source code..
+
+## Table of Contents
+
+<!-- MARKDOWN TOC: BEGIN -->
+* [Quickstart](#quickstart)
+  * [1. Enable bzlmod](#1-enable-bzlmod)
+  * [2. Configure your `MODULE.bazel` to use swift_gazelle_plugin.](#2-configure-your-modulebazel-to-use-swift_gazelle_plugin)
+  * [3. Add Gazelle targets to `BUILD.bazel` at the root of your workspace.](#3-add-gazelle-targets-to-buildbazel-at-the-root-of-your-workspace)
+  * [4. Create or update Bazel build files for your project.](#4-create-or-update-bazel-build-files-for-your-project)
+  * [5. Build and test your project.](#5-build-and-test-your-project)
+  * [6. Check in `MODULE.bazel`.](#6-check-in-modulebazel)
+  * [10. Start coding](#10-start-coding)
+* [Tips and Tricks](#tips-and-tricks)
+<!-- MARKDOWN TOC: END -->
+
+## Quickstart
+
+The following provides a quick introduction on how to set up and use the features in this
+repository. These instructions assume that you are using [Bazel modules] to load your external
+dependencies. If you are using Bazel's legacy external dependency management, we recommend using
+[Bazel's hybrid mode], then follow the steps in this quickstart guide.
+
+### 1. Enable bzlmod
+
+This repository supports [bzlmod].
+
+```
+common --enable_bzlmod
+```
+
+### 2. Configure your `MODULE.bazel` to use [swift_gazelle_plugin].
+
+Add a dependency on `swift_gazelle_plugin`.
+
+<!-- BEGIN MODULE SNIPPET -->
+
+```python
+bazel_dep(name = "swift_gazelle_plugin", version = "0.0.0")
+```
+
+<!-- END MODULE SNIPPET -->
+
+### 3. Add Gazelle targets to `BUILD.bazel` at the root of your workspace.
+
+Add the following to the `BUILD.bazel` file at the root of your workspace.
+
+```bzl
+load("@gazelle//:def.bzl", "gazelle", "gazelle_binary")
+
+# This declaration builds a Gazelle binary that incorporates all of the Gazelle
+# plugins for the languages that you use in your workspace. In this example, we
+# are only listing the Gazelle plugin for Swift from swift_gazelle_plugin.
+gazelle_binary(
+    name = "gazelle_bin",
+    languages = [
+        "@swift_gazelle_plugin//gazelle",
+    ],
+)
+
+# This target updates the Bazel build files for your project. Run this target
+# whenever you add or remove source files from your project.
+gazelle(
+    name = "update_build_files",
+    gazelle = ":gazelle_bin",
+)
+```
+
+### 4. Create or update Bazel build files for your project.
+
+Generate/update the Bazel build files for your project by running the following:
+
+```sh
+bazel run //:update_build_files
+```
+
+### 5. Build and test your project.
+
+Build and test your project.
+
+```sh
+bazel test //...
+```
+
+### 6. Check in `MODULE.bazel`.
+
+- The `MODULE.bazel` contains the declarations for your external dependencies.
+
+### 10. Start coding
+
+You are ready to start coding.
+
+## Tips and Tricks
+
+The following are a few tips to consider as you work with your repository:
+
+- When you add or remove source files, run `bazel run //:update_build_files`. This will
+  create/update the Bazel build files in your project. It is designed to be fast and unobtrusive.
+- If things do not appear to be working properly, run the following:
+  - `bazel run //:update_build_files`
+- Do yourself a favor and create a Bazel target (e.g., `//:tidy`) that runs your repository
+  maintenance targets (e.g., `//:update_build_files`, formatting utilities)
+  in the proper order. If you are looking for an easy way to set this up, check out the
+  [`//:tidy` declaration in this repository](BUILD.bazel) and the documentation for the [tidy] macro.
+
+<!-- Links -->
+
+[Gazelle plugin]: https://github.com/bazelbuild/bazel-gazelle/blob/master/extend.md
+[rules_swift]: https://github.com/bazelbuild/rules_swift
+[swift_gazelle_plugin]: https://github.com/cgrindel/swift_gazelle_plugin
+[tidy]: https://github.com/cgrindel/bazel-starlib/blob/main/doc/bzltidy/rules_and_macros_overview.md#tidy

examples/BUILD.bazel

@@ -31,6 +31,7 @@ DIR_NAMES = [
     "bzlmod",
     "grpc_example",
     "grpc_package_example",
+    "simple",
 ]
 
 [

examples/simple/BUILD.bazel

@@ -0,0 +1,33 @@
+load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
+load("@cgrindel_bazel_starlib//bzlformat:defs.bzl", "bzlformat_pkg")
+load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_bazel_starlib//updatesrc:defs.bzl", "updatesrc_update_all")
+
+# MARK: - Tidy / Update Source Files
+
+bzlformat_pkg(name = "bzlformat")
+
+updatesrc_update_all(name = "update_all")
+
+tidy(
+    name = "tidy",
+    targets = [
+        ":update_all",
+        ":update_build_files",
+    ],
+)
+
+# MARK: - Gazelle
+
+gazelle_binary(
+    name = "gazelle_bin",
+    languages = [
+        "@bazel_skylib_gazelle_plugin//bzl",
+        "@swift_gazelle_plugin//gazelle",
+    ],
+)
+
+gazelle(
+    name = "update_build_files",
+    gazelle = ":gazelle_bin",
+)

examples/simple/MODULE.bazel

@@ -0,0 +1,39 @@
+bazel_dep(
+    name = "swift_gazelle_plugin",
+    version = "0.0.0",
+)
+local_path_override(
+    module_name = "swift_gazelle_plugin",
+    path = "../..",
+)
+
+bazel_dep(name = "cgrindel_bazel_starlib", version = "0.21.0")
+
+# The apple_support bazel_dep must come before the rules_cc.
+# https://github.com/bazelbuild/apple_support#incompatible-toolchain-resolution
+bazel_dep(name = "apple_support", version = "1.17.1")
+bazel_dep(
+    name = "rules_swift",
+    version = "2.2.2",
+    repo_name = "build_bazel_rules_swift",
+)
+
+apple_cc_configure = use_extension(
+    "@apple_support//crosstool:setup.bzl",
+    "apple_cc_configure_extension",
+)
+use_repo(apple_cc_configure, "local_config_apple_cc")
+
+# Dev Dependencies
+
+bazel_dep(
+    name = "bazel_skylib_gazelle_plugin",
+    version = "1.7.1",
+    dev_dependency = True,
+)
+bazel_dep(
+    name = "gazelle",
+    version = "0.40.0",
+    dev_dependency = True,
+    repo_name = "bazel_gazelle",
+)

examples/simple/Sources/MyExecutable/BUILD.bazel

@@ -0,0 +1,9 @@
+load("@build_bazel_rules_swift//swift:swift.bzl", "swift_binary")
+
+swift_binary(
+    name = "MyExecutable",
+    srcs = ["MyExecutable.swift"],
+    module_name = "MyExecutable",
+    visibility = ["//visibility:public"],
+    deps = ["//Sources/MyLibrary"],
+)

examples/simple/Sources/MyExecutable/MyExecutable.swift

@@ -0,0 +1,9 @@
+import MyLibrary
+
+@main
+struct MyExecutable {
+    static func main() async {
+        let world = World()
+        print("Hello, \(world.name)!")
+    }
+}

examples/simple/Sources/MyLibrary/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@build_bazel_rules_swift//swift:swift.bzl", "swift_library")
+
+swift_library(
+    name = "MyLibrary",
+    srcs = ["World.swift"],
+    module_name = "MyLibrary",
+    visibility = ["//visibility:public"],
+)

examples/simple/Sources/MyLibrary/World.swift

@@ -0,0 +1,4 @@
+public struct World {
+    public init() {}
+    public var name = "World"
+}

examples/simple/Tests/MyLibraryTests/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@build_bazel_rules_swift//swift:swift.bzl", "swift_test")
+
+swift_test(
+    name = "MyLibraryTests",
+    srcs = ["WorldTests.swift"],
+    module_name = "MyLibraryTests",
+    deps = ["//Sources/MyLibrary"],
+)

examples/simple/Tests/MyLibraryTests/WorldTests.swift

@@ -0,0 +1,8 @@
+@testable import MyLibrary
+import XCTest
+
+final class WorldTests: XCTestCase {
+    func test() throws {
+        XCTAssertEqual(World().name, "World")
+    }
+}

examples/simple/WORKSPACE

@@ -0,0 +1 @@
+# Intentionally blank.

examples/simple/do_test

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+set -o errexit -o nounset -o pipefail
+
+# Use the Bazel binary specified by the integration test. Otherise, fall back 
+# to bazel.
+bazel="${BIT_BAZEL_BINARY:-bazel}"
+
+assert_match() {
+  local pattern=${1}
+  local actual="${2}"
+  local err_msg="Expected to match. pattern: ${pattern}, actual: ${actual}"
+  [[ "${actual}" =~ ${pattern} ]] || (echo >&2 "${err_msg}" && exit 1)
+}
+
+# Generate Swift external deps and update build files
+"${bazel}" run //:tidy
+
+# Ensure that it builds and tests pass
+"${bazel}" test //...
+
+# Run MyExecutable target
+output="$("${bazel}" run //Sources/MyExecutable)"
+assert_match "Hello, World!" "${output}"