Added module extension for fetching CPAN dependencies

Co-authored-by: Laurenz <[email protected]>

Author: UebelAndre

.bazelci/presubmit.yml

@@ -17,6 +17,24 @@ tasks:
     test_targets:
     - "//..."
 
+  cpan_compile_ubuntu2204:
+    name: CPAN Compile
+    platform: ubuntu2204
+    run_targets:
+    # Two compilations are performed to ensure the
+    # results of the first are usable by the second.
+    - "//perl/cpan/3rdparty:compiler"
+    - "//perl/cpan/3rdparty:compiler"
+
+  cpan_compile_macos:
+    name: CPAN Compile
+    platform: macos_arm64
+    run_targets:
+    # Two compilations are performed to ensure the
+    # results of the first are usable by the second.
+    - "//perl/cpan/3rdparty:compiler"
+    - "//perl/cpan/3rdparty:compiler"
+
   e2e_ubuntu2204:
     platform: ubuntu2204
     shell_commands:

MODULE.bazel

@@ -30,6 +30,16 @@ register_toolchains(
     "@rules_perl//perl:perl_windows_x86_64_toolchain",
 )
 
+cpan = use_extension("@rules_perl//perl/cpan:extensions.bzl", "cpan")
+cpan.install(
+    name = "cpan_compiler_deps",
+    lock = "//perl/cpan/3rdparty:cpanfile.snapshot.lock.json",
+)
+use_repo(
+    cpan,
+    "cpan_compiler_deps",
+)
+
 dev_repos = use_extension("@rules_perl//perl:extensions.bzl", "perl_dev_repositories", dev_dependency = True)
 use_repo(
     dev_repos,

README.md

@@ -49,25 +49,47 @@ This repository provides a hermetic [Strawberry Perl](https://strawberryperl.com
 
 ## Using Perl Modules
 
-This is the first stab at getting a more mature set of Perl rules for Bazel.  Currently, it is a manual process and, hopefully, it will be a map for automation later on.
+Perl modules from [CPAN](https://www.cpan.org/) can be generated using the `cpan_compiler` rule in
+conjunction with the `cpan` module extension.
 
 ### Current Steps
 
-* Manually download the module that you want to use.
-* Add the actual files that you need to your repository.
-  * Highly recommended that you place the files in the directory structure that each Perl file is unpacked into (you may need to run `perl Makefile.PL; make` to see the final paths)
-  * Recommended to create a 'cpan' directory and place the files (in their required path) there.
-  * Test::Mock::Simple does **NOT** follow this pattern as it is being used as a practical example - please see 'Simple Pure Perl Example' section.
-* Add the new module's information to the BUILD file in the root directory of all your modules.
-  * the target in the `deps` attribute
-    * At this time compiled files (result of XS) will be put in the `srcs` attribute
-  * the directory where the module lives in the `env` attribute for the `PERL5LIB` variable
-
-#### Dependencies
-
-The process needs to be repeated for any dependencies that the module needs.
-
-Eventually, this should be an automated process.
+1. Create a `cpanfile` per the [Carton](https://metacpan.org/pod/Carton) documentation.
+2. Create an empty `*.json` will need to be created for Bazel to use a lockfile (e.g. `cpanfile.snapshot.lock.json`)
+3. Define a `cpan_compiler` target:
+
+  ```python
+  load("//perl/cpan:cpan_compiler.bzl", "cpan_compiler")
+
+  cpan_compiler(
+      name = "compiler",
+      cpanfile = "cpanfile",
+      lockfile = "cpanfile.snapshot.lock.json",
+      visibility = ["//visibility:public"],
+  )
+  ```
+
+4. `bazel run` the new target.
+5. Define a new module in `MODULE.bazel` pointing to the Bazel `*.json` lock file:
+
+  ```python
+  cpan = use_extension("@rules_perl//perl/cpan:extensions.bzl", "cpan")
+  cpan.install(
+      name = "cpan",
+      lock = "//perl/cpan/3rdparty:cpanfile.snapshot.lock.json",
+  )
+  use_repo(
+      cpan,
+      "cpan",
+  )
+  ```
+
+### Dependencies
+
+Once the `cpan` module extension is defined, dependencies will be available through the name given to the module.
+Using the example in the steps above, dependencies can be accessed through `@cpan//...`. (e.g. `@cpan//:DateTime`).
+
+Note that [`xs`](https://perldoc.perl.org/perlxs) dependencies are currently not supported by the `cpan` extension module.
 
 ### Simple Pure Perl Example
 

perl/cpan/3rdparty/BUILD.bazel

@@ -0,0 +1,14 @@
+load("//perl/cpan:cpan_compiler.bzl", "cpan_compiler")
+
+exports_files([
+    "cpanfile",
+    "cpanfile.snapshot",
+    "cpanfile.snapshot.lock.json",
+])
+
+cpan_compiler(
+    name = "compiler",
+    cpanfile = "cpanfile",
+    lockfile = "cpanfile.snapshot.lock.json",
+    visibility = ["//visibility:public"],
+)

perl/cpan/3rdparty/cpanfile

@@ -0,0 +1,3 @@
+requires 'Carton';
+requires 'File::Slurp';
+requires 'JSON::PP';