Use 'rust-toolchain' instead of '.rust-version'

Also interleave the directory override and rust-toolchain directory walk.

Author: brson

README.md

@@ -18,9 +18,10 @@ And it runs on all platforms Rust supports, including Windows.
 * [Keeping Rust up to date](#keeping-rust-up-to-date)
 * [Working with nightly Rust](#working-with-nightly-rust)
 * [Toolchain specification](#toolchain-specification)
-* [Directory overrides](#directory-overrides)
-* [The version file](#the-version-file)
 * [Toolchain override shorthand](#toolchain-override-shorthand)
+* [Directory overrides](#directory-overrides)
+* [The toolchain file](#the-toolchain-file)
+* [Override precedence](#override-precedence)
 * [Cross-compilation](#cross-compilation)
 * [Working with Rust on Windows](#working-with-rust-on-windows)
 * [Working with custom toolchains](#working-with-custom-toolchains-and-local-builds)
@@ -293,13 +294,12 @@ cargo +beta test
 
 ## Directory overrides
 
-Directories can be assigned their own Rust toolchain with
-`rustup override`. When a directory has an override then
-any time `rustc` or `cargo` is run inside that directory,
-or one of its child directories, the override toolchain
-will be invoked.
+Directories can be assigned their own Rust toolchain with `rustup
+override`. When a directory has an override then any time `rustc` or
+`cargo` is run inside that directory, or one of its child directories,
+the override toolchain will be invoked.
 
-To pin to a specific nightly:
+To use to a specific nightly for a directory:
 
 ```
 rustup override set nightly-2014-12-18
@@ -314,7 +314,7 @@ rustup override set 1.0.0
 To see the active toolchain use `rustup show`. To remove the override
 and use the default toolchain again, `rustup override unset`.
 
-## The version file
+## The toolchain file
 
 `rustup` directory overrides are a local configuration, stored in
 `$RUSTUP_HOME`. Some projects though find themselves 'pinned' to a
@@ -323,7 +323,7 @@ source repository. This is most often the case for nightly-only
 software that pins to a revision from the release archives.
 
 In these cases the toolchain can be named in the project's directory
-in a file called `.rust-version`, the content of which is the name of
+in a file called `rust-toolchain`, the content of which is the name of
 a single `rustup` toolchain, and which is suitable to check in to
 source control.
 
@@ -334,8 +334,27 @@ numbers, like '1.0.0', and optionally an archive date, like
 'nightly-2017-01-01'. They may not name custom toolchains, nor
 host-specific toolchains.
 
-The version file has lower precedence than all other methods of
-specifying the toolchain.
+## Override precedence
+
+There are several ways to specify which toolchain `rustup` should
+execute:
+
+* An explicit toolchain, e.g. `cargo +beta`,
+* The `RUSTUP_TOOLCHAIN` environment variable,
+* A directory override, ala `rustup override set beta`,
+* The `rust-toolchain` file,
+* The default toolchain,
+
+and they are prefered by rustup in that order, with the explicit
+toolchain having highest precedence, and the default toolchain having
+the lowest. There is one exception though: directory overrides and the
+`rust-toolchain` file are also preferred by their proximity to the
+current directory. That is, these two override methods are discovered
+by walking up the directory structure toward the filesystem root, and
+`rust-toolchain` file that is closer to the current directory will be
+prefered over a directory override that is further away.
+
+To verify which toolchain is active use `rustup show`.
 
 ## Cross-compilation
 

src/rustup/config.rs

@@ -12,13 +12,13 @@ use rustup_dist::{temp, dist};
 use rustup_utils::utils;
 use toolchain::{Toolchain, UpdateStatus};
 use telemetry_analysis::*;
-use settings::{TelemetryMode, SettingsFile, DEFAULT_METADATA_VERSION};
+use settings::{TelemetryMode, SettingsFile, Settings, DEFAULT_METADATA_VERSION};
 
 #[derive(Debug)]
 pub enum OverrideReason {
     Environment,
     OverrideDB(PathBuf),
-    VersionFile(PathBuf),
+    ToolchainFile(PathBuf),
 }
 
 impl Display for OverrideReason {
@@ -28,7 +28,7 @@ impl Display for OverrideReason {
             OverrideReason::OverrideDB(ref path) => {
                 write!(f, "directory override for '{}'", path.display())
             }
-            OverrideReason::VersionFile(ref path) => {
+            OverrideReason::ToolchainFile(ref path) => {
                 write!(f, "overridden by '{}'", path.display())
             }
         }
@@ -232,20 +232,14 @@ impl Cfg {
             override_ = Some((name.to_string(), OverrideReason::Environment));
         }
 
-        // Then look in the override database
+        // Then walk up the directory tree from 'path' looking for either the
+        // directory in override database, or a `rust-toolchain` file.
         if override_.is_none() {
-            try!(self.settings_file.with(|s| {
-                let name = s.find_override(path, self.notify_handler.as_ref());
-                override_ = name.map(|(name, reason_path)| (name, OverrideReason::OverrideDB(reason_path)));
+            self.settings_file.with(|s| {
+                override_ = self.find_override_from_dir_walk(path, s)?;
 
                 Ok(())
-            }));
-        }
-
-        // Then check the explicit version file
-        if override_.is_none() {
-            let name_path = self.find_override_version_file(path)?;
-            override_ = name_path.map(|(name, path)| (name, OverrideReason::VersionFile(path)));
+            })?;
         }
 
         if let Some((name, reason)) = override_ {
@@ -260,8 +254,8 @@ impl Cfg {
                 OverrideReason::OverrideDB(ref path) => {
                     format!("the directory override for '{}' specifies an uninstalled toolchain", path.display())
                 }
-                OverrideReason::VersionFile(ref path) => {
-                    format!("the version file at '{}' specifies an uninstalled toolchain", path.display())
+                OverrideReason::ToolchainFile(ref path) => {
+                    format!("the toolchain file at '{}' specifies an uninstalled toolchain", path.display())
                 }
             };
 
@@ -286,25 +280,36 @@ impl Cfg {
         }
     }
 
-    /// Starting in path walk up the tree looking for .rust-version
-    fn find_override_version_file(&self, path: &Path) -> Result<Option<(String, PathBuf)>> {
-        let mut path = Some(path);
+    fn find_override_from_dir_walk(&self, dir: &Path, settings: &Settings)
+                                   -> Result<Option<(String, OverrideReason)>>
+    {
+        let notify = self.notify_handler.as_ref();
+        let dir = utils::canonicalize_path(dir, &|n| notify(n.into()));
+        let mut dir = Some(&*dir);
+
+        while let Some(d) = dir {
+            // First check the override database
+            if let Some(name) = settings.dir_override(d, notify) {
+                let reason = OverrideReason::OverrideDB(d.to_owned());
+                return Ok(Some((name, reason)));
+            }
 
-        while let Some(p) = path {
-            let version_file = p.join(".rust-version");
-            if let Ok(s) = utils::read_file("version file", &version_file) {
+            // Then look for 'rust-toolchain'
+            let toolchain_file = d.join("rust-toolchain");
+            if let Ok(s) = utils::read_file("toolchain file", &toolchain_file) {
                 if let Some(s) = s.lines().next() {
                     let toolchain_name = s.trim();
                     dist::validate_channel_name(&toolchain_name)
                         .chain_err(|| format!("invalid channel name '{}' in '{}'",
                                               toolchain_name,
-                                              version_file.display()))?;
+                                              toolchain_file.display()))?;
 
-                    return Ok(Some((toolchain_name.to_string(), version_file)));
+                    let reason = OverrideReason::ToolchainFile(toolchain_file);
+                    return Ok(Some((toolchain_name.to_string(), reason)));
                 }
             }
 
-            path = p.parent();
+            dir = d.parent();
         }
 
         Ok(None)

src/rustup/settings.rs

@@ -162,18 +162,9 @@ impl Settings {
         self.overrides.insert(key, toolchain);
     }
 
-    pub fn find_override(&self, dir_unresolved: &Path, notify_handler: &Fn(Notification))
-            -> Option<(String, PathBuf)> {
-        let dir = utils::canonicalize_path(dir_unresolved, &|n| notify_handler(n.into()));
-        let mut maybe_path = Some(&*dir);
-        while let Some(path) = maybe_path {
-            let key = Self::path_to_key(path, notify_handler);
-            if let Some(toolchain) = self.overrides.get(&key) {
-                return Some((toolchain.to_owned(), path.to_owned()));
-            }
-            maybe_path = path.parent();
-        }
-        None
+    pub fn dir_override(&self, dir: &Path, notify_handler: &Fn(Notification)) -> Option<String> {
+        let key = Self::path_to_key(dir, notify_handler);
+        self.overrides.get(&key).map(|s| s.clone())
     }
 
     pub fn parse(data: &str) -> Result<Self> {