Provide more examples for pkg_rpm() (#823)

* Move prebuilt_rpmbuild example into rpm subdirectory

This will help us be a bit more organized as we add a few more
RPM-based examples for rules_pkg.

* Fix WORKSPACE file to account for subdirectory move

One we moved this into a subdirectory it was broke because of how it
uses rules_pkg as a local repository.

* s/readme.md/README.md/

The latter seems to be more the norm, so renaming for consistency and
visibility.

* Add more detail to README.md for prebuilt_rpmbuild example

This adds a bit more detail the description of the `prebuilt_rpmbuild`
example so that someone can understand it a bit more.

* Add an example of using system rpmbuild for pkg_rpm()

This example is essentially the same as the prebuilt_rpmbuild example
except that it uses find_system_rpmbuild() to register the local
version of `rpmbuild` as the toolchain to use.

* Add an example with bzlmod using system rpmbuild

This is very similar to the non-bzlmod version except we've replaced
the WORKSPACE file with a MODULE.bazel file.

* Add an example that doesn't use a specfile for pkg_rpm()

This example uses pkg_rpm() to generate the full rpm in lieu of using
a standalone specfile.

19 files changed, 343 insertions, 15 deletions

diff --git a/examples/prebuilt_rpmbuild/readme.md b/examples/prebuilt_rpmbuild/readme.md
deleted file mode 100644
index 0f1c347..0000000
--- a/examples/prebuilt_rpmbuild/readme.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Using a prebuilt rpmbuild instead of the system one.
-
-## To use
-
-```
-cp /usr/bin/rpmbuild local/rpmbuild_binary
-bazel build :*
-rpm2cpio bazel-bin/test-rpm.rpm | cpio -ivt
-cat bazel-bin/content.txt
-```
diff --git a/examples/rpm/nospecfile/BUILD b/examples/rpm/nospecfile/BUILD
new file mode 100644
index 0000000..3cf1b3b
--- /dev/null
+++ b/examples/rpm/nospecfile/BUILD
@@ -0,0 +1,54 @@
+# Copyright 2024 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.
+# -*- coding: utf-8 -*-
+
+load("@rules_pkg//pkg:mappings.bzl", "pkg_files")
+load("@rules_pkg//pkg:rpm.bzl", "pkg_rpm")
+
+pkg_files(
+    name = "rpm_files",
+    srcs = [
+        "BUILD",
+        "MODULE.bazel",
+        "README.md",
+    ],
+)
+
+pkg_rpm(
+    name = "test-rpm",
+    srcs = [
+        ":rpm_files",
+    ],
+    release = "0",
+    version = "1",
+    summary = "rules_pkg example RPM",
+    description = "This is a package description.",
+    license = "Apache License, v2.0",
+    architecture = "x86_64",
+    requires = [
+        "somerpm",
+    ],
+    provides = [
+        "somefile",
+    ],
+)
+
+# If you have rpmbuild, you probably have rpm2cpio too.
+# Feature idea: Add rpm2cpio and cpio to the rpmbuild toolchain
+genrule(
+    name = "inspect_content",
+    srcs = [":test-rpm"],
+    outs = ["content.txt"],
+    cmd = "rpm2cpio $(locations :test-rpm) | cpio -ivt >$@",
+)
diff --git a/examples/rpm/nospecfile/MODULE.bazel b/examples/rpm/nospecfile/MODULE.bazel
new file mode 100644
index 0000000..b2d8a8f
--- /dev/null
+++ b/examples/rpm/nospecfile/MODULE.bazel
@@ -0,0 +1,32 @@
+# Copyright 2024 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.
+
+module(name = "rules_pkg_example_rpm_system_rpmbuild_bzlmod")
+
+bazel_dep(name = "rules_pkg")
+
+local_path_override(
+    module_name = "rules_pkg",
+    path = "../../..",
+)
+
+find_rpmbuild = use_extension(
+    "@rules_pkg//toolchains/rpm:rpmbuild_configure.bzl",
+    "find_system_rpmbuild_bzlmod",
+)
+use_repo(find_rpmbuild, "rules_pkg_rpmbuild")
+
+register_toolchains(
+    "@rules_pkg_rpmbuild//:all",
+)
diff --git a/examples/rpm/nospecfile/README.md b/examples/rpm/nospecfile/README.md
new file mode 100644
index 0000000..1229e8a
--- /dev/null
+++ b/examples/rpm/nospecfile/README.md
@@ -0,0 +1,14 @@
+# Using system rpmbuild with bzlmod
+
+## Summary
+
+This example builds an RPM using the system `rpmbuild` from a pure bazel
+`pkg_rpm()` definition instead of using a separate specfile.
+
+## To use
+
+```
+bazel build :*
+rpm2cpio bazel-bin/test-rpm.rpm | cpio -ivt
+cat bazel-bin/content.txt
+```
diff --git a/examples/prebuilt_rpmbuild/BUILD b/examples/rpm/prebuilt_rpmbuild/BUILD
index 5b8f762..3f57592 100644
--- a/examples/prebuilt_rpmbuild/BUILD
+++ b/examples/rpm/prebuilt_rpmbuild/BUILD
@@ -20,7 +20,7 @@ pkg_rpm(
     data = [
         "BUILD",
         "WORKSPACE",
-        "readme.md",
+        "README.md",
         "test_rpm.spec",
     ],
     release = "0",
diff --git a/examples/rpm/prebuilt_rpmbuild/README.md b/examples/rpm/prebuilt_rpmbuild/README.md
new file mode 100644
index 0000000..4b12b39
--- /dev/null
+++ b/examples/rpm/prebuilt_rpmbuild/README.md
@@ -0,0 +1,18 @@
+# Using a prebuilt rpmbuild instead of the system one.
+
+## Summary
+
+This example defines a rpmbuild toolchain in `local` that can be used
+by rules_pkg.  This must be copied into place as `local/rpmbuild_binary`
+for use by `register_toolchains()`.
+
+The RPM itself is based on a user provided spec file.
+
+## To use
+
+```
+cp /usr/bin/rpmbuild local/rpmbuild_binary
+bazel build :*
+rpm2cpio bazel-bin/test-rpm.rpm | cpio -ivt
+cat bazel-bin/content.txt
+```
diff --git a/examples/prebuilt_rpmbuild/WORKSPACE b/examples/rpm/prebuilt_rpmbuild/WORKSPACE
index 4fc8a59..530620a 100644
--- a/examples/prebuilt_rpmbuild/WORKSPACE
+++ b/examples/rpm/prebuilt_rpmbuild/WORKSPACE
@@ -12,11 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-workspace(name = "rules_pkg_example_prebuilt_rpmbuild")
+workspace(name = "rules_pkg_example_rpm_prebuilt_rpmbuild")
 
 local_repository(
     name = "rules_pkg",
-    path = "../..",
+    path = "../../..",
 )
 
 load("@rules_pkg//pkg:deps.bzl", "rules_pkg_dependencies")
diff --git a/examples/prebuilt_rpmbuild/local/BUILD b/examples/rpm/prebuilt_rpmbuild/local/BUILD
index 7c273bf..7c273bf 100644
--- a/examples/prebuilt_rpmbuild/local/BUILD
+++ b/examples/rpm/prebuilt_rpmbuild/local/BUILD
diff --git a/examples/prebuilt_rpmbuild/local/rpmbuild.bzl b/examples/rpm/prebuilt_rpmbuild/local/rpmbuild.bzl
index cb34178..cb34178 100644
--- a/examples/prebuilt_rpmbuild/local/rpmbuild.bzl
+++ b/examples/rpm/prebuilt_rpmbuild/local/rpmbuild.bzl
diff --git a/examples/prebuilt_rpmbuild/local/rpmbuild_binary b/examples/rpm/prebuilt_rpmbuild/local/rpmbuild_binary
index 8015e88..8015e88 100755
--- a/examples/prebuilt_rpmbuild/local/rpmbuild_binary
+++ b/examples/rpm/prebuilt_rpmbuild/local/rpmbuild_binary
diff --git a/examples/prebuilt_rpmbuild/test_rpm.spec b/examples/rpm/prebuilt_rpmbuild/test_rpm.spec
index c52dc24..3b18f98 100644
--- a/examples/prebuilt_rpmbuild/test_rpm.spec
+++ b/examples/rpm/prebuilt_rpmbuild/test_rpm.spec
@@ -15,10 +15,10 @@ This is a package description.
 %build
 
 %install
-cp WORKSPACE BUILD readme.md test_rpm.spec %{buildroot}/
+cp WORKSPACE BUILD README.md test_rpm.spec %{buildroot}/
 
 %files
 /WORKSPACE
 /BUILD
-/readme.md
+/README.md
 /test_rpm.spec
diff --git a/examples/rpm/system_rpmbuild/BUILD b/examples/rpm/system_rpmbuild/BUILD
new file mode 100644
index 0000000..3f57592
--- /dev/null
+++ b/examples/rpm/system_rpmbuild/BUILD
@@ -0,0 +1,38 @@
+# Copyright 2020 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.
+# -*- coding: utf-8 -*-
+
+load("@rules_pkg//pkg:rpm.bzl", "pkg_rpm")
+
+pkg_rpm(
+    name = "test-rpm",
+    data = [
+        "BUILD",
+        "WORKSPACE",
+        "README.md",
+        "test_rpm.spec",
+    ],
+    release = "0",
+    spec_file = "test_rpm.spec",
+    version = "1",
+)
+
+# If you have rpmbuild, you probably have rpm2cpio too.
+# Feature idea: Add rpm2cpio and cpio to the rpmbuild toolchain
+genrule(
+    name = "inspect_content",
+    srcs = [":test-rpm"],
+    outs = ["content.txt"],
+    cmd = "rpm2cpio $(locations :test-rpm) | cpio -ivt >$@",
+)
diff --git a/examples/rpm/system_rpmbuild/README.md b/examples/rpm/system_rpmbuild/README.md
new file mode 100644
index 0000000..ea27429
--- /dev/null
+++ b/examples/rpm/system_rpmbuild/README.md
@@ -0,0 +1,17 @@
+# Using system rpmbuild
+
+## Summary
+
+This example uses the `find_system_rpmbuild()` macro built into `rules_pkg`
+to search for `rpmbuild` in on the local system and use that to drive the
+packaging process.
+
+The RPM itself is based on a user provided spec file.
+
+## To use
+
+```
+bazel build :*
+rpm2cpio bazel-bin/test-rpm.rpm | cpio -ivt
+cat bazel-bin/content.txt
+```
diff --git a/examples/rpm/system_rpmbuild/WORKSPACE b/examples/rpm/system_rpmbuild/WORKSPACE
new file mode 100644
index 0000000..9dac982
--- /dev/null
+++ b/examples/rpm/system_rpmbuild/WORKSPACE
@@ -0,0 +1,31 @@
+# Copyright 2024 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.
+
+workspace(name = "rules_pkg_example_rpm_system_rpmbuild")
+
+local_repository(
+    name = "rules_pkg",
+    path = "../../..",
+)
+
+load("@rules_pkg//pkg:deps.bzl", "rules_pkg_dependencies")
+
+rules_pkg_dependencies()
+
+load(
+    "@rules_pkg//toolchains/rpm:rpmbuild_configure.bzl",
+    "find_system_rpmbuild",
+)
+
+find_system_rpmbuild(name="my_rpmbuild")
diff --git a/examples/rpm/system_rpmbuild/test_rpm.spec b/examples/rpm/system_rpmbuild/test_rpm.spec
new file mode 100644
index 0000000..3b18f98
--- /dev/null
+++ b/examples/rpm/system_rpmbuild/test_rpm.spec
@@ -0,0 +1,24 @@
+Name: example
+Version: 0
+Release: 1
+Summary: Example .spec file
+License: Apache License, v2.0
+
+# Do not try to use magic to determine file types
+%define __spec_install_post %{nil}
+# Do not die because we give it more input files than are in the files section
+%define _unpackaged_files_terminate_build 0
+
+%description
+This is a package description.
+
+%build
+
+%install
+cp WORKSPACE BUILD README.md test_rpm.spec %{buildroot}/
+
+%files
+/WORKSPACE
+/BUILD
+/README.md
+/test_rpm.spec
diff --git a/examples/rpm/system_rpmbuild_bzlmod/BUILD b/examples/rpm/system_rpmbuild_bzlmod/BUILD
new file mode 100644
index 0000000..1f007ed
--- /dev/null
+++ b/examples/rpm/system_rpmbuild_bzlmod/BUILD
@@ -0,0 +1,38 @@
+# Copyright 2020 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.
+# -*- coding: utf-8 -*-
+
+load("@rules_pkg//pkg:rpm.bzl", "pkg_rpm")
+
+pkg_rpm(
+    name = "test-rpm",
+    data = [
+        "BUILD",
+        "MODULE.bazel",
+        "README.md",
+        "test_rpm.spec",
+    ],
+    release = "0",
+    spec_file = "test_rpm.spec",
+    version = "1",
+)
+
+# If you have rpmbuild, you probably have rpm2cpio too.
+# Feature idea: Add rpm2cpio and cpio to the rpmbuild toolchain
+genrule(
+    name = "inspect_content",
+    srcs = [":test-rpm"],
+    outs = ["content.txt"],
+    cmd = "rpm2cpio $(locations :test-rpm) | cpio -ivt >$@",
+)
diff --git a/examples/rpm/system_rpmbuild_bzlmod/MODULE.bazel b/examples/rpm/system_rpmbuild_bzlmod/MODULE.bazel
new file mode 100644
index 0000000..b2d8a8f
--- /dev/null
+++ b/examples/rpm/system_rpmbuild_bzlmod/MODULE.bazel
@@ -0,0 +1,32 @@
+# Copyright 2024 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.
+
+module(name = "rules_pkg_example_rpm_system_rpmbuild_bzlmod")
+
+bazel_dep(name = "rules_pkg")
+
+local_path_override(
+    module_name = "rules_pkg",
+    path = "../../..",
+)
+
+find_rpmbuild = use_extension(
+    "@rules_pkg//toolchains/rpm:rpmbuild_configure.bzl",
+    "find_system_rpmbuild_bzlmod",
+)
+use_repo(find_rpmbuild, "rules_pkg_rpmbuild")
+
+register_toolchains(
+    "@rules_pkg_rpmbuild//:all",
+)
diff --git a/examples/rpm/system_rpmbuild_bzlmod/README.md b/examples/rpm/system_rpmbuild_bzlmod/README.md
new file mode 100644
index 0000000..88f9cd4
--- /dev/null
+++ b/examples/rpm/system_rpmbuild_bzlmod/README.md
@@ -0,0 +1,16 @@
+# Using system rpmbuild with bzlmod
+
+## Summary
+
+This example uses the `find_system_rpmbuild_bzlmod` module extension to help
+us register the system rpmbuild as a toolchain in a bzlmod environment.
+
+The RPM itself is based on a user provided spec file.
+
+## To use
+
+```
+bazel build :*
+rpm2cpio bazel-bin/test-rpm.rpm | cpio -ivt
+cat bazel-bin/content.txt
+```
diff --git a/examples/rpm/system_rpmbuild_bzlmod/test_rpm.spec b/examples/rpm/system_rpmbuild_bzlmod/test_rpm.spec
new file mode 100644
index 0000000..0858b95
--- /dev/null
+++ b/examples/rpm/system_rpmbuild_bzlmod/test_rpm.spec
@@ -0,0 +1,24 @@
+Name: example
+Version: 0
+Release: 1
+Summary: Example .spec file
+License: Apache License, v2.0
+
+# Do not try to use magic to determine file types
+%define __spec_install_post %{nil}
+# Do not die because we give it more input files than are in the files section
+%define _unpackaged_files_terminate_build 0
+
+%description
+This is a package description.
+
+%build
+
+%install
+cp MODULE.bazel BUILD README.md test_rpm.spec %{buildroot}/
+
+%files
+/MODULE.bazel
+/BUILD
+/README.md
+/test_rpm.spec