Adds CRAN compliance helpers and vignette

.Rbuildignore

@@ -17,3 +17,4 @@
 ^\.idea$
 ^inst/libgcc_mock/libgcc_eh.a$
 ^CRAN-SUBMISSION$
+^vignettes/articles$

NAMESPACE

@@ -11,7 +11,9 @@ export(rust_function)
 export(rust_sitrep)
 export(rust_source)
 export(to_toml)
+export(use_cran_defaults)
 export(use_extendr)
+export(vendor_pkgs)
 export(write_license_note)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,mutate)

R/cran-compliance.R

@@ -0,0 +1,221 @@
+#' Use CRAN compliant defaults
+#'
+#' Modifies an extendr package to use CRAN compliant settings.
+#'
+#' @details
+#'
+#' `use_cran_defaults()` modifies an existing package to provide CRAN complaint
+#' settings and files. It creates `configure` and `configure.win` files as well as
+#'  modifies `Makevars` and `Makevars.win` to use required CRAN settings.
+#'
+#' `vendor_pkgs()` is used to package the dependencies as required by CRAN.
+#' It executes `cargo vendor` on your behalf creating a `vendor/` directory and a
+#' compressed `vendor.tar.xz` which will be shipped with package itself.
+#' If you have modified your dependencies, you will need need to repackage
+#  the vendored dependencies using `vendor_pkgs()`.
+#'
+#' @inheritParams use_extendr
+#' @returns
+#'
+#' - `vendor_pkgs()` returns a data.frame with two columns `crate` and `version`
+#' - `use_cran_defaults()` returns `NULL` and is used solely for its side effects
+#'
+#' @examples
+#'
+#' if (interactive()) {
+#'   use_cran_defaults()
+#'   vendor_pkgs()
+#' }
+#' @name cran
+#' @export
+use_cran_defaults <- function(path = ".", quiet = FALSE, overwrite = NULL, lib_name = NULL) {
+
+  # if not in an interactive session and overwrite is null, set it to false
+  if (!rlang::is_interactive()) {
+    overwrite <- overwrite %||% FALSE
+  }
+
+  # silence output
+  local_quiet_cli(quiet)
+
+  # find package root
+  pkg_root <- rprojroot::find_package_root_file(path)
+
+  # set the path for the duration of the function
+  withr::local_dir(pkg_root)
+
+  if (is.null(lib_name)) {
+    lib_name <- as_valid_rust_name(pkg_name(path))
+  } else if (length(lib_name) > 1) {
+    cli::cli_abort(
+      "{.arg lib_name} must be a character scalar",
+      class = "rextendr_error"
+    )
+  }
+
+  # add configure and configure.win templates
+  use_rextendr_template(
+    "cran/configure",
+    save_as = "configure",
+    quiet = quiet,
+    overwrite = overwrite,
+    data = list(lib_name = lib_name)
+  )
+
+  # configure needs to be made executable
+  Sys.chmod("configure", "0755")
+
+  use_rextendr_template(
+    "cran/configure.win",
+    save_as = "configure.win",
+    quiet = quiet,
+    overwrite = overwrite,
+    data = list(lib_name = lib_name)
+  )
+
+  # use CRAN specific Makevars templates
+  use_rextendr_template(
+    "cran/Makevars",
+    save_as = file.path("src", "Makevars"),
+    quiet = quiet,
+    overwrite = overwrite,
+    data = list(lib_name = lib_name)
+  )
+
+  use_rextendr_template(
+    "cran/Makevars.win",
+    save_as = file.path("src", "Makevars.win"),
+    quiet = quiet,
+    overwrite = overwrite,
+    data = list(lib_name = lib_name)
+  )
+
+  # vendor directory should be ignored by git and R CMD build
+  if (!rlang::is_installed("usethis")) {
+    cli::cli_inform(
+      c(
+        "!" = "Add {.code ^src/rust/vendor$} to your {.file .Rbuildignore}",
+        "!" = "Add {.code ^src/rust/vendor$} to your {.file .gitignore}",
+        "i" = "Install {.pkg usethis} to have this done automatically."
+      )
+    )
+  } else {
+    # vendor folder will be large when expanded and should be ignored
+    usethis::use_build_ignore(
+      file.path("src", "rust", "vendor")
+    )
+
+    usethis::use_git_ignore(
+      file.path("src", "rust", "vendor")
+    )
+  }
+
+  invisible(NULL)
+}
+
+#' @export
+#' @name cran
+vendor_pkgs <- function(path = ".", quiet = FALSE, overwrite = NULL) {
+  local_quiet_cli(quiet)
+
+  # get path to rust folder
+  src_dir <- rprojroot::find_package_root_file(path, "src/rust")
+
+  # if `src/rust` does not exist error
+  if (!dir.exists(src_dir)) {
+    cli::cli_abort(
+      c("{.path src/rust} cannot be found", "i" = "Did you run {.fn use_extendr}?"),
+      class = "rextendr_error"
+    )
+  }
+
+  # if cargo.lock does not exist, cerate it using `cargo update`
+  cargo_lock_fp <- file.path(src_dir, "Cargo.lock")
+
+  if (!file.exists(cargo_lock_fp)) {
+    withr::with_dir(src_dir, {
+      update_res <- processx::run(
+        "cargo",
+        c(
+          "generate-lockfile",
+          "--manifest-path",
+          file.path(src_dir, "Cargo.toml")
+        ),
+        stderr_line_callback = function(x, proc) {
+          if (!grepl("To use vendored sources", x) && x != "") {
+            cli::cat_bullet(stringi::stri_trim_left(x))
+          }
+        }
+      )
+    })
+  }
+
+  if (update_res[["status"]] != 0) {
+    cli::cli_abort(
+      "{.file Cargo.lock} could not be created using {.code cargo generate-lockfile}",
+      class = "rextendr_error"
+    )
+  }
+
+  # vendor crates
+  withr::with_dir(src_dir, {
+    vendor_res <- processx::run(
+      "cargo",
+      c(
+        "vendor",
+        "--locked",
+        "--manifest-path",
+        file.path(src_dir, "Cargo.toml")
+      ),
+      stderr_line_callback = function(x, proc) {
+        if (!grepl("To use vendored sources", x) && x != "") {
+          cli::cat_bullet(stringi::stri_trim_left(x))
+        }
+      }
+    )
+  })
+
+  if (vendor_res[["status"]] != 0) {
+    cli::cli_abort(
+      "{.code cargo vendor} failed",
+      class = "rextendr_error"
+    )
+  }
+
+  # capture vendor-config.toml content
+  config_toml <- stringi::stri_split(vendor_res$stdout, coll = "\n")[[1]]
+
+  # always write to file as cargo vendor catches things like patch.crates-io
+  # and provides the appropriate configuration.
+  brio::write_lines(config_toml, file.path(src_dir, "vendor-config.toml"))
+  cli::cli_alert_info("Writing {.file src/rust/vendor-config.toml}")
+
+  # compress to vendor.tar.xz
+  compress_res <- withr::with_dir(src_dir, {
+    processx::run(
+      "tar", c(
+        "-cJ", "--no-xattrs", "-f", "vendor.tar.xz", "vendor"
+      )
+    )
+  })
+
+  if (compress_res[["status"]] != 0) {
+    cli::cli_abort(
+      "Folder {.path vendor} could not be compressed",
+      class = "rextendr_error"
+    )
+  }
+
+  # create a dataframe of vendored crates
+  vendored <- stringi::stri_split(vendor_res[["stderr"]], coll = "\n")[[1]]
+  trimmed <- stringi::stri_trim_left(vendored)
+  to_remove <- grepl("To use vendored sources", trimmed) | trimmed == ""
+  rows <- stringi::stri_split_fixed(trimmed[!to_remove], pattern = " ")
+
+  res <- purrr::map_dfr(rows, function(x) {
+    data.frame(crate = x[2], version = x[3])
+  })
+
+  # return packages and versions invisibly
+  invisible(res)
+}

