From 15f70b20f3cc20494f64e1bfa7dd91367fdd6ade Mon Sep 17 00:00:00 2001
From: Wolf Vollprecht <w.vollprecht@gmail.com>
Date: Wed, 4 Dec 2024 13:57:50 +0100
Subject: [PATCH] docs: add some perl docs (#1234)

---
 docs/tutorials/perl.md | 93 ++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml             |  1 +
 2 files changed, 94 insertions(+)
 create mode 100644 docs/tutorials/perl.md

diff --git a/docs/tutorials/perl.md b/docs/tutorials/perl.md
new file mode 100644
index 00000000..a6373571
--- /dev/null
+++ b/docs/tutorials/perl.md
@@ -0,0 +1,93 @@
+# Packaging a Perl (CPAM) package
+
+Packaging a Perl package is similar to packaging a Python package!
+
+## Building a Perl Package
+
+### A perl `noarch: generic` package
+
+The following recipe is for the Perl package `Call::Context`. We use `perl` in the `host` requirements, and install the package using `make`.
+The `noarch: generic` is used to indicate that the package is architecture-independent - since this is a pure Perl package, it can be installed and run on any platform (`noarch`).
+
+```yaml title="recipe.yaml"
+context:
+  version: 0.03
+
+package:
+  name: perl-call-context
+  version: ${{ version }}
+
+source:
+  url: https://cpan.metacpan.org/authors/id/F/FE/FELIPE/Call-Context-${{ version }}.tar.gz
+  sha256: 0ee6bf46bc72755adb7a6b08e79d12e207de5f7809707b3c353b58cb2f0b5a26
+
+build:
+  number: 0
+  noarch: generic
+  script:
+    - perl Makefile.PL INSTALLDIRS=vendor NO_PERLLOCAL=1 NO_PACKLIST=1
+    - make
+    - make test
+    - make install
+
+requirements:
+  build:
+    - make
+  host:
+    - perl
+
+tests:
+  - perl:
+      uses:
+        - Call::Context
+
+about:
+  license: GPL-1.0-or-later OR Artistic-1.0-Perl
+  summary: Sanity-check calling context
+  homepage: http://metacpan.org/pod/Call-Context
+```
+
+### A perl package with a C extension
+
+Some `perl` packages have native code extensions. In this example, we will build a package for the Perl package `Data::Dumper` using the `C` compiler.
+The `c` compiler and `make` are required at build time in the `build` requirements to compile the native code extension.
+We use `perl` in the `host` requirements, and install the package using `make`.
+
+```yaml title="recipe.yaml"
+context:
+  version: "2.183"
+
+package:
+  name: "perl-data-dumper"
+  version: ${{ version }}
+
+source:
+  url: https://cpan.metacpan.org/authors/id/N/NW/NWCLARK/Data-Dumper-${{ version }}.tar.gz
+  sha256: e42736890b7dae1b37818d9c5efa1f1fdc52dec04f446a33a4819bf1d4ab5ad3
+
+build:
+  number: 0
+  script:
+    - perl Makefile.PL INSTALLDIRS=vendor NO_PERLLOCAL=1 NO_PACKLIST=1
+    - make
+    - make test
+    - make install VERBINST=1
+
+requirements:
+  build:
+    - ${{ compiler('c') }}
+    - make
+  host:
+    - perl
+    - perl-extutils-makemaker
+
+tests:
+  - perl:
+      uses:
+        - Data::Dumper
+
+about:
+  homepage: https://metacpan.org/pod/Data::Dumper
+  license: GPL-1.0-or-later OR Artistic-1.0-Perl
+  summary: 'seeds germane, yet not germinated'
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index bb161864..38018ad7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -103,6 +103,7 @@ nav:
     - "Javascript": tutorials/javascript.md
     - "Rust": tutorials/rust.md
     - "Go": tutorials/go.md
+    - "Perl": tutorials/perl.md
     - "Converting from conda-build": converting_from_conda_build.md
 
   - Build options: