chore: restructure repo layout

.cargo/config.toml

@@ -0,0 +1,19 @@
+# Copyright 2024 FastLabs Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[alias]
+x = "run --package x --"
+
+[env]
+CARGO_WORKSPACE_DIR = { value = "", relative = true }

.github/workflows/ci.yml

@@ -47,13 +47,7 @@ jobs:
       - uses: taiki-e/install-action@v2
         with:
           tool: typos-cli,taplo-cli,hawkeye
-      - name: Check all
-        run: |
-          hawkeye check
-          taplo format --check
-          typos
-          cargo +nightly fmt --all -- --check
-          cargo +nightly clippy --all-targets --all-features -- -D warnings
+      - run: cargo x lint
 
   msrv:
     name: Resolve MSRV
@@ -89,10 +83,9 @@ jobs:
         run: cargo build --workspace --all-features --bins --tests --examples --benches --lib
       - name: Run unit tests
         shell: bash
-        run: cargo test --all-features -- --nocapture
+        run: cargo x test --no-capture
       - name: Run examples
         shell: bash
-        working-directory: logforth
         run: |
           set -x
           cargo run --features="bridge-log" --example simple_stdout

Cargo.toml

@@ -15,11 +15,13 @@
 [workspace]
 members = [
   "core",
+  "examples",
   "logforth",
   "appenders/*",
   "bridges/*",
   "diagnostics/*",
   "layouts/*",
+  "xtask",
 ]
 resolver = "2"
 
@@ -34,6 +36,7 @@ rust-version = "1.85.0"
 
 [workspace.dependencies]
 # Workspace dependencies
+logforth = { version = "0.29.1", path = "logforth" }
 logforth-append-async = { version = "0.3.0", path = "appenders/async" }
 logforth-append-fastrace = { version = "0.3.0", path = "appenders/fastrace" }
 logforth-append-file = { version = "0.3.0", path = "appenders/file" }
@@ -52,6 +55,7 @@ logforth-layout-text = { version = "0.3.0", path = "layouts/text" }
 # Crates.io dependencies
 anyhow = { version = "1.0" }
 arc-swap = { version = "1.7.1" }
+clap = { version = "4.5.49", features = ["derive"] }
 colored = { version = "3.0" }
 crossbeam-channel = { version = "0.5.15" }
 fastrace = { version = "0.7" }
@@ -71,9 +75,9 @@ serde_json = { version = "1.0" }
 tempfile = { version = "3.16" }
 tokio = { version = "1.47.1" }
 value-bag = { version = "1.11.1", features = ["inline-i128", "owned", "sval"] }
+which = { version = "8.0.0" }
 
 [workspace.lints.rust]
-missing_docs = "deny"
 unknown_lints = "deny"
 unused_must_use = "deny"
 

README.md

