gix-features 0.38.2

A crate to integrate various capabilities using compile-time feature flags
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

[package]
name = "gix-features"
description = "A crate to integrate various capabilities using compile-time feature flags"
repository = "https://github.com/Byron/gitoxide"
version = "0.38.2"
authors = ["Sebastian Thiel <sebastian.thiel@icloud.com>"]
license = "MIT OR Apache-2.0"
edition = "2021"
rust-version = "1.65"
include = ["src/**/*", "LICENSE-*"]

[lib]
doctest = false
test = false

[features]

default = []
## Provide traits and utilities for providing progress information. These can then be rendered
## using facilities of the `prodash` crate.
progress = ["prodash"]
## Provide human-readable numbers as well as easier to read byte units for progress bars.
progress-unit-human-numbers = ["prodash?/unit-human"]
## Provide human readable byte units for progress bars.
progress-unit-bytes = ["dep:bytesize", "prodash?/unit-bytes"]

## If set, walkdir iterators will be multi-threaded.
fs-walkdir-parallel = ["dep:jwalk", "dep:gix-utils"]

## Provide utilities suitable for working with the `std::fs::read_dir()`.
fs-read-dir = ["dep:gix-utils"]

## Implement `tracing` with `tracing-core`, which provides applications with valuable performance details if they opt-in to it.
##
## Note that this may have overhead as well, thus instrumentations should be used stategically, only providing coarse tracing by default and adding details
## only where needed while marking them with the appropriate level.
tracing = ["gix-trace/tracing"]

## If enabled, detailed tracing is also emitted, which can greatly increase insights but at a cost.
tracing-detail = ["gix-trace/tracing-detail"]

## Use scoped threads and channels to parallelize common workloads on multiple objects. If enabled, it is used everywhere
## where it makes sense.
## As caches are likely to be used and instantiated per thread, more memory will be used on top of the costs for threads.
## The `threading` module will contain thread-safe primitives for shared ownership and mutation, otherwise these will be their single threaded counterparts.
## This way, single-threaded applications don't have to pay for threaded primitives.
parallel = ["dep:crossbeam-channel",
    "dep:parking_lot"]
## If enabled, OnceCell will be made available for interior mutability either in sync or unsync forms.
once_cell = ["dep:once_cell"]
## Makes facilities of the `walkdir` crate partially available.
## In conjunction with the **parallel** feature, directory walking will be parallel instead behind a compatible interface.
walkdir = ["dep:walkdir", "dep:gix-utils"]
#* an in-memory unidirectional pipe using `bytes` as efficient transfer mechanism.
io-pipe = ["dep:bytes"]
## provide a proven and fast `crc32` implementation.
crc32 = ["dep:crc32fast"]

#! ### Mutually Exclusive ZLIB

## Enable the usage of zlib related utilities to compress or decompress data.
## The base `zlib` feature uses the `flate2` Rust crate; the other mutually exclusive features select the `flate2 backend.
## Note that a competitive Zlib implementation is critical to `gitoxide's` object database performance.
## Enabling this without enabling one of the other features below will use a low-performance pure-Rust backend.
zlib = ["dep:flate2", "flate2?/rust_backend", "dep:thiserror"]
## Use the C-based zlib-ng backend, which can compress and decompress significantly faster.
zlib-ng = ["zlib", "flate2?/zlib-ng"]
## Use zlib-ng via its zlib-compat API. Useful if you already need zlib for C
## code elsewhere in your dependencies. Otherwise, use zlib-ng.
zlib-ng-compat = ["zlib", "flate2?/zlib-ng-compat"]
## Use a slower C-based backend which can compress and decompress significantly faster than the rust version.
## Unlike `zlib-ng-compat`, this allows using dynamic linking with system `zlib` libraries and doesn't require cmake.
zlib-stock = ["zlib", "flate2?/zlib"]
## Pure Rust backend, available for completeness even though it's the default
## if neither of the above options are set. Low performance, but pure Rust, so it
## may build in environments where other backends don't.
zlib-rust-backend = ["zlib", "flate2?/rust_backend"]

#! ### Mutually Exclusive SHA1
## A fast SHA1 implementation is critical to `gitoxide's` object database performance
## A multi-crate implementation that can use hardware acceleration, thus bearing the potential for up to 2Gb/s throughput on
## CPUs that support it, like AMD Ryzen or Intel Core i3, as well as Apple Silicon like M1.
## Takes precedence over `rustsha1` if both are specified.
fast-sha1 = ["dep:sha1"]
## A standard and well performing pure Rust implementation of Sha1. Will significantly slow down various git operations.
rustsha1 = ["dep:sha1_smol"]

#! ### Other

## Count cache hits and misses and print that debug information on drop.
## Caches implement this by default, which costs nothing unless this feature is enabled
cache-efficiency-debug = []

[[test]]
name = "hash"
path = "tests/hash.rs"
required-features = ["rustsha1"]

[[test]]
name = "parallel"
path = "tests/parallel_threaded.rs"
required-features = ["parallel", "rustsha1"]

[[test]]
name = "multi-threaded"
path = "tests/parallel_shared_threaded.rs"
required-features = ["parallel", "rustsha1"]

[[test]]
name = "single-threaded"
path = "tests/parallel_shared.rs"
required-features = ["rustsha1"]

[[test]]
name = "pipe"
path = "tests/pipe.rs"
required-features = ["io-pipe"]

[dependencies]
gix-hash = { version = "^0.14.2", path = "../gix-hash" }
gix-trace = { version = "^0.1.8", path = "../gix-trace" }

# for walkdir
gix-utils = { version = "^0.1.11", path = "../gix-utils", optional = true }

# 'parallel' feature
crossbeam-channel = { version = "0.5.0", optional = true }
parking_lot = { version = "0.12.0", default-features = false, optional = true }

jwalk = { version = "0.8.1", optional = true }
walkdir = { version = "2.3.2", optional = true } # used when parallel is off

# hashing and 'fast-sha1' feature
sha1_smol = { version = "1.0.0", optional = true }
crc32fast = { version = "1.2.1", optional = true }
sha1 = { version = "0.10.0", optional = true }

# progress
prodash = { workspace = true, optional = true }
bytesize = { version = "1.0.1", optional = true }

# pipe
bytes = { version = "1.0.0", optional = true }

# zlib module
flate2 = { version = "1.0.25", optional = true, default-features = false }
thiserror = { version = "1.0.38", optional = true }

once_cell = { version = "1.13.0", optional = true }

document-features = { version = "0.2.0", optional = true }

[target.'cfg(unix)'.dependencies]
libc = { version = "0.2.119" }

[dev-dependencies]
bstr = { version = "1.3.0", default-features = false }


# Assembly doesn't yet compile on MSVC on windows, but does on GNU, see https://github.com/RustCrypto/asm-hashes/issues/17
# At this time, only aarch64, x86 and x86_64 are supported.
[target.'cfg(all(any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64"), not(target_os = "windows")))'.dependencies]
sha1 = { version = "0.10.0", optional = true, features = ["asm"] }

[package.metadata.docs.rs]
all-features = true
features = ["document-features"]