Skip to content

Commit 193438c

Browse files
alexmohralexmohr
committed
docs: add README files for publishable crates
Add individual README files for dlt-sys, dlt-rs, and tracing-dlt crates to support publishing to crates.io. Each README provides crate-specific documentation, examples, and usage guidance. Individual READMEs make sure, that the published artifact on crates.io contains the correct documentation. Update root README to serve as workspace overview with table of crates and links to individual documentation. Signed-off-by: Alexander Mohr <[email protected]>
1 parent 01058b8 commit 193438c

File tree

5 files changed

+183
-63
lines changed

5 files changed

+183
-63
lines changed

‎.github/workflows/build.yml‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -58,13 +58,6 @@ jobs:
5858
with:
5959
submodules: false
6060
- uses: ./.github/actions/setup-dlt
61-
- name: Set up Docker Buildx
62-
uses: docker/setup-buildx-action@v3
63-
- name: Install Rust toolchain
64-
uses: dtolnay/rust-toolchain@master
65-
with:
66-
toolchain: 1.88.0
67-
components: clippy, rustfmt
6861
- name: Cache Rust dependencies
6962
uses: Swatinem/rust-cache@v2
7063
- name: Install cargo-deny

‎README.md‎

Lines changed: 16 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -18,70 +18,30 @@ Get it by running:
1818

1919
## Overview
2020

21-
This workspace contains three crates:
22-
- **`dlt-sys`** - Low-level Rust wrapper around the C libdlt library
23-
- **`dlt-rs`** - Safe Rust API for DLT logging. This crate depends on `dlt-sys`.
24-
- **`tracing-appender`** - Tracing subscriber/layer that integrates with the tracing framework. This crate depends on `dlt-rs`.
25-
- **`integration-tests`** - Common test utilities for integration testing with DLT daemon
26-
27-
## Features
28-
29-
- ✅ **Type-safe Rust API** for DLT logging
30-
- ✅ **Tracing integration** - Use standard `tracing` macros with DLT
31-
- ✅ **Structured logging** - Field types preserved when sent to DLT
32-
- ✅ **Span context** - Nested spans appear in log messages
33-
- ✅ **Dynamic log levels** - Responds to DLT daemon log level changes
34-
- ✅ **Thread-safe** - Safe for concurrent use across async tasks
35-
- ✅ **Zero-copy** where possible for performance
21+
This workspace contains three publishable crates:
3622

37-
## Quick Start
38-
39-
### Prerequisites
40-
41-
- Rust 1.88.0 or later
23+
| Crate | Description | Documentation |
24+
|-------|-------------|---------------|
25+
| **[`dlt-sys`](dlt-sys/)** | Low-level FFI bindings to libdlt | [README](dlt-sys/README.md) |
26+
| **[`dlt-rs`](dlt-rs/)** | Safe and idiomatic Rust API for DLT logging | [README](dlt-rs/README.md) |
27+
| **[`tracing-dlt`](tracing-dlt/)** | Tracing subscriber/layer for DLT integration | [README](tracing-dlt/README.md) |
4228

43-
### Basic Usage
44-
45-
#### DLT Sys
46-
```rust
47-
use dlt_sys::{DltApplication, DltId, DltLogLevel};
48-
fn main() -> Result<(), Box<dyn std::error::Error>> {
49-
// Register application (one per process)
50-
let app = DltApplication::register(&DltId::new(b"MBTI")?, "Measurement & Bus Trace Interface")?;
51-
let ctx = app.create_context(&DltId::new(b"MEAS")?, "Measurement Context")?;
52-
53-
// Simple logging
54-
ctx.log(DltLogLevel::Info, "Hello DLT!")?;
55-
56-
// Structured logging with typed fields
57-
let mut writer = ctx.log_write_start(DltLogLevel::Info)?;
58-
writer.write_string("Temperature:")?
59-
.write_float32(87.5)?
60-
.write_string("°C")?;
61-
writer.finish()?;
62-
Ok(())
63-
}
64-
```
29+
**Which crate should you use?**
30+
- Use `tracing-dlt` for integration with the `tracing` ecosystem (recommended)
31+
- Use `dlt-rs` for direct DLT logging with a safe API (non-tracing applications)
32+
- Use `dlt-sys` only if building your own low-level abstraction (not recommended for most users)
6533

66-
#### Dlt Tracing Appender
34+
See each crate's README for detailed examples and API documentation.
6735

68-
```rust
69-
use dlt_tracing_appender::{DltLayer, DltId};
70-
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
36+
> **Note:** `tracing-dlt` and `dlt-rs` can be used together when application registration is done through `tracing-dlt`.
7137
72-
#[tokio::main]
73-
async fn main() -> Result<(), Box<dyn std::error::Error>> {
74-
let dlt_layer = DltLayer::new(&DltId::new(b"MBTI"), "My Beautiful Trace Ingestor")?;
38+
## Quick Start
7539

76-
tracing_subscriber::registry().with(dlt_layer).init();
40+
### Prerequisites
7741

78-
tracing::info!("Application started");
79-
Ok(())
80-
}
81-
```
42+
- Rust 1.88.0 or later
43+
- **libdlt** must be installed on your system
8244

