Add preliminary support for running doctests.

This partially addresses #225.

This only works on nightly, due to the use of the unstable feature [doctest-xcompile](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#doctest-xcompile)

The relevant tracking issues are:
- rust-lang/cargo#7040
- rust-lang/rust#64245

If the subcommand is `test` and the compiler is nightly, we provide the `-Zdoctest-xcompile` flag if `CROSS_UNSTABLE_ENABLE_DOCTESTS=true`.

README.md

@@ -207,6 +207,15 @@ passthrough = [
 ]
 ```
 
+### Unstable Features
+
+Certain unstable features can enable additional functionality useful to 
+cross-compiling. Note that these are unstable, and may be removed at any
+time (particularly if the feature is stabilized or removed), and will
+only be used on a nightly channel.
+
+- `CROSS_UNSTABLE_ENABLE_DOCTESTS=true`: also run doctests.
+
 ### Mounting volumes into the build environment
 
 In addition to passing environment variables, you can also specify environment

src/cli.rs

@@ -14,6 +14,7 @@ pub struct Args {
     pub target: Option<Target>,
     pub target_dir: Option<PathBuf>,
     pub docker_in_docker: bool,
+    pub enable_doctests: bool,
 }
 
 // Fix for issue #581. target_dir must be absolute.
@@ -75,6 +76,9 @@ pub fn parse(target_list: &TargetList) -> Result<Args> {
     let docker_in_docker = env::var("CROSS_DOCKER_IN_DOCKER")
         .map(|s| bool::from_str(&s).unwrap_or_default())
         .unwrap_or_default();
+    let enable_doctests = env::var("CROSS_UNSTABLE_ENABLE_DOCTESTS")
+        .map(|s| bool::from_str(&s).unwrap_or_default())
+        .unwrap_or_default();
 
     Ok(Args {
         all,
@@ -83,5 +87,6 @@ pub fn parse(target_list: &TargetList) -> Result<Args> {
         target,
         target_dir,
         docker_in_docker,
+        enable_doctests,
     })
 }

src/main.rs

@@ -279,6 +279,7 @@ fn run() -> Result<ExitStatus> {
 
     let host_version_meta =
         rustc_version::version_meta().wrap_err("couldn't fetch the `rustc` version")?;
+    let is_nightly = rustc::is_nightly(&args.channel, &host_version_meta);
     if let Some(root) = cargo::root()? {
         let host = host_version_meta.host();
         let toml = toml(&root)?;
@@ -358,7 +359,7 @@ fn run() -> Result<ExitStatus> {
                 .map(|sc| sc.needs_interpreter())
                 .unwrap_or(false);
 
-            let filtered_args = if args
+            let mut filtered_args = if args
                 .subcommand
                 .map_or(false, |s| !s.needs_target_in_command())
             {
@@ -384,6 +385,11 @@ fn run() -> Result<ExitStatus> {
                 args.all.clone()
             };
 
+            let is_test = args.subcommand.map(|sc| sc == Subcommand::Test).unwrap_or(false);
+            if is_test && args.enable_doctests && is_nightly {
+                filtered_args.push("-Zdoctest-xcompile".to_string());
+            }
+
             if target.needs_docker() && args.subcommand.map(|sc| sc.needs_docker()).unwrap_or(false)
             {
                 if host_version_meta.needs_interpreter()

src/rustc.rs

@@ -1,7 +1,7 @@
 use std::path::PathBuf;
 use std::process::Command;
 
-use rustc_version::{Version, VersionMeta};
+use rustc_version::{Channel, Version, VersionMeta};
 
 use crate::errors::*;
 use crate::extensions::CommandExt;
@@ -33,6 +33,14 @@ impl VersionMetaExt for VersionMeta {
     }
 }
 
+pub fn is_nightly(channel: &Option<String>, host_version_meta: &VersionMeta) -> bool {
+    if let Some(channel) = channel {
+        channel.contains("nightly")
+    } else {
+        host_version_meta.channel == Channel::Nightly
+    }
+}
+
 pub fn target_list(verbose: bool) -> Result<TargetList> {
     Command::new("rustc")
         .args(&["--print", "target-list"])