---

yaml
---
r: 95301
b: refs/heads/dist-snap
c: 88593fc
h: refs/heads/master
i:
  95299: 6d82866
v: v3

Author: alexcrichton

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: c274a6888410ce3e357e014568b43310ed787d36
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: 147ecfdd8221e4a4d4e090486829a06da1e0ca3c
-refs/heads/dist-snap: a1ffb06ac828f689af428b715cdd601a41021862
+refs/heads/dist-snap: 88593fc3fc808e78dd89be95c997c94ba4c816da
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503
 refs/heads/try3: 9387340aab40a73e8424c48fd42f0c521a4875c0

branches/dist-snap/src/librustc/rustc.rs

@@ -194,9 +194,6 @@ pub fn describe_debug_flags() {
 }
 
 pub fn run_compiler(args: &[~str], demitter: @diagnostic::Emitter) {
-    // Don't display log spew by default. Can override with RUST_LOG.
-    ::std::logging::console_off();
-
     let mut args = args.to_owned();
     let binary = args.shift().to_managed();
 

branches/dist-snap/src/libstd/logging.rs

@@ -8,40 +8,101 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Logging
+/*!
 
-use fmt;
-use option::*;
-use os;
-use rt;
-use rt::logging::{Logger, StdErrLogger};
+Logging
 
-/// Turns on logging to stdout globally
-pub fn console_on() {
-    rt::logging::console_on();
-}
+This module is used by the compiler when emitting output for the logging family
+of macros. The methods of this module shouldn't necessarily be used directly,
+but rather through the logging macros defined.
 
-/**
- * Turns off logging to stdout globally
- *
- * Turns off the console unless the user has overridden the
- * runtime environment's logging spec, e.g. by setting
- * the RUST_LOG environment variable
- */
-pub fn console_off() {
-    // If RUST_LOG is set then the console can't be turned off
-    if os::getenv("RUST_LOG").is_some() {
-        return;
-    }
+There are five macros that the logging subsystem uses:
+
+* `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any
+                       related `format!` arguments
+* `debug!(...)` - a macro hard-wired to the log level of 4
+* `info!(...)` - a macro hard-wired to the log level of 3
+* `warn!(...)` - a macro hard-wired to the log level of 2
+* `error!(...)` - a macro hard-wired to the log level of 1
+
+All of these macros use the same style of syntax as the `format!` syntax
+extension. Details about the syntax can be found in the documentation of
+`std::fmt` along with the Rust tutorial/manual
+
+## Enabling logging
+
+Log levels are controlled on a per-module basis, and by default all logging is
+disabled except for `error!` (a log level of 1). Logging is controlled via the
+`RUST_LOG` environment variable. The value of this environment variable is a
+comma-separated list of logging directives. A logging directive is of the form:
+
+```
+path::to::module=log_level
+```
+
+The path to the module is rooted in the name of the crate it was compiled for,
+so if your program is contained in a file `hello.rs`, for example, to turn on
+logging for this file you would use a value of `RUST_LOG=hello`. Furthermore,
+this path is a prefix-search, so all modules nested in the specified module will
+also have logging enabled.
+
+The actual `log_level` is optional to specify. If omitted, all logging will be
+enabled. If specified, the it must be either a numeric in the range of 1-255, or
+it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric
+is specified, then all logging less than or equal to that numeral is enabled.
+For example, if logging level 3 is active, error, warn, and info logs will be
+printed, but debug will be omitted.
+
+As the log level for a module is optional, the module to enable logging for is
+also optional. If only a `log_level` is provided, then the global log level for
+all modules is set to this value.
 
-    rt::logging::console_off();
+Some examples of valid values of `RUST_LOG` are:
+
+```
+hello                // turns on all logging for the 'hello' module
+info                 // turns on all info logging
+hello=debug          // turns on debug logging for 'hello'
+hello=3              // turns on info logging for 'hello'
+hello,std::hashmap   // turns on hello, and std's hashmap logging
+error,hello=warn     // turn on global error logging and also warn for hello
+```
+
+## Performance and Side Effects
+
+Each of these macros will expand to code similar to:
+
+```rust
+if log_level <= my_module_log_level() {
+    ::std::logging::log(log_level, format!(...));
 }
+```
 
-#[allow(missing_doc)]
-pub fn log(_level: u32, args: &fmt::Arguments) {
-    use rt::task::Task;
-    use rt::local::Local;
+What this means is that each of these macros are very cheap at runtime if
+they're turned off (just a load and an integer comparison). This also means that
+if logging is disabled, none of the components of the log will be executed.
+
+## Useful Values
+
+For convenience, if a value of `::help` is set for `RUST_LOG`, a program will
+start, print out all modules registered for logging, and then exit.
 
+*/
+
+use fmt;
+use option::*;
+use rt::local::Local;
+use rt::logging::{Logger, StdErrLogger};
+use rt::task::Task;
+
+/// This function is called directly by the compiler when using the logging
+/// macros. This function does not take into account whether the log level
+/// specified is active or not, it will always log something if this method is
+/// called.
+///
+/// It is not recommended to call this function directly, rather it should be
+/// invoked through the logging family of macros.
+pub fn log(_level: u32, args: &fmt::Arguments) {
     unsafe {
         let optional_task: Option<*mut Task> = Local::try_unsafe_borrow();
         match optional_task {

branches/dist-snap/src/libstd/rt/logging.rs

@@ -10,7 +10,7 @@
 
 use fmt;
 use from_str::from_str;
-use libc::{uintptr_t, exit};
+use libc::exit;
 use option::{Some, None, Option};
 use rt;
 use rt::util::dumb_println;
@@ -182,9 +182,7 @@ pub struct StdErrLogger;
 
 impl Logger for StdErrLogger {
     fn log(&mut self, args: &fmt::Arguments) {
-        if should_log_console() {
-            fmt::writeln(self as &mut rt::io::Writer, args);
-        }
+        fmt::writeln(self as &mut rt::io::Writer, args);
     }
 }
 
@@ -220,21 +218,6 @@ pub fn init() {
     }
 }
 
-#[fixed_stack_segment] #[inline(never)]
-pub fn console_on() { unsafe { rust_log_console_on() } }
-
-#[fixed_stack_segment] #[inline(never)]
-pub fn console_off() { unsafe { rust_log_console_off() } }
-
-#[fixed_stack_segment] #[inline(never)]
-fn should_log_console() -> bool { unsafe { rust_should_log_console() != 0 } }
-
-extern {
-    fn rust_log_console_on();
-    fn rust_log_console_off();
-    fn rust_should_log_console() -> uintptr_t;
-}
-
 // Tests for parse_logging_spec()
 #[test]
 fn parse_logging_spec_valid() {

branches/dist-snap/src/rt/rust_builtin.cpp

@@ -326,27 +326,6 @@ rust_mktime(rust_tm* timeptr) {
     return mktime(&t);
 }
 
-static lock_and_signal log_lock;
-static bool log_to_console = true;
-
-extern "C" CDECL void
-rust_log_console_on() {
-    scoped_lock with(log_lock);
-    log_to_console = true;
-}
-
-extern "C" CDECL void
-rust_log_console_off() {
-    scoped_lock with(log_lock);
-    log_to_console = false;
-}
-
-extern "C" CDECL uintptr_t
-rust_should_log_console() {
-    scoped_lock with(log_lock);
-    return log_to_console;
-}
-
 extern "C" lock_and_signal*
 rust_create_little_lock() {
     return new lock_and_signal();

branches/dist-snap/src/rt/rustrt.def.in

@@ -18,9 +18,6 @@ rust_get_stderr
 rust_list_dir_val
 rust_list_dir_wfd_size
 rust_list_dir_wfd_fp_buf
-rust_log_console_on
-rust_log_console_off
-rust_should_log_console
 rust_unset_sigprocmask
 rust_env_pairs
 upcall_rust_personality