Skip to content

Commit

Permalink
logging is an external crate
Browse files Browse the repository at this point in the history
  • Loading branch information
steveklabnik committed Sep 22, 2014
1 parent 68b8901 commit 84bd6bb
Showing 1 changed file with 0 additions and 58 deletions.
58 changes: 0 additions & 58 deletions src/doc/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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*.
Expand Down

0 comments on commit 84bd6bb

Please sign in to comment.