83-
For more examples and detailed usage, see the API documentation.
84-
The tracing and dlt-sys crates can be used simultaneously, when the application registration is done through the dlt-tracing-appender crate.
8545

8646
## Development
8747

‎dlt-rs/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# dlt-rs
2+
[![Crates.io](https://img.shields.io/crates/v/dlt-rs.svg)](https://crates.io/crates/dlt-rs)
3+
[![Documentation](https://docs.rs/dlt-rs/badge.svg)](https://docs.rs/dlt-rs)
4+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../LICENSE)
5+
Safe and idiomatic Rust wrapper for the COVESA DLT (Diagnostic Log and Trace) library.
6+
7+
## Overview
8+
`dlt-rs` provides a safe, ergonomic Rust API for logging to the [COVESA DLT daemon](https://github.com/COVESA/dlt-daemon). It wraps the low-level [`dlt-sys`](https://crates.io/crates/dlt-sys) FFI bindings with a type-safe interface.
9+
10+
## Features
11+
- ✅ **Type-safe API** - No unsafe code in your application
12+
- ✅ **Structured logging** - Log typed fields (integers, floats, strings, etc.)
13+
- ✅ **RAII-based resource management** - Automatic cleanup
14+
- ✅ **Thread-safe** - Safe for concurrent use
15+
- ✅ **Zero-copy** where possible for performance
16+
- ✅ **Dynamic log levels** - Responds to DLT daemon configuration changes
17+
18+
19+
## Basic Example
20+
```rust
21+
use dlt_rs::{DltApplication, DltId, DltLogLevel};
22+
fn main() -> Result<(), Box<dyn std::error::Error>> {
23+
// Register application (one per process)
24+
let app = DltApplication::register(
25+
&DltId::new(b"MBTI")?,
26+
"Measurement & Bus Trace Interface"
27+
)?;
28+
// Create a logging context
29+
let ctx = app.create_context(
30+
&DltId::new(b"CTX1")?,
31+
"Main Context"
32+
)?;
33+
// Simple text logging
34+
ctx.log(DltLogLevel::Info, "Hello DLT!")?;
35+
Ok(())
36+
}
37+
```
38+
39+
## Structured Logging
40+
```rust
41+
use dlt_rs::{DltLogLevel};
42+
// Log structured data with typed fields
43+
let mut writer = ctx.log_write_start(DltLogLevel::Info)?;
44+
writer
45+
.write_string("Temperature:")?
46+
.write_float32(87.5)?
47+
.write_string("°C")?;
48+
writer.finish()?;
49+
```
50+
51+
## Tracing Integration
52+
For integration with the `tracing` ecosystem, see the [`tracing-dlt`](https://crates.io/crates/tracing-dlt) crate.
53+
54+
## Features
55+
- `trace_load_ctrl` - Enable DLT load control support (optional)
56+
57+
## License
58+
Licensed under the Apache License, Version 2.0. See [LICENSE](../LICENSE) for details.
59+
60+
## Contributing
61+
This project is part of [Eclipse OpenSOVD](https://projects.eclipse.org/projects/automotive.opensovd), but can be used independently.
62+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
63+
64+
## References
65+
- [COVESA DLT Daemon](https://github.com/COVESA/dlt-daemon)
66+
- [DLT Protocol Specification](https://www.autosar.org/fileadmin/standards/foundation/19-11/AUTOSAR_PRS_LogAndTraceProtocol.pdf)

‎dlt-sys/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# dlt-sys
2+
[![Crates.io](https://img.shields.io/crates/v/dlt-sys.svg)](https://crates.io/crates/dlt-sys)
3+
[![Documentation](https://docs.rs/dlt-sys/badge.svg)](https://docs.rs/dlt-sys)
4+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../LICENSE)
5+
Low-level FFI bindings to the COVESA DLT (Diagnostic Log and Trace) C library (`libdlt`).
6+
7+
## Overview
8+
`dlt-sys` provides unsafe Rust bindings to the [COVESA DLT daemon](https://github.com/COVESA/dlt-daemon) C library.
9+
This crate is intended to be used as a foundation for higher-level safe Rust abstractions (see [`dlt-rs`](https://crates.io/crates/dlt-rs)).
10+
Please note that this is only implements functionality required for dlt-rs and does not cover the entire libdlt API.
11+
12+
## Features
13+
- Direct FFI bindings to `libdlt` functions
14+
- Custom C wrapper for improved API ergonomics
15+
- Support for all DLT log levels and message types
16+
- Optional `trace_load_ctrl` feature for load control support
17+
18+
## Prerequisites
19+
- **libdlt** and its development headers must be installed on your system.
20+
21+
## Usage
22+
This is a low-level crate with unsafe APIs. Most users should use [`dlt-rs`](https://crates.io/crates/dlt-rs) instead for a safe, idiomatic Rust API.
23+
24+
## Features
25+
- `trace_load_ctrl` - Enable DLT load control support (may be required in some environments, depending on the DLT build time daemon configuration)
26+
- `generate-bindings` - Regenerate bindings from C headers (development only)
27+
28+
## Safety
29+
All functions in this crate are `unsafe` as they directly call C library functions. Proper usage requires understanding of:
30+
- DLT library initialization and cleanup
31+
- Memory management across FFI boundaries
32+
- Thread safety considerations
33+
For safe abstractions, use the [`dlt-rs`](https://crates.io/crates/dlt-rs) crate.
34+
35+
## License
36+
Licensed under the Apache License, Version 2.0. See [LICENSE](../LICENSE) for details.
37+
## Contributing
38+
This project is part of [Eclipse OpenSOVD](https://projects.eclipse.org/projects/automotive.opensovd), but can be used independently.
39+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
40+
41+
## References
42+
- [COVESA DLT Daemon](https://github.com/COVESA/dlt-daemon)
43+
- [DLT Protocol Specification](https://www.autosar.org/fileadmin/standards/foundation/19-11/AUTOSAR_PRS_LogAndTraceProtocol.pdf)

‎tracing-dlt/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# tracing-dlt
2+
[![Crates.io](https://img.shields.io/crates/v/tracing-dlt.svg)](https://crates.io/crates/tracing-dlt)
3+
[![Documentation](https://docs.rs/tracing-dlt/badge.svg)](https://docs.rs/tracing-dlt)
4+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../LICENSE)
5+
A `tracing` subscriber/layer for sending structured logs and traces to the COVESA DLT daemon.
6+
7+
## Overview
8+
`tracing-dlt` provides a [tracing](https://github.com/tokio-rs/tracing) layer that forwards logs and spans to the [COVESA DLT daemon](https://github.com/COVESA/dlt-daemon). This allows you to use the standard `tracing` macros in your Rust application while outputting to DLT.
9+
10+
## Features
11+
- ✅ **Tracing integration** - Use standard `tracing::info!`, `tracing::debug!`, etc.
12+
- ✅ **Structured logging** - Field types are preserved when sent to DLT
13+
- ✅ **Span context** - Nested spans appear in log messages
14+
- ✅ **Dynamic log levels** - Responds to DLT daemon log level changes
15+
- ✅ **Thread-safe** - Safe for concurrent use across async tasks
16+
- ✅ **Multiple contexts** - Support for different logging contexts per span
17+
18+
> **Note:** The `tracing-dlt` and `dlt-rs` crates can be used simultaneously in the same application, as long as application registration is done through `tracing-dlt`.
19+
20+
## Basic Example
21+
```rust
22+
use tracing_dlt::{DltLayer, DltId};
23+
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
24+
fn main() -> Result<(), Box<dyn std::error::Error>> {
25+
// Initialize DLT layer
26+
let dlt_layer = DltLayer::new(
27+
&DltId::new(b"MBTI")?,
28+
"My Beautiful Trace Ingestor"
29+
)?;
30+
// Set up tracing subscriber
31+
tracing_subscriber::registry()
32+
.with(dlt_layer)
33+
.init();
34+
35+
// Use standard tracing macros
36+
tracing::info!("Application started");
37+
tracing::warn!(temperature = 95.5, "High temperature detected");
38+
// Will be logged with context ID "SPCL"
39+
tracing::warn!(dlt_context = "SPCL", "Log message on 'special' context id");
40+
Ok(())
41+
}
42+
```
43+
44+
## Features
45+
- `trace_load_ctrl` - Enable DLT load control support (optional)
46+
- `dlt_layer_internal_logging` - Enable debug logging for the layer itself
47+
48+
## License
49+
Licensed under the Apache License, Version 2.0. See [LICENSE](../LICENSE) for details.
50+
51+
## Contributing
52+
This project is part of [Eclipse OpenSOVD](https://projects.eclipse.org/projects/automotive.opensovd), but can be used independently.
53+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
54+
55+
## References
56+
- [Tracing Framework](https://github.com/tokio-rs/tracing)
57+
- [COVESA DLT Daemon](https://github.com/COVESA/dlt-daemon)
58+
- [DLT Protocol Specification](https://www.autosar.org/fileadmin/standards/foundation/19-11/AUTOSAR_PRS_LogAndTraceProtocol.pdf)

0 commit comments

Comments
 (0)