add an R tutorial and update python tutorial with abi3

Author: wolfv

docs/build_script.md

@@ -1,4 +1,4 @@
-# Build scripts
+# Scripts for building and testing packages
 
 The `build.sh` file is the build script for Linux and macOS and `build.bat` is
 the build script for Windows. These scripts contain the logic that carries out
@@ -77,6 +77,21 @@ So far, the following interpreters are supported:
 - `cmd.exe` (default on Windows)
 - `nushell`
 - `python`
+- `perl`
+- `rscript` (for R scripts)
+
+`rattler-build` automatically detects the interpreter based on the file extension
+(`.sh`, `.bat`, `.nu`, `.py`, `.pl`, `.r`) or you can specify it in the
+`interpreter` key in the `script` section of your recipe.
+
+```yaml title="recipe.yaml"
+build:
+  script: myscript.py  # automatically selects the Python interpreter
+
+requirements:
+  build:
+    - python  # required to execute the `myscript.py` script
+```
 
 !!! note
     Using alternative interpreters is less battle-tested than using `bash` or

docs/tutorials/python.md

@@ -3,6 +3,18 @@
 Writing a Python package is fairly straightforward, especially for "Python-only" packages.
 In the second example we will build a package for `numpy` which contains compiled code.
 
+## Generating a starter recipe
+
+Rattler-build provides a command to generate a recipe for a package from PyPI.
+The generated recipe can be used as a starting point for your recipe.
+The recipe generator will fetch the metadata from PyPI and generate a recipe that will build the package from the `sdist` source distriution.
+
+```bash
+rattler-build generate-recipe pypi ipywidgets
+# select an older version of the package
+rattler-build generate-recipe pypi ipywidgets --version 8.0.0
+```
+
 ## A Python-only package
 
 The following recipe uses the `noarch: python` setting to build a `noarch` package that can be installed on any platform without modification.
