diff --git a/src/doc/reference.md b/src/doc/reference.md index 0a7de19a161..8c13b8212e4 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -4243,64 +4243,6 @@ In general, `--crate-type=bin` or `--crate-type=lib` should be sufficient for all compilation needs, and the other options are just available if more fine-grained control is desired over the output format of a Rust crate. -### Logging system - -The runtime contains a system for directing [logging -expressions](#logging-expressions) to a logging console and/or internal logging -buffers. Logging can be enabled per module. - -Logging output is enabled by setting the `RUST_LOG` environment variable. -`RUST_LOG` accepts a logging specification made up of a comma-separated list of -paths, with optional log levels. For each module containing log expressions, if -`RUST_LOG` contains the path to that module or a parent of that module, then -logs of the appropriate level will be output to the console. - -The path to a module consists of the crate name, any parent modules, then the -module itself, all separated by double colons (`::`). The optional log level -can be appended to the module path with an equals sign (`=`) followed by the -log level, from 1 to 4, inclusive. Level 1 is the error level, 2 is warning, 3 -info, and 4 debug. You can also use the symbolic constants `error`, `warn`, -`info`, and `debug`. Any logs less than or equal to the specified level will -be output. If not specified then log level 4 is assumed. Debug messages can be -omitted by passing `--cfg ndebug` to `rustc`. - -As an example, to see all the logs generated by the compiler, you would set -`RUST_LOG` to `rustc`, which is the crate name (as specified in its `crate_id` -[attribute](#attributes)). To narrow down the logs to just crate resolution, -you would set it to `rustc::metadata::creader`. To see just error logging use -`rustc=0`. - -Note that when compiling source files that don't specify a crate name the crate -is given a default name that matches the source file, with the extension -removed. In that case, to turn on logging for a program compiled from, e.g. -`helloworld.rs`, `RUST_LOG` should be set to `helloworld`. - -#### Logging Expressions - -Rust provides several macros to log information. Here's a simple Rust program -that demonstrates all four of them: - -``` -#![feature(phase)] -#[phase(plugin, link)] extern crate log; - -fn main() { - error!("This is an error log") - warn!("This is a warn log") - info!("this is an info log") - debug!("This is a debug log") -} -``` - -These four log levels correspond to levels 1-4, as controlled by `RUST_LOG`: - -```sh -$ RUST_LOG=rust=3 ./rust -This is an error log -This is a warn log -this is an info log -``` - # Appendix: Rationales and design tradeoffs *TODO*.