@@ -99,7 +99,7 @@ fn main() {
 }
 ```
 
-Read more demos under the [examples](logforth/examples) directory.
+Read more demos under the [examples](examples) directory.
 
 ## Features
 

appenders/async/README.md

@@ -3,3 +3,4 @@
 This appender is a remix of [spdlog-rs's AsyncPoolSink](https://docs.rs/spdlog-rs/*/spdlog/sink/struct.AsyncPoolSink.html), with several modifications to fit this crate's need:
 
 * Instead of a thread pool, it uses a single background thread to drain the log queue.
+* `flush` will block until all pending log messages are processed. This avoids the need of `Append::exit` we once added.

appenders/async/src/append.rs

@@ -27,6 +27,28 @@ use crate::state::AsyncState;
 use crate::worker::Worker;
 
 /// A composable appender, logging and flushing asynchronously.
+///
+/// # Examples
+///
+/// ```
+/// use logforth_append_async::AsyncBuilder;
+/// use logforth_core::append::Stderr;
+///
+/// let async_append = AsyncBuilder::new("logforth-async-append")
+///     .overflow_drop_incoming()
+///     // for demonstration purposes; in practice, this can be a file appender, etc.
+///     .append(Stderr::default())
+///     .build();
+/// ```
+///
+/// # Caveats
+///
+/// The caller or application should ensure that the `flush` method is called before the program
+/// exits to write out any buffered events, especially when this appender is used in a global
+/// context.
+///
+/// The drop glue will also flush the appender. But, in Rust, static items do not call `drop`
+/// at the end of the program.
 #[derive(Debug)]
 pub struct Async {
     state: AsyncState,

appenders/async/src/lib.rs

@@ -15,6 +15,7 @@
 //! A composable appender, logging and flushing asynchronously.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use logforth_core::Error;
 use logforth_core::kv;

appenders/async/tests/flushes.rs

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Tests for asynchronous appenders wait on flushes.
-
 use std::sync::Arc;
 use std::sync::Barrier;
 use std::sync::atomic::AtomicBool;

appenders/fastrace/src/lib.rs

@@ -15,6 +15,7 @@
 //! Appender for integrating with [fastrace](https://crates.io/crates/fastrace).
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use std::borrow::Cow;
 
@@ -42,10 +43,6 @@ use logforth_core::record::Record;
 /// The caller or application should ensure that the `flush` method or [`fastrace::flush`] is called
 /// before the program exits to collect the final events, especially when this appender is used
 /// in a global context.
-///
-/// Both the `exit` method and the drop glue do not call `fastrace::flush`, because it uses
-/// thread-local storage internally, which is not supported in `atexit` callbacks or arbitrary
-/// drop cases.
 #[derive(Default, Debug, Clone)]
 #[non_exhaustive]
 pub struct FastraceEvent {}

appenders/file/src/append.rs

@@ -31,6 +31,8 @@ use crate::rolling::RollingFileWriterBuilder;
 use crate::rotation::Rotation;
 
 /// A builder to configure and create an [`File`] appender.
+///
+/// See [module-level documentation](super) for usage examples.
 #[derive(Debug)]
 pub struct FileBuilder {
     builder: RollingFileWriterBuilder,

appenders/file/src/lib.rs

@@ -38,6 +38,7 @@
 //! ```
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 pub use self::append::File;
 pub use self::append::FileBuilder;

appenders/file/tests/global_file_limit.rs

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Ensure max_log_files limits the total number of log files across multiple date patterns.
-
 use std::fs;
 use std::num::NonZeroUsize;
 use std::path::Path;

appenders/journald/src/lib.rs

@@ -16,6 +16,7 @@
 
 #![cfg(unix)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use std::io::Write;
 use std::os::unix::net::UnixDatagram;

appenders/opentelemetry/src/lib.rs

@@ -15,6 +15,7 @@
 //! Appenders and utilities for integrating with OpenTelemetry.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use std::borrow::Cow;
 use std::fmt;

appenders/syslog/src/lib.rs

@@ -31,6 +31,7 @@
 //! ```
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use std::io;
 use std::sync::Mutex;
@@ -273,6 +274,8 @@ mod unix_ext {
 }
 
 /// An appender that writes log records to syslog.
+///
+/// See [module-level documentation](self) for usage examples.
 #[derive(Debug)]
 pub struct Syslog {
     sender: Mutex<SyslogSender>,

bridges/log/src/lib.rs

@@ -15,6 +15,7 @@
 //! A bridge to forward logs from the `log` crate to `logforth`.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use log::Metadata;
 use log::Record;

core/src/lib.rs

@@ -15,6 +15,7 @@
 //! Core structs and functions for the logforth logging framework.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 pub mod append;
 pub mod diagnostic;

diagnostics/fastrace/src/lib.rs

@@ -15,6 +15,7 @@
 //! A diagnostic that enriches log records with trace context provided by the Fastrace library.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
 
 use fastrace::collector::SpanContext;
 use logforth_core::Diagnostic;
@@ -25,16 +26,6 @@ use logforth_core::kv::Visitor;
 
 /// A diagnostic that enriches log records with trace context provided by the Fastrace library.
 ///
-/// Output format:
-///
-/// ```text
-/// 2025-01-10T15:22:37.868815+08:00 ERROR fastrace: fastrace.rs:39 Hello syslog error! trace_id=37f9c45f918cbb477089afb0d7162e7e
-/// 2025-01-10T15:22:37.868890+08:00  WARN fastrace: fastrace.rs:40 Hello syslog warn! trace_id=37f9c45f918cbb477089afb0d7162e7e
-/// 2025-01-10T15:22:37.868921+08:00  INFO fastrace: fastrace.rs:41 Hello syslog info! trace_id=37f9c45f918cbb477089afb0d7162e7e
-/// 2025-01-10T15:22:37.868949+08:00 DEBUG fastrace: fastrace.rs:42 Hello syslog debug! trace_id=37f9c45f918cbb477089afb0d7162e7e
-/// 2025-01-10T15:22:37.868976+08:00 TRACE fastrace: fastrace.rs:43 Hello syslog trace! trace_id=37f9c45f918cbb477089afb0d7162e7e
-/// ```
-///
 /// ## Example
 ///
 /// ```