Skip to content

Commit 2d0c5d7

Browse files
benodiwalbenodiwal
authored
docs: made feature flag guide more comprehensive (#678)
1 parent 5f08820 commit 2d0c5d7

2 files changed

Lines changed: 123 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 63 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,69 @@ bollard = "*"
3232

3333
### Feature flags
3434

35-
- `ssl`: enable SSL support through [Rustls](https://github.com/rustls/rustls) with the [ring](https://github.com/briansmith/ring) provider.
36-
- `aws-lc-rs`: enable SSL support through [Rustls](https://github.com/rustls/rustls) with the [aws-lc-rs](https://github.com/aws/aws-lc-rs) provider.
37-
- `ssl_providerless`: enable SSL support through [Rustls](https://github.com/rustls/rustls) without installing a [CryptoProvider](https://docs.rs/rustls/0.23.12/rustls/crypto/struct.CryptoProvider.html). You are responsible to do so.
38-
- `chrono`: enable [Chrono](https://github.com/chronotope/chrono) for `DateTime` types.
39-
- `time`: enable [Time 0.3](https://github.com/time-rs/time) for `DateTime` types.
40-
- `buildkit`: use [Buildkit](https://github.com/moby/buildkit) instead of [Docker](https://github.com/moby/moby) when building images.
41-
- `buildkit_providerless`: enable [Buildkit](https://github.com/moby/buildkit) support without installing a [CryptoProvider](https://docs.rs/rustls/0.23.12/rustls/crypto/struct.CryptoProvider.html).
42-
- `json_data_content`: Add JSON to errors on serialization failures.
43-
- `webpki`: Use mozilla's root certificates instead of native root certs provided by the OS.
35+
#### Quick Start
36+
37+
| Use Case | Cargo.toml |
38+
|----------|------------|
39+
| Local Docker (Unix/Windows) | `bollard = "*"` _(defaults work)_ |
40+
| Remote Docker over HTTPS | `bollard = { version = "*", features = ["ssl"] }` |
41+
| SSH tunnel to remote Docker | `bollard = { version = "*", features = ["ssh"] }` |
42+
| BuildKit image builds | `bollard = { version = "*", features = ["buildkit", "chrono"] }` |
43+
| Minimal binary size | `bollard = { version = "*", default-features = false, features = ["pipe"] }` |
44+
45+
#### Default Features
46+
47+
Enabled by default:
48+
- `http` - TCP connections to remote Docker (`DOCKER_HOST=tcp://...`)
49+
- `pipe` - Unix sockets (`/var/run/docker.sock`) and Windows named pipes
50+
51+
#### Transport Features
52+
53+
| Feature | Description |
54+
|---------|-------------|
55+
| `http` | HTTP/TCP connector for remote Docker |
56+
| `pipe` | Unix socket / Windows named pipe for local Docker |
57+
| `ssh` | SSH tunnel connector (requires `ssh` feature) |
58+
59+
#### TLS/SSL Features
60+
61+
Choose **one** crypto provider:
62+
63+
| Feature | Description |
64+
|---------|-------------|
65+
| `ssl` | [Rustls](https://github.com/rustls/rustls) with [ring](https://github.com/briansmith/ring) provider (recommended) |
66+
| `aws-lc-rs` | [Rustls](https://github.com/rustls/rustls) with [aws-lc-rs](https://github.com/aws/aws-lc-rs) provider (FIPS-compliant) |
67+
| `ssl_providerless` | [Rustls](https://github.com/rustls/rustls) without crypto provider (bring your own [CryptoProvider](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html)) |
68+
| `webpki` | Use Mozilla's root certificates instead of OS native certs |
69+
70+
#### DateTime Features
71+
72+
For timestamp support in events and logs, choose **one**:
73+
74+
| Feature | Description |
75+
|---------|-------------|
76+
| `chrono` | [Chrono](https://github.com/chronotope/chrono) date/time types |
77+
| `time` | [Time 0.3](https://github.com/time-rs/time) date/time types |
78+
79+
**Note:** `chrono` and `time` are mutually exclusive.
80+
81+
#### BuildKit Features
82+
83+
| Feature | Description |
84+
|---------|-------------|
85+
| `buildkit` | Full [BuildKit](https://github.com/moby/buildkit) support (includes `ssl`) |
86+
| `buildkit_providerless` | BuildKit without bundled crypto provider |
87+
88+
**Note:** BuildKit requires either `chrono` or `time` feature to be enabled for timestamp handling. Example:
89+
```toml
90+
bollard = { version = "*", features = ["buildkit", "chrono"] }
91+
```
92+
93+
#### Development Features
94+
95+
| Feature | Description |
96+
|---------|-------------|
97+
| `json_data_content` | Include raw JSON payload in deserialization errors |
4498

4599
### Version
46100

‎src/lib.rs‎

Lines changed: 60 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,66 @@
3232
//!
3333
//! ## Feature flags
3434
//!
35-
//! - `ssl`: enable SSL support through [Rustls](https://github.com/rustls/rustls) with the [ring](https://github.com/briansmith/ring) provider.
36-
//! - `aws-lc-rs`: enable SSL support through [Rustls](https://github.com/rustls/rustls) with the [aws-lc-rs](https://github.com/aws/aws-lc-rs) provider.
37-
//! - `ssl_providerless`: enable SSL support through [Rustls](https://github.com/rustls/rustls) without installing a [CryptoProvider](https://docs.rs/rustls/0.23.12/rustls/crypto/struct.CryptoProvider.html). You are responsible to do so.
38-
//! - `chrono`: enable [Chrono](https://github.com/chronotope/chrono) for `DateTime` types.
39-
//! - `time`: enable [Time 0.3](https://github.com/time-rs/time) for `DateTime` types.
40-
//! - `buildkit`: use [Buildkit](https://github.com/moby/buildkit) instead of [Docker](https://github.com/moby/moby) when building images.
41-
//! - `buildkit_providerless`: enable [Buildkit](https://github.com/moby/buildkit) support without installing a [CryptoProvider](https://docs.rs/rustls/0.23.12/rustls/crypto/struct.CryptoProvider.html).
42-
//! - `json_data_content`: Add JSON to errors on serialization failures.
43-
//! - `webpki`: Use mozilla's root certificates instead of native root certs provided by the OS.
35+
//! ### Quick Start
36+
//!
37+
//! | Use Case | Cargo.toml |
38+
//! |----------|------------|
39+
//! | Local Docker (Unix/Windows) | `bollard = "*"` _(defaults work)_ |
40+
//! | Remote Docker over HTTPS | `bollard = { version = "*", features = ["ssl"] }` |
41+
//! | SSH tunnel to remote Docker | `bollard = { version = "*", features = ["ssh"] }` |
42+
//! | BuildKit image builds | `bollard = { version = "*", features = ["buildkit", "chrono"] }` |
43+
//! | Minimal binary size | `bollard = { version = "*", default-features = false, features = ["pipe"] }` |
44+
//!
45+
//! ### Default Features
46+
//!
47+
//! Enabled by default:
48+
//! - `http` - TCP connections to remote Docker (`DOCKER_HOST=tcp://...`)
49+
//! - `pipe` - Unix sockets (`/var/run/docker.sock`) and Windows named pipes
50+
//!
51+
//! ### Transport Features
52+
//!
53+
//! | Feature | Description |
54+
//! |---------|-------------|
55+
//! | `http` | HTTP/TCP connector for remote Docker |
56+
//! | `pipe` | Unix socket / Windows named pipe for local Docker |
57+
//! | `ssh` | SSH tunnel connector |
58+
//!
59+
//! ### TLS/SSL Features
60+
//!
61+
//! Choose **one** crypto provider:
62+
//!
63+
//! | Feature | Description |
64+
//! |---------|-------------|
65+
//! | `ssl` | [Rustls](https://github.com/rustls/rustls) with [ring](https://github.com/briansmith/ring) provider (recommended) |
66+
//! | `aws-lc-rs` | [Rustls](https://github.com/rustls/rustls) with [aws-lc-rs](https://github.com/aws/aws-lc-rs) provider (FIPS-compliant) |
67+
//! | `ssl_providerless` | [Rustls](https://github.com/rustls/rustls) without crypto provider (bring your own [`CryptoProvider`](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html)) |
68+
//! | `webpki` | Use Mozilla's root certificates instead of OS native certs |
69+
//!
70+
//! ### DateTime Features
71+
//!
72+
//! For timestamp support in events and logs, choose **one**:
73+
//!
74+
//! | Feature | Description |
75+
//! |---------|-------------|
76+
//! | `chrono` | [Chrono](https://github.com/chronotope/chrono) date/time types |
77+
//! | `time` | [Time 0.3](https://github.com/time-rs/time) date/time types |
78+
//!
79+
//! **Note:** `chrono` and `time` are mutually exclusive.
80+
//!
81+
//! ### BuildKit Features
82+
//!
83+
//! | Feature | Description |
84+
//! |---------|-------------|
85+
//! | `buildkit` | Full [BuildKit](https://github.com/moby/buildkit) support (includes `ssl`) |
86+
//! | `buildkit_providerless` | BuildKit without bundled crypto provider |
87+
//!
88+
//! **Note:** BuildKit requires either `chrono` or `time` feature to be enabled for timestamp handling.
89+
//!
90+
//! ### Development Features
91+
//!
92+
//! | Feature | Description |
93+
//! |---------|-------------|
94+
//! | `json_data_content` | Include raw JSON payload in deserialization errors |
4495
//!
4596
//! ## Version
4697
//!

0 commit comments

Comments
 (0)