[doc/book] Add introduction page and other enhancements
Preview: http://code.behnam.es/rust-cargo/book/
* Reorganize files to use folders instead of numbered files. This will allow us to add new sections and pages without breaking a numbering system or the URLs.
* Rename "Cargo In Depth" to "Cargo Reference", as those pages are considered *the* reference for cargo behaviors.
* Add `introduction.md`, as the landing page with the book title and Cargo logo on top.
* Expand `installation.md`: Import install text and links from <https://crates.io/install>, as we
want to drop that page and redirect it to here. (See <https://github.com/rust-lang/crates.io/issues/1029>)
* Sync `SUMMARY.md` titles (and sub-pages lists in section pages) with page titles and fix some wordings and casings.
* Expand Introduction and section pages with some intro text.
* Set lang for some of the code blocks.
* Add `book.toml` to get the title in HTML head title, etc.
Tracker: <https://github.com/rust-lang/cargo/issues/4040>
Import mdBook-based docs and sync
Since we decided to keep the mdBook-based docs in-repo, I have imported the existing converted docs from <https://github.com/istankovic/cargo-book> under `/src/doc/book/` here, and have synced the current docs and the mdBook-based ones manually, file-by-file.
I have created a `MIGRATION_MAP` file, which shows the relationship between old docs and new ones. The first column is the old file, the second column is the canonical location in mdBook, and the rest of columns are globs of other files in mdBook containing content from the old file.
The first and second column of `MIGRATION_MAP` shall later be used to create redirect rules from `doc.crates.io/` to `doc.rust-lang.org/cargo/`.
I will also add a README file to remind everyone to keep these files in sync during the migration.
There are also two or three small wording fixes here, which I'll note inline.
This is a retry of <https://github.com/rust-lang/cargo/pull/4220>.
First step for <https://github.com/rust-lang/cargo/issues/4040>.
Add host dependency path via -L for cargo_test.
Proc-macro crates' dependencies in the host dependency directory cannot
be found when running `cargo test` with the `--target {target}` flag
set as reported in #4224. This adds the host dependency directory to the
search path to find those missing dependencies with -L when building tests
and adds a test case that fails before and passes after this patch.
A new function `find_host_deps(..)` is added to accomplish this which can
determine the path of the host dependencies directory from within
`run_doc_tests(..)` where the missing library search path is needed.
Fixes#4224Fixes#4254
Modeled after a similar patch: a298346d6e8862992be3fd93dd8a6c833cc72719
**Concerns**
The test case seems to require a non-local crate from crates.io to example the failure before this patch. Couldn't make it fail with simply another local subcrate, but if others think it's possible that'd be great. This means that during tests for the cargo project itself that this test case actually downloads and compiles a crate, which I don't think any other tests do and is obviously not ideal and is perhaps even unacceptable. I've used the base64 crate pretty arbitrarily, but which crate it is really doesn't matter to test the case's content. So if anyone knows a tiny or empty crate on crates.io to use instead that'd speed this up and if someone can figure out how to make it fail before this patch is applied without downloading an external crate that would help as well.
Also, I'm not 100% confident about the `find_host_deps(..)` style and whether it's the best way to find the host dependencies directory with just the `TestOptions` and `Compilation` structs available since I'm new to this project. Any comments are appreciated.
Minor change causes the test to actually test the case instead of always
passing regardless of the fix that adds the host dependency directory to
the library search path.
The plugins_dylib_path field on Compilation is removed because it is
identical to host_deps_output, it is only used in one easily replaced
location, and because host_deps_output is a more general name that
includes its new usage location in cargo_test.rs as well while better
matching the corresponding deps_output field.
Also de-indents erroneously indented lines in a test case.
This patch removes the addition of the find_host_deps() function by
adding a host_deps_output field to the Compilation struct instead. The
test case is altered to not use an external crate from crates.io but
instead use the Package.publish(..) method.
relax rustdoc tests
This was asserting on the output directly, rather than just what it contains.
In https://github.com/rust-lang/rust/pull/44138 we are adding deprecations, and so it
breaks these tests.
Adding target support to cargo package and cargo publish
Fixing Issue #4012
Same as #4077 but couldn't reopen the PR due to force push after rebasing from master
Proc-macro crates' dependencies in the host dependency directory cannot
be found when running `cargo test` with the `--target {target}` flag
set. This adds the host dependency directory with -L when building tests
and a test case that fails before and passes after this patch.
A new function find_host_deps(..) is added to accomplish this which can
determine the path of the host dependencies directory from within
run_doc_tests(..) where the missing library search path is needed.
Fixes#4224Fixes#4254