_pkgdown.yml

@@ -20,6 +20,7 @@ reference:
   - register_extendr
   - write_license_note
   - clean
+  - cran
 
 - title: Various utility functions
   contents:

inst/templates/cran/Makevars

@@ -0,0 +1,42 @@
+TARGET_DIR = ./rust/target
+LIBDIR = $(TARGET_DIR)/release
+STATLIB = $(LIBDIR)/lib{{{lib_name}}}.a
+PKG_LIBS = -L$(LIBDIR) -l{{{lib_name}}}
+
+all: C_clean
+
+$(SHLIB): $(STATLIB)
+
+CRAN_FLAGS=-j 2 --offline
+CARGOTMP = $(CURDIR)/.cargo
+
+
+$(STATLIB):
+	if [ -f ./rust/vendor.tar.xz ]; then \
+		tar xf rust/vendor.tar.xz && \
+		mkdir -p $(CARGOTMP) && \
+		cp rust/vendor-config.toml $(CARGOTMP)/config.toml; \
+	fi
+
+	# In some environments, ~/.cargo/bin might not be included in PATH, so we need
+	# to set it here to ensure cargo can be invoked. It is appended to PATH and
+	# therefore is only used if cargo is absent from the user's PATH.
+	if [ "$(NOT_CRAN)" != "true" ]; then \
+		export CARGO_HOME=$(CARGOTMP); \
+	fi && \
+		export PATH="$(PATH):$(HOME)/.cargo/bin" && \
+			cargo build $(CRAN_FLAGS) --lib --release --manifest-path=./rust/Cargo.toml --target-dir $(TARGET_DIR) && \
+			echo `cargo --version` && echo `rustc --version`;
+	if [ "$(NOT_CRAN)" != "true" ]; then \
+		rm -Rf $(CARGOTMP) $(VENDOR_DIR) $(LIBDIR)/build; \
+	fi
+
+C_clean:
+	rm -Rf $(SHLIB) $(STATLIB) $(OBJECTS)
+
+clean:
+	rm -Rf $(SHLIB) $(STATLIB) $(OBJECTS) ./rust/target
+
+
+
+

