114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# okstd
|
|
|
|
<img src="okstd.png" align="right" width="200">
|
|
|
|
Standards that are OK.
|
|
|
|
## Motivation
|
|
|
|
Rust's ecosystem is known for its vibrant community and wealth of high-quality crates. However, this abundance has led to some fragmentation, especially when it comes to foundational aspects like asynchronous programming, I/O, and logging. Developers are often faced with choosing between multiple ways of handling async code (e.g., async-std, tokio, smol, surf), several approaches to async I/O, and numerous logging frameworks (e.g., log, env_logger, pretty_env_logger, femme, flexi_logger). While having options is valuable, it can also lead to decision paralysis and make it harder to build an ecosystem of interoperable libraries and frameworks.
|
|
|
|
This is the crate when we reach for when we need such primitives, essentially the "Battery Included" crate.
|
|
|
|
## Getting Started
|
|
|
|
```bash
|
|
cargo add okstd@0.1.0
|
|
```
|
|
|
|
```rust
|
|
use okstd::prelude::*;
|
|
```
|
|
|
|
## Examples
|
|
|
|
### `okstd::main`
|
|
|
|
```rust
|
|
#[okstd::main]
|
|
async fn main() {
|
|
something();
|
|
}
|
|
```
|
|
|
|
### `okstd::log`
|
|
|
|
```rust
|
|
#[okstd::log(debug)]
|
|
fn something() {
|
|
debug!("Hello, world!");
|
|
println!("Hello, world!");
|
|
}
|
|
```
|
|
|
|
### `okstd::test`
|
|
|
|
take a function and if it's not async, just add the #[test] attribute
|
|
if it's async, add the #[test] attribute and setup the runtime
|
|
take the previous function body then pass it into block_on as a closure
|
|
|
|
```rust
|
|
#[okstd::test]
|
|
fn does_something() {
|
|
// do something
|
|
}
|
|
```
|
|
|
|
to
|
|
|
|
```rust
|
|
#[test]
|
|
fn does_something() {
|
|
// do something
|
|
}
|
|
```
|
|
|
|
or
|
|
|
|
```rust
|
|
#[okstd::test]
|
|
async fn does_something() {
|
|
// do something
|
|
}
|
|
```
|
|
|
|
to
|
|
|
|
```rust
|
|
#[test]
|
|
fn does_something() {
|
|
Runtimes::setup_runtimes().unwrap().block_on(async {
|
|
// do something
|
|
});
|
|
}
|
|
```
|
|
|
|
## Experimental Features
|
|
|
|
> [!CAUTION]
|
|
> Very unstable and only available under `unstable` feature flag.
|
|
|
|
### `okstd::crashdump`
|
|
|
|
```rust
|
|
#[okstd::log(info)]
|
|
#[okstd::crashdump]
|
|
#[okstd::main]
|
|
async fn main() {
|
|
let a = 0;
|
|
let b = 1;
|
|
let c = b / a;
|
|
panic!("This is a panic");
|
|
}
|
|
```
|
|
|
|
will return a crashdump string like so
|
|
|
|
```text
|
|
SourceMap { file: Some("integration/src/panics.rs"), tokens: [], index: [], names: ["backtrace::backtrace::trace_unsynchronized", "backtrace::backtrace::trace", "okstd::notokpanic::panic_hook", "core::ops::function::Fn::call", "<alloc::boxed::Box<F,A> as core::ops::function::Fn<Args>>::call", "std::panicking::rust_panic_with_hook", "std::panicking::begin_panic_handler::{{closure}}", "std::sys_common::backtrace::__rust_end_short_backtrace", "rust_begin_unwind", "core::panicking::panic_fmt", "core::panicking::panic", "panics::old_main::{{closure}}", "tokio::runtime::park::CachedParkThread::block_on::{{closure}}", "tokio::runtime::park::CachedParkThread::block_on", "tokio::runtime::context::blocking::BlockingRegionGuard::block_on", "tokio::runtime::scheduler::multi_thread::MultiThread::block_on::{{closure}}", "tokio::runtime::context::runtime::enter_runtime", "tokio::runtime::scheduler::multi_thread::MultiThread::block_on", "tokio::runtime::runtime::Runtime::block_on", "<okstd::okasync::Runtimes as okstd::okasync::Runtime>::block_on", "panics::main", "core::ops::function::FnOnce::call_once", "std::sys_common::backtrace::__rust_begin_short_backtrace", "std::rt::lang_start::{{closure}}", "std::panicking::try::do_call", "std::panicking::try", "std::panic::catch_unwind", "std::rt::lang_start_internal::{{closure}}", "std::rt::lang_start_internal", "std::rt::lang_start", "main", "_start"], source_root: None, sources: [], sources_prefixed: None, sources_content: [], debug_id: None }
|
|
Filename: Ok("/scratch/cargo_target/debug/panics")
|
|
Crashdump URL: https://crashdu.mp/🐧/♔/aea3ab2067116e3327bb51dc3bed94cd0/g98qBgj9qBg80qBg7r2Ng7gmOg4nxOgrnxOgt9wOgnmxOg4gpBghhpBggnpBg2spBg7npBg9lpBgp9pBgjsqBgk9pBgwqqBgl+pBgxmpBg/upOg4mqBg4kqBg500Cgnl6Kg6yuDgilvOg500Cgnl6Kg6yuDgohvOgzkqBg9mpBgslpB?cGFuaWMgb2NjdXJyZWQ6IGF0dGVtcHQgdG8gZGl2aWRlIGJ5IHplcm8gYXQgaW50ZWdyYXRpb24vc3JjL3Bhbmljcy5yczoxMToxMw
|
|
```
|
|
|
|
[crashdu.mp/🐧/♔/aea3ab2067116e3327bb51dc3bed94cd0/g98qBgj9qBg80qBg7r2Ng7gmOg4nxOgrnxOgt9wOgnmxOg4gpBghhpBggnpBg2spBg7npBg9lpBgp9pBgjsqBgk9pBgwqqBgl+pBgxmpBg/upOg4mqBg4kqBg500Cgnl6Kg6yuDgilvOg500Cgnl6Kg6yuDgohvOgzkqBg9mpBgslpB?cGFuaWMgb2NjdXJyZWQ6IGF0dGVtcHQgdG8gZGl2aWRlIGJ5IHplcm8gYXQgaW50ZWdyYXRpb24vc3JjL3Bhbmljcy5yczoxMToxMw](https://crashdu.mp/🐧/♔/aea3ab2067116e3327bb51dc3bed94cd0/g98qBgj9qBg80qBg7r2Ng7gmOg4nxOgrnxOgt9wOgnmxOg4gpBghhpBggnpBg2spBg7npBg9lpBgp9pBgjsqBgk9pBgwqqBgl+pBgxmpBg/upOg4mqBg4kqBg500Cgnl6Kg6yuDgilvOg500Cgnl6Kg6yuDgohvOgzkqBg9mpBgslpB?cGFuaWMgb2NjdXJyZWQ6IGF0dGVtcHQgdG8gZGl2aWRlIGJ5IHplcm8gYXQgaW50ZWdyYXRpb24vc3JjL3Bhbmljcy5yczoxMToxMw)
|