Added help for rustup toolchain link as documented in issue #954.

src/rustup-cli/help.rs

@@ -32,7 +32,7 @@ r"DISCUSSION:
     'nightly', or '1.8.0'. For more information see `rustup help
     toolchain`.";
 
-pub static TOOLCHAIN_INSTALL_HELP: &'static str =
+pub static INSTALL_HELP: &'static str =
 r"DISCUSSION:
     Installs a specific rust toolchain.
 
@@ -81,8 +81,29 @@ r"DISCUSSION:
 
         $ rustup default stable-msvc
 
-    Toolchain names that don't name a channel instead can be used to
-    name custom toolchains with the `rustup toolchain link` command.";
+    rustup can also manage symlinked local toolchain builds, which are
+    often used to for developing Rust itself. For more information see
+    `rustup toolchain help link`.";
+
+pub static TOOLCHAIN_LINK_HELP: &'static str =
+r"DISCUSSION:
+    'toolchain' is the custom name to be assigned to the new toolchain.
+    Any name is permitted as long as it does not fully match an initial
+    substring of a standard release channel. For example, you can use
+    the names 'latest' or '2017-04-01' but you cannot use 'stable' or
+    'beta-i686' or 'nightly-x86_64-unknown-linux-gnu'.
+
+    'path' specifies the directory where the binaries and libraries for
+    the custom toolchain can be found. For example, when used for
+    development of Rust itself, toolchains can be linked directly out of
+    the build directory. After building, you can test out different
+    compiler versions as follows:
+
+        $ rustup toolchain link latest-stage1 build/x86_64-unknown-linux-gnu/stage1
+        $ rustup override set latest-stage1
+
+    If you now compile a crate in the current directory, the custom
+    toolchain 'latest-stage1' will be used.";
 
 pub static OVERRIDE_HELP: &'static str =
 r"DISCUSSION:

src/rustup-cli/rustup_mode.rs

@@ -128,7 +128,7 @@ pub fn cli() -> App<'static, 'static> {
             .after_help(SHOW_HELP))
         .subcommand(SubCommand::with_name("install")
             .about("Update Rust toolchains")
-            .after_help(TOOLCHAIN_INSTALL_HELP)
+            .after_help(INSTALL_HELP)
             .setting(AppSettings::Hidden) // synonym for 'toolchain install'
             .arg(Arg::with_name("toolchain")
                 .required(true)
@@ -169,6 +169,7 @@ pub fn cli() -> App<'static, 'static> {
                      .multiple(true)))
             .subcommand(SubCommand::with_name("link")
                 .about("Create a custom toolchain by symlinking to a directory")
+                .after_help(TOOLCHAIN_LINK_HELP)
                 .arg(Arg::with_name("toolchain")
                     .required(true))
                 .arg(Arg::with_name("path")

src/rustup-mock/src/clitools.rs

@@ -693,6 +693,8 @@ fn mock_bin(_name: &str, version: &str, version_hash: &str) -> Vec<u8> {
 fn create_custom_toolchains(customdir: &Path) {
     let ref dir = customdir.join("custom-1/bin");
     fs::create_dir_all(dir).unwrap();
+    let ref libdir = customdir.join("custom-1/lib");
+    fs::create_dir_all(libdir).unwrap();
     let rustc = mock_bin("rustc", "1.0.0", "hash-c-1");
     let ref path = customdir.join(format!("custom-1/bin/rustc{}", EXE_SUFFIX));
     let mut file = File::create(path).unwrap();
@@ -701,6 +703,8 @@ fn create_custom_toolchains(customdir: &Path) {
 
     let ref dir = customdir.join("custom-2/bin");
     fs::create_dir_all(dir).unwrap();
+    let ref libdir = customdir.join("custom-2/lib");
+    fs::create_dir_all(libdir).unwrap();
     let rustc = mock_bin("rustc", "1.0.0", "hash-c-2");
     let ref path = customdir.join(format!("custom-2/bin/rustc{}", EXE_SUFFIX));
     let mut file = File::create(path).unwrap();

src/rustup/toolchain.rs

@@ -275,6 +275,16 @@ impl<'a> Toolchain<'a> {
     pub fn install_from_dir(&self, src: &Path, link: bool) -> Result<()> {
         try!(self.ensure_custom());
 
+        let mut pathbuf = PathBuf::from(src);
+
+        pathbuf.push("lib");
+        try!(utils::assert_is_directory(&pathbuf));
+        pathbuf.pop();
+        pathbuf.push("bin");
+        try!(utils::assert_is_directory(&pathbuf));
+        pathbuf.push(format!("rustc{}", EXE_SUFFIX));
+        try!(utils::assert_is_file(&pathbuf));
+
         if link {
             try!(self.install(InstallMethod::Link(&try!(utils::to_absolute(src)))));
         } else {

tests/cli-misc.rs

@@ -306,10 +306,11 @@ fn rustup_failed_path_search() {
         let ref tool_path = config.exedir.join(&format!("fake_proxy{}", EXE_SUFFIX));
         utils::hardlink_file(rustup_path, tool_path).expect("Failed to create fake proxy for test");
 
-        expect_ok(config, &["rustup", "toolchain", "link", "empty", &config.emptydir.to_string_lossy()]);
-        let broken = &["rustup", "run", "empty", "fake_proxy"];
+        expect_ok(config, &["rustup", "toolchain", "link", "custom",
+                            &config.customdir.join("custom-1").to_string_lossy()]);
+        let broken = &["rustup", "run", "custom", "fake_proxy"];
         expect_err(config, broken, &format!(
-            "toolchain 'empty' does not have the binary `fake_proxy{}`", EXE_SUFFIX
+            "toolchain 'custom' does not have the binary `fake_proxy{}`", EXE_SUFFIX
         ));
 
         // Hardlink will be automatically cleaned up by test setup code