make targets: consider making doc generation part of default target

[pnkfelix]

Currently, if I do make, it builds the compiler and standard library.

If I then do make install, it does a prepare step which runs quickly, then it discovers that it has not yet generated the docs, and so it does a rustdoc run.

The rustdoc step takes a while.

Then after that finishes, it does the rest of the installation, which runs quickly.

My expectation as a developer is that if I download a source distribution and run make followed by make install, the make step could take a long time, but make install should run very fast.

To resolve this conflict, I suggest that we make the default make target also do doc generation, and potentially add some other make target for people who do not want the doc generation step while they are working.

[pnkfelix]

(I recommend no one actually work on implementing this until I get a chance to take the temperature of the team and community.)

[SiegeLord]

This is a bigger issue than just inconvenience, see: #13728.

[pnkfelix]

We discussed this in last night's meeting

[pnkfelix]

So, to summarize the meeting discussion there are several separate issues here:

1. configure --disable-docs is broken; there's a PR for that in mk: Don't build any docs with --disable-docs. #14476.
2. make by default should probably be building all dependencies that make install has, but it currently is not building all such dependencies (leading to this issue).
3. make install is currently building docs (including docs for librustc), but not installing any docs. In the long term, we probably do want make install to install docs in some manner.

[steveklabnik]

This is now fixed, as far as I know.

[pnkfelix]

This did not appear fixed when I did a make install over weekend; some docs were still unbuilt until one ran make install

[steveklabnik]

Okay then! @brson , any idea? I thought this was finished.

[pnkfelix]

/me goes to double-check his claim. ;)

[pnkfelix]

Okay, just to be clear: when I do a fresh checkout, run configure, then make, then make install, the problem I'm talking about is that the last step, the make install, takes too long, because it is spending time actually running rustdoc on various crates.

Here's the summary of what rustdoc invocations are reported during make install immediately after a make:

...
rustdoc: doc/libc/index.html
rustdoc: doc/std/index.html
/Users/fklock/Dev/Mozilla/rust-chk/src/libstd/lib.rs:112:12: 112:26 warning: feature is deprecated and will only be available for a limited time, please rewrite code that relies on it
/Users/fklock/Dev/Mozilla/rust-chk/src/libstd/lib.rs:112 #![feature(old_impl_check)]
                                                                    ^~~~~~~~~~~~~~
/Users/fklock/Dev/Mozilla/rust-chk/src/libstd/lib.rs:112:12: 112:26 warning: feature is deprecated and will only be available for a limited time, please rewrite code that relies on it
/Users/fklock/Dev/Mozilla/rust-chk/src/libstd/lib.rs:112 #![feature(old_impl_check)]
                                                                    ^~~~~~~~~~~~~~
rustdoc: doc/collections/index.html
rustdoc: doc/test/index.html
rustdoc: doc/rand/index.html
rustdoc: doc/rustc/index.html
rustdoc: doc/rustc_trans/index.html
rustdoc: doc/rustc_borrowck/index.html
rustdoc: doc/rustc_resolve/index.html
rustdoc: doc/rustc_typeck/index.html
rustdoc: doc/rustc_driver/index.html
rustdoc: doc/syntax/index.html
rustdoc: doc/rustc_privacy/index.html
build: dist/rustc-1.0.0-dev-x86_64-apple-darwin.tar.gz
...

Though to be honest, watching it now, the time spent in those rustdoc calls is not that bad compared to the amount of time that the amount of time we spend in make install overall.

[steveklabnik]

Ahh yes. It still weirds me out that we do this, and I think there's another issue open...

[steveklabnik]

Triage: no change that I'm aware of.