Add preliminary support for running doctests.

This partially addresses cross-rs#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`.

CHANGELOG.md

@@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 
 - #722 - boolean environment variables are evaluated as truthy or falsey.
+- #721 - add support for running doctests on nightly if `CROSS_UNSTABLE_ENABLE_DOCTESTS=true`.
 - #718 - remove deb subcommand.
 - #714 - use host target directory when falling back to host cargo.
 - #713 - convert relative target directories to absolute paths.

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.
@@ -85,6 +86,9 @@ pub fn parse(target_list: &TargetList) -> Result<Args> {
     let docker_in_docker = env::var("CROSS_DOCKER_IN_DOCKER")
         .map(|s| bool_from_envvar(&s))
         .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,
@@ -93,5 +97,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,14 @@ 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"])