Auto merge of #36948 - brson:sys, r=brson

More refactoring to obey platform abstraction lint

The most interesting things here are moving `std/sys/common` to `std/sys_common`, and `std/num/{f32,f64}.rs` to `std/{f32,f64}.rs`, and adding more documentation to `std/lib.rs`.

r? @alexcrichton

Author: bors

src/libstd/num/f32.rs renamed to src/libstd/f32.rs

@@ -289,7 +289,7 @@ mod lazy;
 mod util;
 mod stdio;
 
-const DEFAULT_BUF_SIZE: usize = 8 * 1024;
+const DEFAULT_BUF_SIZE: usize = ::sys_common::io::DEFAULT_BUF_SIZE;
 
 // A few methods below (read_to_string, read_line) will append data into a
 // `String` buffer, but we need to be pretty careful when doing this. The

src/libstd/num/f64.rs renamed to src/libstd/f64.rs

@@ -214,15 +214,7 @@ pub fn stdin() -> Stdin {
             _ => Maybe::Fake
         };
 
-        // The default buffer capacity is 64k, but apparently windows
-        // doesn't like 64k reads on stdin. See #13304 for details, but the
-        // idea is that on windows we use a slightly smaller buffer that's
-        // been seen to be acceptable.
-        Arc::new(Mutex::new(if cfg!(windows) {
-            BufReader::with_capacity(8 * 1024, stdin)
-        } else {
-            BufReader::new(stdin)
-        }))
+        Arc::new(Mutex::new(BufReader::with_capacity(stdio::STDIN_BUF_SIZE, stdin)))
     }
 }
 

src/libstd/io/mod.rs

@@ -210,8 +210,27 @@
        test(no_crate_inject, attr(deny(warnings))),
        test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))]
 
+// Don't link to std. We are std.
+#![no_std]
+
+#![deny(missing_docs)]
+
+// Tell the compiler to link to either panic_abort or panic_unwind
 #![needs_panic_runtime]
 
+// Always use alloc_system during stage0 since jemalloc might be unavailable or
+// disabled (Issue #30592)
+#![cfg_attr(stage0, feature(alloc_system))]
+
+// Turn warnings into errors, but only after stage0, where it can be useful for
+// code to emit warnings during language transitions
+#![cfg_attr(not(stage0), deny(warnings))]
+
+// std may use features in a platform-specific way
+#![allow(unused_features)]
+
+// std is implemented with unstable features, many of which are internal
+// compiler details that will never be stable
 #![feature(alloc)]
 #![feature(allow_internal_unstable)]
 #![feature(asm)]
@@ -248,7 +267,6 @@
 #![feature(link_args)]
 #![feature(linkage)]
 #![feature(macro_reexport)]
-#![cfg_attr(test, feature(map_values_mut))]
 #![feature(needs_panic_runtime)]
 #![feature(num_bits_bytes)]
 #![feature(old_wrapping)]
@@ -284,21 +302,13 @@
 #![feature(zero_one)]
 #![cfg_attr(test, feature(update_panic_count))]
 
-// Issue# 30592: Systematically use alloc_system during stage0 since jemalloc
-// might be unavailable or disabled
-#![cfg_attr(stage0, feature(alloc_system))]
-
-// Don't link to std. We are std.
-#![no_std]
-
-#![deny(missing_docs)]
-#![allow(unused_features)] // std may use features in a platform-specific way
-#![cfg_attr(not(stage0), deny(warnings))]
-
+// Explicitly import the prelude. The compiler uses this same unstable attribute
+// to import the prelude implicitly when building crates that depend on std.
 #[prelude_import]
 #[allow(unused)]
 use prelude::v1::*;
 
+// Access to Bencher, etc.
 #[cfg(test)] extern crate test;
 
 // We want to reexport a few macros from core but libcore has already been
@@ -326,11 +336,22 @@ extern crate alloc_system;
 // compiler-rt intrinsics
 extern crate compiler_builtins;
 
