From 7bd88ebd3a51789e7a2cab9ace7530f3a3dc3193 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Sat, 7 Oct 2017 13:46:46 -0700 Subject: [PATCH 1/2] Remove env_logger stuff from README --- README.md | 131 ------------------------------------------------------ 1 file changed, 131 deletions(-) diff --git a/README.md b/README.md index 6efed34..68995ae 100644 --- a/README.md +++ b/README.md @@ -72,134 +72,3 @@ function to do this. Any log messages generated before the logger is initialized will be ignored. The executable itself may use the `log` crate to log as well. - -The `env_logger` crate provides a logger implementation that mirrors the -functionality of the old revision of the `log` crate. - -```toml -[dependencies] -log = "0.3" -env_logger = "0.3" -``` - -```rust -#[macro_use] -extern crate log; -extern crate env_logger; - -fn main() { - env_logger::init(); - - info!("starting up"); - - // ... -} -``` - -Then when running the executable, specify a value for the `RUST_LOG` -environment variable that corresponds with the log messages you want to show. - -```bash -$ RUST_LOG=info ./main -starting up -``` - -See the [`env_logger` documentation](https://docs.rs/env_logger) -for the `RUST_LOG` values that can be used to get log messages with different -levels or filtered to different modules. - -## In tests - -Tests can use the `env_logger` crate to see log messages generated during that test: - -```toml -[dependencies] -log = "0.3" - -[dev-dependencies] -env_logger = "0.3" -``` - -```rust -#[macro_use] -extern crate log; - -fn add_one(num: i32) -> i32 { - info!("add_one called with {}", num); - num + 1 -} - -#[cfg(test)] -mod tests { - use super::*; - extern crate env_logger; - - #[test] - fn it_adds_one() { - let _ = env_logger::init(); - info!("can log from the test too"); - assert_eq!(3, add_one(2)); - } - - #[test] - fn it_handles_negative_numbers() { - let _ = env_logger::init(); - info!("logging from another test"); - assert_eq!(-7, add_one(-8)); - } -} -``` - -Assuming the module under test is called `my_lib`, running the tests with the -`RUST_LOG` filtering to info messages from this module looks like: - -```bash -$ RUST_LOG=my_lib=info cargo test - Running target/debug/my_lib-... - -running 2 tests -INFO:my_lib::tests: logging from another test -INFO:my_lib: add_one called with -8 -test tests::it_handles_negative_numbers ... ok -INFO:my_lib::tests: can log from the test too -INFO:my_lib: add_one called with 2 -test tests::it_adds_one ... ok - -test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured -``` - -Note that `env_logger::init()` needs to be called in each test in which you -want to enable logging. Additionally, the default behavior of tests to -run in parallel means that logging output may be interleaved with test output. -Either run tests in a single thread by specifying `RUST_TEST_THREADS=1` or by -running one test by specifying its name as an argument to the test binaries as -directed by the `cargo test` help docs: - -```bash -$ RUST_LOG=my_lib=info cargo test it_adds_one - Running target/debug/my_lib-... - -running 1 test -INFO:my_lib::tests: can log from the test too -INFO:my_lib: add_one called with 2 -test tests::it_adds_one ... ok - -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured -``` - -## Configuring log target - -By default, `env_logger` logs to stderr. If you want to log to stdout instead, -you can use the `Builder` to change the log target: - -```rust -use std::env; -use env_logger::{Builder, Target}; - -let mut builder = Builder::new(); -builder.target(Target::Stdout); -if env::var("RUST_LOG").is_ok() { - builder.parse(&env::var("RUST_LOG").unwrap()); -} -builder.init(); -``` From 213b85dab2cdb5e12b673a0a599a740b6e4f87b5 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Sat, 7 Oct 2017 14:44:00 -0700 Subject: [PATCH 2/2] Add a note about version compatibility --- src/lib.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index d3bc80a..15175eb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -211,6 +211,13 @@ //! features = ["max_level_debug", "release_max_level_warn"] //! ``` //! +//! # Version Compatibility +//! +//! The 0.3 and 0.4 versions of the `log` crate are almost entirely compatible. Log messages +//! made using `log` 0.3 will forward transparently to a logger implementation using `log` 0.4. Log +//! messages made using `log` 0.4 will forward to a logger implementation using `log` 0.3, but the +//! module path and file name information associated with the message will unfortunately be lost. +//! //! [`Log`]: trait.Log.html //! [level_link]: enum.Level.html //! [`set_logger`]: fn.set_logger.html