From 09cf2bf20373453cf63738f35f78695e4ecc031c Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 27 Jun 2019 21:54:22 -0700 Subject: [PATCH 1/3] add flag to optionally document dev dependencies --- src/bin/cargo/commands/doc.rs | 13 +++++++++++++ src/cargo/core/compiler/build_config.rs | 3 +++ .../core/compiler/context/unit_dependencies.rs | 3 +++ 3 files changed, 19 insertions(+) diff --git a/src/bin/cargo/commands/doc.rs b/src/bin/cargo/commands/doc.rs index 8405015dfbb..df646d66177 100644 --- a/src/bin/cargo/commands/doc.rs +++ b/src/bin/cargo/commands/doc.rs @@ -29,6 +29,11 @@ pub fn cli() -> App { .arg_target_dir() .arg_manifest_path() .arg_message_format() + .arg( + Arg::with_name("dev") + .long("dev") + .help("Include dev dependencies in documentation"), + ) .after_help( "\ By default the documentation for the local package and all dependencies is @@ -52,6 +57,14 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult { deps: !args.is_present("no-deps"), }; let mut compile_opts = args.compile_options(config, mode, Some(&ws))?; + let document_devdeps = args.is_present("dev"); + if document_devdeps && !config.cli_unstable().unstable_options { + return Err(failure::format_err!( + "`cargo doc --dev` is unstable, pass `-Z unstable-options` to enable it" + ) + .into()); + } + compile_opts.build_config.document_dev_dependencies = document_devdeps; compile_opts.local_rustdoc_args = if args.is_present("document-private-items") { Some(vec!["--document-private-items".to_string()]) } else { diff --git a/src/cargo/core/compiler/build_config.rs b/src/cargo/core/compiler/build_config.rs index f5fbe119354..8789f8104b6 100644 --- a/src/cargo/core/compiler/build_config.rs +++ b/src/cargo/core/compiler/build_config.rs @@ -27,6 +27,8 @@ pub struct BuildConfig { /// An optional wrapper, if any, used to wrap rustc invocations pub rustc_wrapper: Option, pub rustfix_diagnostic_server: RefCell>, + /// Wheather or not to document development dependencies + pub document_dev_dependencies: bool, /// Whether or not Cargo should cache compiler output on disk. cache_messages: bool, } @@ -100,6 +102,7 @@ impl BuildConfig { build_plan: false, rustc_wrapper: None, rustfix_diagnostic_server: RefCell::new(None), + document_dev_dependencies: false, cache_messages: config.cli_unstable().cache_messages, }) } diff --git a/src/cargo/core/compiler/context/unit_dependencies.rs b/src/cargo/core/compiler/context/unit_dependencies.rs index db0744476c7..986adea97b4 100644 --- a/src/cargo/core/compiler/context/unit_dependencies.rs +++ b/src/cargo/core/compiler/context/unit_dependencies.rs @@ -299,6 +299,9 @@ fn compute_deps_doc<'a, 'cfg, 'tmp>( .filter(|&(_id, deps)| { deps.iter().any(|dep| match dep.kind() { DepKind::Normal => bcx.dep_platform_activated(dep, unit.kind), + DepKind::Development if bcx.build_config.document_dev_dependencies => { + bcx.dep_platform_activated(dep, unit.kind) + } _ => false, }) }); From 3fd20497743d3233854ef617f83ad348b73132c3 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Tue, 9 Jul 2019 18:54:05 -0700 Subject: [PATCH 2/3] a bit more stuff --- src/bin/cargo/commands/doc.rs | 32 ++++++++++++----- src/bin/cargo/commands/rustdoc.rs | 4 ++- src/cargo/core/compiler/build_config.rs | 36 ++++++++++++++----- .../compiler/context/unit_dependencies.rs | 20 +++++++++-- src/cargo/core/compiler/mod.rs | 2 +- src/cargo/util/command_prelude.rs | 2 +- tests/testsuite/rustdoc.rs | 4 +++ 7 files changed, 77 insertions(+), 23 deletions(-) diff --git a/src/bin/cargo/commands/doc.rs b/src/bin/cargo/commands/doc.rs index df646d66177..f7c688f414d 100644 --- a/src/bin/cargo/commands/doc.rs +++ b/src/bin/cargo/commands/doc.rs @@ -30,9 +30,12 @@ pub fn cli() -> App { .arg_manifest_path() .arg_message_format() .arg( - Arg::with_name("dev") - .long("dev") - .help("Include dev dependencies in documentation"), + Arg::with_name("dep-mode") + .long("dep-mode") + .help("Configure the set of dependencies to document") + .takes_value(true) + .possible_values(&["dev", "normal", "all", "build"]) + .default_value("normal"), ) .after_help( "\ @@ -53,18 +56,29 @@ the `cargo help pkgid` command. pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult { let ws = args.workspace(config)?; - let mode = CompileMode::Doc { - deps: !args.is_present("no-deps"), + let dep_mode = if args.is_present("no-deps") { + DepDocMode::NoDeps + } else { + match args.value_of("dev") { + Some("dev") => DepDocMode::Development, + Some("all") => DepDocMode::All, + Some("build") => DepDocMode::Build, + _ => DepDocMode::Normal, + } }; + let mode = CompileMode::Doc { dep_mode }; let mut compile_opts = args.compile_options(config, mode, Some(&ws))?; - let document_devdeps = args.is_present("dev"); - if document_devdeps && !config.cli_unstable().unstable_options { + + if !config.cli_unstable().unstable_options + && dep_mode != DepDocMode::Normal + && dep_mode != DepDocMode::NoDeps + { return Err(failure::format_err!( - "`cargo doc --dev` is unstable, pass `-Z unstable-options` to enable it" + "`cargo doc --dep-mode` is unstable, pass `-Z unstable-options` to enable it" ) .into()); } - compile_opts.build_config.document_dev_dependencies = document_devdeps; + compile_opts.local_rustdoc_args = if args.is_present("document-private-items") { Some(vec!["--document-private-items".to_string()]) } else { diff --git a/src/bin/cargo/commands/rustdoc.rs b/src/bin/cargo/commands/rustdoc.rs index 6616dc70e18..575e15ba218 100644 --- a/src/bin/cargo/commands/rustdoc.rs +++ b/src/bin/cargo/commands/rustdoc.rs @@ -53,7 +53,9 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult { let ws = args.workspace(config)?; let mut compile_opts = args.compile_options_for_single_package( config, - CompileMode::Doc { deps: false }, + CompileMode::Doc { + dep_mode: DepDocMode::Normal, + }, Some(&ws), )?; let target_args = values(args, "args"); diff --git a/src/cargo/core/compiler/build_config.rs b/src/cargo/core/compiler/build_config.rs index 8789f8104b6..84629c03265 100644 --- a/src/cargo/core/compiler/build_config.rs +++ b/src/cargo/core/compiler/build_config.rs @@ -27,8 +27,6 @@ pub struct BuildConfig { /// An optional wrapper, if any, used to wrap rustc invocations pub rustc_wrapper: Option, pub rustfix_diagnostic_server: RefCell>, - /// Wheather or not to document development dependencies - pub document_dev_dependencies: bool, /// Whether or not Cargo should cache compiler output on disk. cache_messages: bool, } @@ -102,7 +100,6 @@ impl BuildConfig { build_plan: false, rustc_wrapper: None, rustfix_diagnostic_server: RefCell::new(None), - document_dev_dependencies: false, cache_messages: config.cli_unstable().cache_messages, }) } @@ -151,14 +148,24 @@ pub enum CompileMode { /// allows some de-duping of Units to occur. Bench, /// A target that will be documented with `rustdoc`. - /// If `deps` is true, then it will also document all dependencies. - Doc { deps: bool }, + /// `dep_mode` determines what set of packages will be documented. + Doc { dep_mode: DepDocMode }, /// A target that will be tested with `rustdoc`. Doctest, /// A marker for Units that represent the execution of a `build.rs` script. RunCustomBuild, } +/// Specific mode for rustdoc to use when documenting dependencies +#[derive(Clone, Copy, PartialEq, Debug, Eq, Hash, PartialOrd, Ord)] +pub enum DepDocMode { + Normal, + Development, + Build, + NoDeps, + All, +} + impl ser::Serialize for CompileMode { fn serialize(&self, s: S) -> Result where @@ -219,14 +226,27 @@ impl CompileMode { /// List of all modes (currently used by `cargo clean -p` for computing /// all possible outputs). pub fn all_modes() -> &'static [CompileMode] { - static ALL: [CompileMode; 9] = [ + static ALL: [CompileMode; 12] = [ CompileMode::Test, CompileMode::Build, CompileMode::Check { test: true }, CompileMode::Check { test: false }, CompileMode::Bench, - CompileMode::Doc { deps: true }, - CompileMode::Doc { deps: false }, + CompileMode::Doc { + dep_mode: DepDocMode::Build, + }, + CompileMode::Doc { + dep_mode: DepDocMode::All, + }, + CompileMode::Doc { + dep_mode: DepDocMode::NoDeps, + }, + CompileMode::Doc { + dep_mode: DepDocMode::Normal, + }, + CompileMode::Doc { + dep_mode: DepDocMode::Development, + }, CompileMode::Doctest, CompileMode::RunCustomBuild, ]; diff --git a/src/cargo/core/compiler/context/unit_dependencies.rs b/src/cargo/core/compiler/context/unit_dependencies.rs index 986adea97b4..887116ef3e4 100644 --- a/src/cargo/core/compiler/context/unit_dependencies.rs +++ b/src/cargo/core/compiler/context/unit_dependencies.rs @@ -16,7 +16,7 @@ //! graph of `Unit`s, which capture these properties. use crate::core::compiler::Unit; -use crate::core::compiler::{BuildContext, CompileMode, Context, Kind}; +use crate::core::compiler::{BuildContext, CompileMode, Context, DepDocMode, Kind}; use crate::core::dependency::Kind as DepKind; use crate::core::package::Downloads; use crate::core::profiles::UnitFor; @@ -293,13 +293,24 @@ fn compute_deps_doc<'a, 'cfg, 'tmp>( state: &mut State<'a, 'cfg, 'tmp>, ) -> CargoResult, UnitFor)>> { let bcx = state.cx.bcx; + + let dep_mode = match bcx.build_config.mode { + CompileMode::Doc { dep_mode } => dep_mode, + _ => unreachable!(), + }; + let deps = bcx .resolve .deps(unit.pkg.package_id()) .filter(|&(_id, deps)| { deps.iter().any(|dep| match dep.kind() { DepKind::Normal => bcx.dep_platform_activated(dep, unit.kind), - DepKind::Development if bcx.build_config.document_dev_dependencies => { + DepKind::Development + if dep_mode == DepDocMode::Development || dep_mode == DepDocMode::All => + { + bcx.dep_platform_activated(dep, unit.kind) + } + DepKind::Build if dep_mode == DepDocMode::Build || dep_mode == DepDocMode::All => { bcx.dep_platform_activated(dep, unit.kind) } _ => false, @@ -325,7 +336,10 @@ fn compute_deps_doc<'a, 'cfg, 'tmp>( let dep_unit_for = UnitFor::new_normal().with_for_host(lib.for_host()); let lib_unit = new_unit(bcx, dep, lib, dep_unit_for, unit.kind.for_target(lib), mode); ret.push((lib_unit, dep_unit_for)); - if let CompileMode::Doc { deps: true } = unit.mode { + if (CompileMode::Doc { + dep_mode: DepDocMode::NoDeps, + }) != unit.mode + { // Document this lib as well. let doc_unit = new_unit( bcx, diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs index 628ac8bbff8..9e8e6afa392 100644 --- a/src/cargo/core/compiler/mod.rs +++ b/src/cargo/core/compiler/mod.rs @@ -24,7 +24,7 @@ use log::debug; use same_file::is_same_file; use serde::Serialize; -pub use self::build_config::{BuildConfig, CompileMode, MessageFormat}; +pub use self::build_config::{BuildConfig, CompileMode, DepDocMode, MessageFormat}; pub use self::build_context::{BuildContext, FileFlavor, TargetConfig, TargetInfo}; use self::build_plan::BuildPlan; pub use self::compilation::{Compilation, Doctest}; diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index b8f208ea3e3..511ecf00857 100644 --- a/src/cargo/util/command_prelude.rs +++ b/src/cargo/util/command_prelude.rs @@ -15,7 +15,7 @@ use crate::util::{ use crate::CargoResult; use clap::{self, SubCommand}; -pub use crate::core::compiler::CompileMode; +pub use crate::core::compiler::{CompileMode, DepDocMode}; pub use crate::{CliError, CliResult, Config}; pub use clap::{AppSettings, Arg, ArgMatches}; diff --git a/tests/testsuite/rustdoc.rs b/tests/testsuite/rustdoc.rs index 6525054444f..9072c622f0f 100644 --- a/tests/testsuite/rustdoc.rs +++ b/tests/testsuite/rustdoc.rs @@ -61,7 +61,11 @@ fn rustdoc_foo_with_bar_dependency() { foo.cargo("rustdoc -v -- --cfg=foo") .with_stderr( "\ +[DOCUMENTING] bar v0.0.1 ([..]) [CHECKING] bar v0.0.1 ([..]) +[RUNNING] `rustdoc --crate-name bar [..]\ + -o [CWD]/target/doc \ + -L dependency=[CWD]/target/debug/deps` [RUNNING] `rustc [..]bar/src/lib.rs [..]` [DOCUMENTING] foo v0.0.1 ([CWD]) [RUNNING] `rustdoc --crate-name foo src/lib.rs [..]\ From 1013c60d96cd214ad125a44d9d6f272d33909af1 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 11 Jul 2019 10:59:39 -0700 Subject: [PATCH 3/3] fix the rustdoc subcommand --- src/bin/cargo/commands/rustdoc.rs | 2 +- tests/testsuite/rustdoc.rs | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/src/bin/cargo/commands/rustdoc.rs b/src/bin/cargo/commands/rustdoc.rs index 575e15ba218..3e676c6544d 100644 --- a/src/bin/cargo/commands/rustdoc.rs +++ b/src/bin/cargo/commands/rustdoc.rs @@ -54,7 +54,7 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult { let mut compile_opts = args.compile_options_for_single_package( config, CompileMode::Doc { - dep_mode: DepDocMode::Normal, + dep_mode: DepDocMode::NoDeps, }, Some(&ws), )?; diff --git a/tests/testsuite/rustdoc.rs b/tests/testsuite/rustdoc.rs index 9072c622f0f..6525054444f 100644 --- a/tests/testsuite/rustdoc.rs +++ b/tests/testsuite/rustdoc.rs @@ -61,11 +61,7 @@ fn rustdoc_foo_with_bar_dependency() { foo.cargo("rustdoc -v -- --cfg=foo") .with_stderr( "\ -[DOCUMENTING] bar v0.0.1 ([..]) [CHECKING] bar v0.0.1 ([..]) -[RUNNING] `rustdoc --crate-name bar [..]\ - -o [CWD]/target/doc \ - -L dependency=[CWD]/target/debug/deps` [RUNNING] `rustc [..]bar/src/lib.rs [..]` [DOCUMENTING] foo v0.0.1 ([CWD]) [RUNNING] `rustdoc --crate-name foo src/lib.rs [..]\