Better document default_device_type() (#800)

* Switch to Cairo as the preferred fallback device

* Try to confirm a hypothesis

* Rework `default_device_type()` to be very clear about per OS behavior

* Remove hypothesis

Author: DavisVaughan

crates/ark/src/modules/positron/graphics.R

@@ -409,14 +409,72 @@ default_resolution_in_pixels_per_inch <- function() {
     }
 }
 
+#' Determines the default device `type` for png, jpeg, and tiff
+#'
+#' Only applicable when ragg is not in use
 default_device_type <- function() {
+    switch(
+        system_os(),
+        macos = default_device_type_macos(),
+        windows = default_device_type_windows(),
+        linux = default_device_type_linux(),
+        # Treat `other` as linux
+        other = default_device_type_linux()
+    )
+}
+
+#' On MacOS, we prefer Quartz
+#'
+#' At one point we considered preferring Cairo, but `capabilities("cairo")`
+#' isn't a reliable signal of whether or not you have Cairo support, because
+#' surprisingly you also need xquartz installed as well, i.e. with `brew install
+#' --cask xquartz`. Confusingly you don't need that to use the `"quartz"` type.
+#' https://github.com/posit-dev/positron/issues/913
+#' https://github.com/posit-dev/positron/issues/2919
+#'
+#' From https://cran.r-project.org/doc/manuals/r-release/R-admin.html#Installing-R-under-macOS-1:
+#' "Various parts of the build require XQuartz to be installed...This is also
+#' needed for some builds of the cairographics-based devices...such as
+#' png(type = "cairo") and svg()..."
+#'
+#' To avoid this issue for Mac users, we don't even consider Cairo in our
+#' fallback path. It seems unlikely we'd ever get past `"quartz"` as the
+#' fallback anyways, it's probably installed on all Macs.
+default_device_type_macos <- function() {
     if (has_aqua()) {
         "quartz"
-    } else if (has_cairo()) {
+    } else if (has_x11()) {
+        "Xlib"
+    } else {
+        stop_no_plotting_capabilities()
+    }
+}
+
+#' On Windows, we prefer Cairo
+#'
+#' According to Thomas, this is much preferred over the default on Windows,
+#' which uses the Windows GDI. We don't even offer that as a fallback.
+default_device_type_windows <- function() {
+    if (has_cairo()) {
+        "cairo"
+    } else {
+        stop_no_plotting_capabilities()
+    }
+}
+
+#' On Linux, we prefer Cairo
+#'
+#' This is the default there, and we have no reason to move away from it.
+default_device_type_linux <- function() {
+    if (has_cairo()) {
         "cairo"
     } else if (has_x11()) {
         "Xlib"
     } else {
-        stop("This version of R wasn't built with plotting capabilities")
+        stop_no_plotting_capabilities()
     }
 }
+
+stop_no_plotting_capabilities <- function() {
+    stop("This version of R wasn't built with plotting capabilities")
+}

crates/ark/src/modules/positron/system.R

@@ -1,10 +1,26 @@
-is_macos <- function() {
-    Sys.info()[["sysname"]] == "Darwin"
+#' One of:
+#' - "macos"
+#' - "windows"
+#' - "linux"
+#' - "other"
+system_os <- function() {
+    switch(
+        tolower(Sys.info()[["sysname"]]),
+        darwin = "macos",
+        windows = "windows",
+        linux = "linux",
+        # For example, possibly `sunos`, but very unlikely
+        "other"
+    )
 }
 
 has_aqua <- function() {
-    is_macos() && capabilities("aqua")
+    capabilities("aqua")
 }
+# Here be dragons! On MacOS, this will return `TRUE`, but you won't be able to
+# use `png(type = "cairo")` or `svg()` unless xquartz is also installed too,
+# i.e. with `brew install --cask xquartz`. So we can't use this as a reliable
+# indicator of Cairo graphics support on MacOS.
 has_cairo <- function() {
     capabilities("cairo")
 }