-// Make std testable by not duplicating lang items and other globals. See #2912
+// During testing, this crate is not actually the "real" std library, but rather
+// it links to the real std library, which was compiled from this same source
+// code. So any lang items std defines are conditionally excluded (or else they
+// wolud generate duplicate lang item errors), and any globals it defines are
+// _not_ the globals used by "real" std. So this import, defined only during
+// testing gives test-std access to real-std lang items and globals. See #2912
 #[cfg(test)] extern crate std as realstd;
 
-// NB: These reexports are in the order they should be listed in rustdoc
+// The standard macros that are not built-in to the compiler.
+#[macro_use]
+mod macros;
+
+// The Rust prelude
+pub mod prelude;
 
+// Public module declarations and reexports
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::any;
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -363,48 +384,6 @@ pub use core::raw;
 pub use core::result;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::option;
-
-pub mod error;
-
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use alloc::boxed;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use alloc::rc;
-
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::borrow;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::fmt;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::slice;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::str;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::string;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::vec;
-
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use rustc_unicode::char;
-
-/* Exported macros */
-
-#[macro_use]
-mod macros;
-
-mod rtdeps;
-
-/* The Prelude. */
-
-pub mod prelude;
-
-
-/* Primitive types */
-
-// NB: slice and str are primitive types too, but their module docs + primitive
-// doc pages are inlined from the public re-exports of core_collections::{slice,
-// str} above.
-
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::isize;
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -415,7 +394,6 @@ pub use core::i16;
 pub use core::i32;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::i64;
-
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::usize;
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -426,46 +404,62 @@ pub use core::u16;
 pub use core::u32;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::u64;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use alloc::boxed;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use alloc::rc;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::borrow;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::fmt;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::slice;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::str;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::string;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::vec;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use rustc_unicode::char;
 
-#[path = "num/f32.rs"]   pub mod f32;
-#[path = "num/f64.rs"]   pub mod f64;
-
-pub mod ascii;
-
-/* Common traits */
-
-pub mod num;
-
-/* Runtime and platform support */
+pub mod f32;
+pub mod f64;
 
 #[macro_use]
 pub mod thread;
-
+pub mod ascii;
 pub mod collections;
 pub mod env;
+pub mod error;
 pub mod ffi;
 pub mod fs;
 pub mod io;
 pub mod net;
+pub mod num;
 pub mod os;
 pub mod panic;
 pub mod path;
 pub mod process;
 pub mod sync;
 pub mod time;
-mod memchr;
 
+// Platform-abstraction modules
 #[macro_use]
-#[path = "sys/common/mod.rs"] mod sys_common;
-
-#[cfg(unix)]
-#[path = "sys/unix/mod.rs"] mod sys;
-#[cfg(windows)]
-#[path = "sys/windows/mod.rs"] mod sys;
+mod sys_common;
+mod sys;
 
-pub mod rt;
+// Private support modules
 mod panicking;
 mod rand;
+mod memchr;
+
+// This module just defines per-platform native library dependencies
+mod rtdeps;
+
+// The runtime entry point and a few unstable public functions used by the
+// compiler
+pub mod rt;
 
 // Some external utilities of the standard library rely on randomness (aka
 // rustc_back::TempDir and tests) and need a way to get at the OS rng we've got

src/libstd/io/stdio.rs

@@ -0,0 +1,41 @@
+// Copyright 2016 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Platform-dependent platform abstraction
+//!
+//! The `std::sys` module is the abstracted interface through which
+//! `std` talks to the underlying operating system. It has different
+//! implementations for different operating system families, today
+//! just Unix and Windows.
+//!
+//! The centralization of platform-specific code in this module is
+//! enforced by the "platform abstraction layer" tidy script in
+//! `tools/tidy/pal.rs`.
+//!
+//! This module is closely related to the platform-independent system
+//! integration code in `std::sys_common`. See that module's
+//! documentation for details.
+//!
+//! In the future it would be desirable for the indepedent
+//! implementations of this module to be extracted to their own crates
+//! that `std` can link to, thus enabling their implementation
+//! out-of-tree via crate replacement. Though due to the complex
+//! inter-dependencies within `std` that will be a challenging goal to
+//! achieve.
+
+pub use self::imp::*;
+
+#[cfg(unix)]
+#[path = "unix/mod.rs"]
+mod imp;
+
+#[cfg(windows)]
+#[path = "windows/mod.rs"]
+mod imp;