inst/templates/cran/Makevars.win

@@ -0,0 +1,54 @@
+TARGET = $(subst 64,x86_64,$(subst 32,i686,$(WIN)))-pc-windows-gnu
+
+TARGET_DIR = ./rust/target
+LIBDIR = $(TARGET_DIR)/$(TARGET)/release
+STATLIB = $(LIBDIR)/lib{{{lib_name}}}.a
+PKG_LIBS = -L$(LIBDIR) -l{{{lib_name}}} -lws2_32 -ladvapi32 -luserenv -lbcrypt -lntdll
+
+all: C_clean
+
+$(SHLIB): $(STATLIB)
+
+CRAN_FLAGS=-j 2 --offline
+CARGOTMP = $(CURDIR)/.cargo
+
+all: C_clean
+
+$(SHLIB): $(STATLIB)
+
+CRAN_FLAGS=-j 2 --offline
+CARGOTMP = $(CURDIR)/.cargo
+
+$(STATLIB):
+	# uncompress vendored deps
+	if [ -f ./rust/vendor.tar.xz ]; then \
+		tar xf rust/vendor.tar.xz && \
+		mkdir -p $(CARGOTMP) && \
+		cp rust/vendor-config.toml $(CARGOTMP)/config.toml; \
+	fi
+
+	mkdir -p $(TARGET_DIR)/libgcc_mock
+	# `rustc` adds `-lgcc_eh` flags to the compiler, but Rtools' GCC doesn't have
+	# `libgcc_eh` due to the compilation settings. So, in order to please the
+	# compiler, we need to add empty `libgcc_eh` to the library search paths.
+	# For more details, please refer to
+	# https://github.com/r-windows/rtools-packages/blob/2407b23f1e0925bbb20a4162c963600105236318/mingw-w64-gcc/PKGBUILD#L313-L316
+	touch $(TARGET_DIR)/libgcc_mock/libgcc_eh.a
+
+	# CARGO_LINKER is provided in Makevars.ucrt for R >= 4.2
+	if [ "$(NOT_CRAN)" != "true" ]; then \
+		export CARGO_HOME=$(CARGOTMP); \
+	fi && \
+		export CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER="$(CARGO_LINKER)" && \
+		export LIBRARY_PATH="$${LIBRARY_PATH};$(CURDIR)/$(TARGET_DIR)/libgcc_mock"; \
+		cargo build $(CRAN_FLAGS) --target=$(TARGET) --lib --release --manifest-path=./rust/Cargo.toml --target-dir $(TARGET_DIR) && \
+		echo `cargo --version` && echo `rustc --version`;
+	if [ "$(NOT_CRAN)" != "true" ]; then \
+		rm -Rf $(CARGOTMP) $(VENDOR_DIR) $(LIBDIR)/build; \
+	fi
+
+C_clean:
+	rm -Rf $(SHLIB) $(STATLIB) $(OBJECTS)
+
+clean:
+	rm -Rf $(SHLIB) $(STATLIB) $(OBJECTS) $(TARGET_DIR) ./rust/vendor $(CARGO_HOME)

inst/templates/cran/configure

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+
+# https://github.com/eitsupi/prqlr/blob/main/configure
+export PATH="$PATH:$HOME/.cargo/bin"
+
+if [ ! "$(command -v cargo)" ]; then
+    echo "----------------------- [RUST NOT FOUND]---------------------------"
+    echo "The 'cargo' command was not found on the PATH. Please install rustc"
+    echo "from: https://www.rust-lang.org/tools/install"
+    echo ""
+    echo "Alternatively, you may install cargo from your OS package manager:"
+    echo " - Debian/Ubuntu: apt-get install cargo"
+    echo " - Fedora/CentOS: dnf install cargo"
+    echo " - macOS: brew install rustc"
+    echo "-------------------------------------------------------------------"
+    echo ""
+    exit 1
+fi
+
+exit 0
+

inst/templates/cran/configure.win

@@ -0,0 +1,15 @@
+#!/bin/sh
+
+# https://github.com/eitsupi/prqlr/blob/main/configure.win
+export PATH="$PATH:$HOME/.cargo/bin"
+
+if [ ! "$(command -v cargo)" ]; then
+    echo "----------------------- [RUST NOT FOUND]---------------------------"
+    echo "The 'cargo' command was not found on the PATH. Please install rustc"
+    echo "from: https://www.rust-lang.org/tools/install"
+    echo "-------------------------------------------------------------------"
+    echo ""
+    exit 1
+fi
+
+exit 0