Fixing rustdoc stage1.

See #13983 and #14000.

Fix was originally authored by alexcrichton and then rebased a couple
times by pnkfelix, most recently atop PR 13954.

----

Regarding the change to librustdoc/lib.rs, to do `map_err` before
unwrapping a `TqskResult`: I do not understand how master is passing
without this change or something like it, since `Box<Any:Send>` does
not implement `Show`.  (Is this something that is only a problem for
the snapshot stage0 compiler?)  Still, the change I have put in here
(which was added as part of a rebase after alex's review) seems
harmless to me to apply to rustdoc at all stages, since a call to
`unwrap` is just going to `fail!` on the err case anyway.
Include file paths when dumping the list of resolved crates via `debug!`.
Output debug info on how `#[phase] extern crate foo;` gets resolved.
Refactoring: Introduce distinct host and target rpath var setters.

Two line summary: Distinguish HOST_RPATH and TARGET_RPATH; added
RPATH_LINK_SEARCH; skip tests broken in stage1; general cleanup.

`HOST_RPATH_VAR$(1)_T_$(2)_H_$(3)` and `TARGET_RPATH_VAR$(1)_T_$(2)_H_$(3)`
both match the format of the old `RPATH_VAR$(1)_T_$(2)_H_$(3)` (which
is still being set the same way that it was before, to one of either
HOST/TARGET depending on what stage we are building).  Namely, the format
is <XXX>_RPATH_VAR = "<LD_LIB_PATH_ENVVAR>=<COLON_SEP_PATH_ENTRIES>"

What this commit does:

* Pass both of the (newly introduced) HOST and TARGET rpath setup vars
  to `maketest.py`

* Update `maketest.py` to no longer update the LD_LIBRARY_PATH itself
  Instead, it passes along the HOST and TARGET rpath setup vars in
  environment variables `HOST_RPATH_ENV` and `TARGET_RPATH_ENV`

* Also, pass the current stage number to maketest.py; it in turn
  passes it (via an env var) to run-make tests.

  This allows the run-make tests to selectively change behavior
  (e.g. turn themselves off) to deal with incompatibilities with
  e.g. stage1.

* Cleanup: Distinguish in tools.mk between the command to run (`RUN`)
  and the file to generate to drive that command (`RUN_BINFILE`).  The
  main thing this enables is that `RUN` can now setup the
  `TARGET_RPATH_ENV` without having to dirty up the runner code in
  each of the `run-make` Makefiles.

* Cleanup: Factored out commands to delete dylib/rlib into
  REMOVE_DYLIBS/REMOVE_RLIBS.

  There were places where we were only calling `rm $(call DYLIB,foo)`
  even though we really needed to get rid of the whole glob (at least
  based on alex's findings on #13753 that removing the symlink does not
  suffice).

  Therefore rather than peppering the code with the awkward
  `rm $(TMPDIR)/$(call DYLIB_GLOB,foo)`, I instead introduced a common
  `REMOVE_DYLIBS` user function that expands into that when called.
  After I adding an analogous `REMOVE_RLIBS`, I changed all of the
  existing calls that rm dylibs or rlibs to use these routines
  instead.

  Note that the latter is not a true refactoring since I may have
  changed cases where it was our intent to only remove the sym-link.
  (But if that is the case, then we need to more deeply investigate
  alex's findings on #13753 where the system was still dynamically
  loading up the non-symlinked libraries that it finds on the load
  path.)

* Added RPATH_LINK_SEARCH command and use it on Linux.

  On some platforms, namely Linux, when you have libboot.so that has
  its internal rpath set (to e.g. $(ORIGIN)/path/to/HOSTDIR), the
  linker still complains when you do the link step and it does not
  know where to find libraries that libboot.so depends upon that live
  in HOSTDIR (think e.g. librustuv.so).

  As far as I can tell, the GNU linker will consult the
  LD_LIBRARY_PATH as part of the linking process to find such
  libraries.  But if you want to be more careful and not override
  LD_LIBRARY_PATH for the `gcc` invocation, then you need some other
  way to tell the linker where it can find the libraries that
  libboot.so needs.  The solution to this on Linux is the
  `-Wl,-rpath-link` command line option.

  However, this command line option does not exist on Mac OS X, (which
  appears to be figuring out how to resolve the libboot.dylib
  dependency by some other means, perhaps by consulting the rpath
  setting within libboot.dylib).

  So, in order to abstract over this distinction, I added the
  RPATH_LINK_SEARCH macro to the run-make infrastructure and added
  calls to it where necessary to get Linux working.  On architectures
  other than Linux, the macro expands to nothing.

* Disable miscellaneous tests atop stage1.

* An especially interesting instance of the previous bullet point:
  Excuse regex from doing rustdoc tests atop stage1.

  This was a (nearly-) final step to get `make check-stage1` working
  again.

  The use of a special-case check for regex here is ugly but is
  analogous other similar checks for regex such as the one that landed
  in PR #13844.

  The way this is written, the user will get a reminder that
  doc-crate-regex is being skipped whenever their rules attempt to do
  the crate documentation tests.  This is deliberate: I want people
  running `make check-stage1` to be reminded about which cases are
  being skipped.  (But if such echo noise is considered offensive, it
  can obviously be removed.)

* Got windows working with the above changes.

  This portion of the commit is a cleanup revision of the (previously
  mentioned on try builds) re-architecting of how the LD_LIBRARY_PATH
  setup and extension is handled in order to accommodate Windows' (1.)
  use of `$PATH` for that purpose and (2.) use of spaces in `$PATH`
  entries (problematic for make and for interoperation with tools at
  the shell).

* In addition, since the code has been rearchitected to pass the
  HOST_RPATH_DIR/TARGET_RPATH_DIR rather than a whole sh
  environment-variable setting command, there is no need to for the
  convert_path_spec calls in maketest.py, which in fact were put in
  place to placate Windows but were now causing the Windows builds to
  fail.  Instead we just convert the paths to absolute paths just like
  all of the other path arguments.

Also, note for makefile hackers: apparently you cannot quote operands
to `ifeq` in Makefile (or at least, you need to be careful about
adding them, e.g. to only one side).
auto merge of #14000 : pnkfelix/rust/fsk-fix-issue13732, r=alexcrichton

Fix #13732.

This is a revised, much less hacky form of PR #13753

The changes here:

 * add instrumentation to aid debugging of linkage errors,
 * fine tune some things in the Makefile where we are telling binaries to use a host-oriented path for finding dynamic libraries, when it should be feeding the binaries a target-oriented path for dynamic libraries.
 * pass along the current stage number to run-make tests, and
 * skip certain tests when running atop stage1.

Fix #13746 as well.