@@ -210,3 +222,118 @@ numpy-1.26.4-py312h440f24a_0
 │ target_platform ┆ osx-arm64 │
 ╰─────────────────┴───────────╯
 ```
+
+## An ABI3-compatible package
+
+Certain packages contain compiled code that is compatible with multiple Python versions.
+This is the case e.g. for a lot of Rust / PyO3 based Python extensions.
+
+In this case, you can use the special `abi3` settings to build a package that is specific to a certain operating system and architecture, but compatible with multiple Python versions.
+
+Note: this feature relies on the `python-abi3` package which exists in the `conda-forge` channel.
+The full recipe can be found on [`conda-forge/py-rattler-feedstock`](https://github.com/conda-forge/py-rattler-feedstock)
+
+```yaml title="recipe.yaml"
+context:
+  name: py-rattler
+  python_name: py_rattler
+  version: "0.11.0"
+  python_min: "3.8"
+
+package:
+  name: py-rattler
+  version: ${{ version }}
+
+source:
+  url: https://pypi.org/packages/source/${{ name[0] }}/${{ name }}/${{ python_name }}-${{ version }}.tar.gz
+  sha256: b00f91e19863741ce137a504eff3082c0b0effd84777444919bd83357530867f
+
+build:
+  number: 0
+  script: build.sh
+  python:
+    version_independent: true
+
+requirements:
+  build:
+    - ${{ compiler('c') }}
+    - ${{ compiler('rust') }}
+    - cargo-bundle-licenses
+  host:
+    - python      ${{ python_min }}.*
+    - python-abi3 ${{ python_min }}.*  # (1)!
+    - maturin >=1.2.2,<2
+    - pip
+    - if: unix
+      then:
+        - openssl
+  run:
+    - python >=${{ python_min }}
+
+tests:
+  - python:
+      imports:
+        - rattler
+      python_version: ["${{ python_min ~ '.*' }}"]  # (2)!
+  # You could run `abi3audit` here, but it is not necessary
+  # - script:
+  #     - abi3audit ${{ SP_DIR }}/spam.abi3.so -s -v --assume-minimum-abi3 ${{ python_min }}
+  #   requirements:
+  #     run:
+  #       - abi3audit
+
+about:
+  homepage: https://github.com/conda/rattler
+  license: BSD-3-Clause
+  license_file:
+    - LICENSE
+    - py-rattler/THIRDPARTY.yml
+  summary: A blazing fast library to work with the conda ecosystem
+  description: |
+    Rattler is a library that provides common functionality used within the conda
+    ecosystem. The goal of the library is to enable programs and other libraries to
+    easily interact with the conda ecosystem without being dependent on Python. Its
+    primary use case is as a library that you can use to provide conda related
+    workflows in your own tools.
+  repository: https://github.com/conda/rattler
+```
+
+1. The `python-abi3` package is a special package that ensures that the   run dependencies
+   are compatible with the ABI3 standard. 
+2. The `python_version` setting is used to test against the oldest compatible Python version.
+
+## Testing Python packages
+
+Testing Python packages is done using the `tests` section of the recipe.
+We can either use a special "python" test or a regular script test to test the package.
+
+All tests will have the current package and all it's run dependencies installed in an isolated environment.
+
+```yaml title="recipe.yaml"
+# contents of the recipe.yaml file
+tests:
+  - python:
+      # The Python test type will simply import packages as a sanity check.
+      imports:
+        - rattler
+        - rattler.version.Version
+      # You can select different Python versions to test against.
+      python_version: ["${{ python_min ~ '.*' }}", "3.12.*"]  # (1)!
+
+  # You can run a script test to run arbitrary code.
+  - script:
+      - pytest ./tests
+    requirements:  # (2)!
+      run:
+         - pytest
+    files:  # (3)!
+      source:
+        - tests/
+  # You can also directly execute a Python script and run some tests from it.
+  # The script is searched in the `recipe` directory.
+  - script: mytest.py
+```
+
+1. The `python_version` setting is used to test against different Python versions. It is useful to test against the minimum version of Python that the package supports.
+2. We can add additional requirements for the test run. such as pytest, pytest-cov, ... – you can also specify a `python` version here by adding e.g. `python 3.12.*` to the run requirements.
+3. This will copy over the tests from the source directory into the package. Note that this makes the package larger, so you might want to use a different approach for larger packages.

docs/tutorials/r.md

@@ -0,0 +1,66 @@
+# Packaging a R (CRAN) package
+
+Packaging a R package is similar to packaging a Python package!
+
+## Generating a starting point
+
+You can use rattler-build to generate a starting point for your recipe from the metadata on CRAN.
+
+```bash
+rattler-build generate-recipe cran r-knitr
+```
+
+## Building a R Package
+
+```yaml title="recipe.yaml"
+context:
+  version: "1.47"
+
+package:
+  name: r-knitr
+  version: ${{ version }}
+  noarch: generic  # (4)!
+
+source:
+- url: https://cran.r-project.org/src/contrib/Archive/knitr/knitr_${{ version }}.tar.gz
+  sha256: fadd849bf94a4e02520088a6626577c3c636227fe11c5cd7e8fcc5d51a7aa6cf
+
+build:
+  script: R CMD INSTALL --build .  # (1)!
+
+requirements:
+  host:
+  - r-base  # (2)!
+  - r-evaluate >=0.15
+  - r-highr >=0.11
+  - r-xfun >=0.44
+  - r-yaml >=2.1.19
+  run:
+  - r-base
+  - r-evaluate >=0.15
+  - r-highr >=0.11
+  - r-xfun >=0.44
+  - r-yaml >=2.1.19
+
+tests:
+# This is a shorthand test for R packages to ensure that the library loads correctly.
+- r:
+    libraries:
+      - knitr
+# You can also run arbitrary R code in the test section.
+- script: test_package.R  # (3)!
+
+about:
+  homepage: https://yihui.org/knitr/
+  summary: A General-Purpose Package for Dynamic Report Generation in R
+  description: |-
+    Provides a general-purpose tool for dynamic report
+    generation in R using Literate Programming techniques.
+  license: GPL-2.0
+  repository: https://github.com/cran/knitr
+```
+
+1. The `script` section is where you specify the build commands to run. In this case, we are using `R CMD INSTALL --build .` to build the package.
+2. The `r-base` package is required to run R and is specified in the `host` requirements.
+3. The `script` key automatically detects the language based on the file extension. In the case of `.R`, it will execute the R script with `rscript`.
+4. The `noarch: generic` directive indicates that the package is architecture-independent. This is useful for R packages that do not contain compiled code and can run on any architecture. It allows the package to be installed on any platform without needing to rebuild it for each architecture.

mkdocs.yml

@@ -104,6 +104,7 @@ nav:
     - "Rust": tutorials/rust.md
     - "Go": tutorials/go.md
     - "Perl": tutorials/perl.md
+    - "R": tutorials/r.md
     - "Converting from conda-build": converting_from_conda_build.md
 
   - Build options:

src/recipe_generator/cran.rs

@@ -229,10 +229,18 @@ pub async fn generate_r_recipe(opts: &CranOpts) -> miette::Result<()> {
     ))
     .expect("Failed to parse URL");
 
+    // It looks like CRAN moves the package to the archive for old versions
+    // so let's add that as a fallback mirror
+    let url_archive = Url::parse(&format!(
+        "https://cran.r-project.org/src/contrib/Archive/{}",
+        package_info._file
+    ))
+    .expect("Failed to parse URL");
+
     let sha256 = fetch_package_sha256sum(&url).await?;
 
     let source = SourceElement {
-        url: url.to_string(),
+        url: vec![url.to_string(), url_archive.to_string()],
         md5: None,
         sha256: Some(format!("{:x}", sha256)),
     };

src/recipe_generator/pypi.rs

@@ -358,7 +358,7 @@ pub async fn create_recipe(
     };
 
     recipe.source.push(serialize::SourceElement {
-        url: release_url.replace(metadata.info.version.as_str(), "${{ version }}"),
+        url: vec![release_url.replace(metadata.info.version.as_str(), "${{ version }}")],
         sha256: metadata.release.digests.get("sha256").cloned(),
         md5: None,
     });

src/recipe_generator/serialize.rs

@@ -2,10 +2,13 @@ use std::{fmt, path::PathBuf};
 
 use indexmap::IndexMap;
 use serde::Serialize;
+use serde_with::{serde_as, OneOrMany, formats::PreferOne};
 
+#[serde_as]
 #[derive(Default, Debug, Serialize)]
 pub struct SourceElement {
-    pub url: String,
+    #[serde_as(as = "OneOrMany<_, PreferOne>")]
+    pub url: Vec<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub sha256: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]