History

Merge branch 'fix-841'

Sebastian Thiel committed 3 years ago

Commit edeb4de2 parents d67551d add3a054 files · +120 −28Browse files

Unified · Split

4 files
  1. Cargo.toml +92 −28
  2. Makefile +1 −0
  3. README.md +3 −0
  4. src/lib.rs +24 −0
Cargo.toml+92−28
@@ -25,11 +25,84 @@ doctest = false · 24 unmodified lines
2525 [features]
2626 default = ["max"]
2727
28+#! ### Build Configuration
29+#! These combine common choices of building blocks to represent typical builds.
30+
31+## Everything, all at once.
32+##
33+## As fast as possible, with TUI progress, progress line rendering with auto-configuration, all transports based on their most mature implementation (HTTP), all `ein` tools, CLI colors and local-time support, JSON output, regex support for rev-specs.
34+max = ["max-control", "fast", "gitoxide-core-blocking-client", "http-client-curl"]
35+
36+## Like `max`, but only Rust is allowed.
37+##
38+## This is the most compatible build as it won't need a C compiler or C toolchains to build. It's also not the fastest as or the most feature-rich in terms of available
39+## transports as it uses Rust's HTTP implementation.
40+##
41+## As fast as possible, with TUI progress, progress line rendering with auto-configuration, all transports available but less mature pure Rust HTTP implementation, all `ein` tools, CLI colors and local-time support, JSON output, regex support for rev-specs.
42+max-pure = ["max-control", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "http-client-reqwest", "gitoxide-core-blocking-client" ]
43+
44+## Like `max`, but with more control for configuration. See the *Package Maintainers* headline for more information.
45+max-control = ["fast-safe", "pretty-cli", "gitoxide-core-tools-query", "gitoxide-core-tools", "prodash-render-line", "prodash-render-tui", "prodash/render-line-autoconfigure", "gix/regex" ]
46+
47+## All of the good stuff, with less fanciness for smaller binaries.
48+##
49+## As fast as possible, progress line rendering, all transports based on their most mature implementation (HTTP), all `ein` tools, CLI colors and local-time support, JSON output.
50+lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]
51+
52+## The smallest possible build, best suitable for small single-core machines.
53+##
54+## This build is essentially limited to local operations without any fanciness.
55+##
56+## Optimized for size, no parallelism thus much slower, progress line rendering.
57+small = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "is-terminal" ]
58+
59+## Like lean, but uses Rusts async implementations for networking.
60+##
61+## This build is more of a demonstration showing how async can work with `gitoxide`, which generally is blocking. This also means that the selection of async transports
62+## is very limited to only HTTP (without typical `git` configuration) and git over TCP like provided by the `git daemon`.
63+##
64+## As fast as possible, progress line rendering, less feature-ful HTTP (pure Rust) and only `git-damon` support, all `ein` tools, CLI colors and local-time support, JSON output.
65+##
66+## Due to async client-networking not being implemented for most transports, this one supports only the 'git+tcp' and HTTP transport.
67+## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
68+lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-async-client", "prodash-render-line"]
69+
70+#! ### Package Maintainers
71+#! `*-control` features leave it to you to configure C libraries, involving choices for `zlib`, ! hashing and transport implementation.
72+#!
73+#! Additional features *can* be provided with `--features` and are handled by the [`gix-features` crate](https://docs.rs/gix-features/latest).
74+#! If nothing else is specified, the Rust implementation is used. ! Note that only one feature of each section can be enabled at a time.
75+#!
76+#! * **zlib**
77+#! - `gix-features/zlib-ng`
78+#! - `gix-features/zlib-ng-compat`
79+#! - `gix-features/zlib-stock`
80+#! - `gix-features/zlib-rust-backend` (*default if no choice is made*)
81+#! * **sha1**
82+#! - `gix-features/fast-sha1`
83+#! - `gix-features/rustsha1` (*default if no choice is made*)
84+#! * **HTTP** - see the *Building Blocks for mutually exclusive networking* headline
85+#!
86+#! #### Examples
87+#!
88+#! * `cargo build --release --no-default-features --features max-control,gix-features/zlib-stock,gitoxide-core-blocking-client,http-client-curl`
89+#! - Create a build just like `max`, but using the stock `zlib` library instead of `zlib-ng`
90+#! * `cargo build --release --no-default-features --features max-control,http-client-reqwest,gitoxide-core-blocking-client,gix-features/fast-sha1`
91+#! - Create a build just like `max-pure`, but with faster hashing due to `fast-sha1`.
92+
93+#! ### Building Blocks
94+#! Typical combinations of features of our dependencies, some of which are referred to in the `gitoxide` crate's code for conditional compilation.
95+
2896 ## Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
2997 ## as well as fast, hardware accelerated hashing, along with a faster zlib backend.
3098 ## If disabled, the binary will be visibly smaller.
3199 fast = ["gix/max-performance", "gix/comfort"]
32100
101+## Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
102+## as well as fast, hardware accelerated hashing, along with a faster zlib backend.
103+## If disabled, the binary will be visibly smaller.
104+fast-safe = ["gix/max-performance-safe", "gix/comfort"]
105+
33106 ## Use `clap` 3.0 to build the prettiest, best documented and most user-friendly CLI at the expense of binary size.
34107 ## Provides a terminal user interface for detailed and exhaustive progress.
35108 ## Provides a line renderer for leaner progress display, without the need for a full-blown TUI.
@@ -39,50 +112,41 @@ pretty-cli = [ "gitoxide-core/serde", "prodash/progress-tree", "prodash/progress · 3 unmodified lines
39112 ## that appears after a short duration.
40113 prodash-render-line-crossterm = ["prodash-render-line", "prodash/render-line-crossterm", "prodash/signal-hook", "is-terminal", "crosstermion"]
41114
42−#! ### Convenience Features
43−#! These combine common choices of the above features to represent typical builds
44−
45−## *fast* + *prodash-render-tui-crossterm* + *prodash-render-line-crossterm* + *http* + *gitoxide-core-tools* + *client-networking*
46−max = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line", "prodash-render-tui", "prodash/render-line-autoconfigure", "gix/regex" ]
47−
48−## *fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-networking*.
49−lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]
50−## fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-async-networking*.
51−## Due to async client-networking not being implemented for most transports, this one supports only the 'git' transport.
52−## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
53−lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-async-client", "prodash-render-line"]
54−
55−## As small as it can possibly be, no threading, no fast sha1, line progress only, rust based zlib implementation.
56−## no networking, local operations only.
57−small = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "is-terminal" ]
115+## Progress reporting with a TUI, can then be enabled with the `--progress` flag.
116+prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]
58117
59−## Makes the crate execute as fast as possible without pulling in C libraries, while keeping everything else minimal akin to the `small` build.
60−max-pure = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "prodash-render-tui", "gix/max-performance-safe", "gix/comfort", "http-client-reqwest", "gitoxide-core-blocking-client", "gitoxide-core-tools", "prodash/render-line-autoconfigure" ]
118+## Progress reporting by visually drawing lines into the terminal without switching to an alternate window.
119+prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "prodash/progress-tree"]
61120
62−#! ### `gitoxide-core` Configuration
121+## Prints statistical information to inform about cache efficiency when those are dropped.
122+## Use this as a way to understand if bigger caches actually produce greater yiedls.
123+cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]
63124
64−## A way to enable all `gitoxide-core` tools found in `gix tools`
125+## A way to enable most `gitoxide-core` tools found in `ein tools`, namely `organize` and `estimate hours`.
65126 gitoxide-core-tools = ["gitoxide-core/organize", "gitoxide-core/estimate-hours"]
66127
67−## A program to perform analytics on a git repository, using an auto-maintained sqlite database
128+## A program to perform analytics on a `git` repository, using an auto-maintained sqlite database
68129 gitoxide-core-tools-query = ["gitoxide-core-tools", "gitoxide-core/query"]
69130
70−#! #### Mutually Exclusive Networking
71−#! If both are set a compile error is triggered. This also means that `cargo … --all-features` will fail.
72−
131+#! ### Building Blocks for mutually exclusive networking
132+#! Blocking and async features are mutually exclusive and cause a compile-time error. This also means that `cargo … --all-features` will fail.
133+#! Within each section, features can be combined.
134+#!
135+#! #### Blocking
136+#! The backends are mutually exclusive, e.g. choose either `curl` or `request`.
137+#!
73138 ## Use blocking client networking.
74139 gitoxide-core-blocking-client = ["gitoxide-core/blocking-client"]
75140 ## Support synchronous 'http' and 'https' transports (e.g. for clone, fetch and push) using **curl**.
76141 http-client-curl = ["gix/blocking-http-transport-curl"]
77142 ## Support synchronous 'http' and 'https' transports (e.g. for clone, fetch and push) using **reqwest**.
78143 http-client-reqwest = ["gix/blocking-http-transport-reqwest-rust-tls"]
144+
145+#! #### Async
146+#!
79147 ## Use async client networking.
80148 gitoxide-core-async-client = ["gitoxide-core/async-client", "futures-lite"]
81149
82−# internal
83−prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]
84−prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "prodash/progress-tree"]
85−cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]
86150
87151 [dependencies]
88152 anyhow = "1.0.42"
Makefile+1−0
@@ -141,6 +141,7 @@ check: ## Build all code in suitable configurations · 140 unmodified lines
141141 && cargo check --no-default-features
142142 cd gix-odb && cargo check --features serde
143143 cd cargo-smart-release && cargo check --all && cargo check --features vendored-openssl
144+ cargo check --no-default-features --features max-control
144145
145146 unit-tests: ## run all unit tests
146147 cargo test --all
README.md+3−0
@@ -145,6 +145,9 @@ effortlessly and for your particular CPU for additional performance gains. · 144 unmodified lines
145145 The minimum supported Rust version is [documented in the CI configuration](https://github.com/Byron/gitoxide/blob/main/.github/workflows/msrv.yml#L23),
146146 the latest stable one will work as well.
147147
148+There are various build configurations, all of them are [documented here](https://docs.rs/crate/gitoxide/latest). The documentation should also be useful
149+for packagers who need to tune external dependencies.
150+
148151 ```
149152 # A certain way to install `gitoxide` with just Rust and a C compiler installed.
150153 # If there are problems with SSL certificates during clones, try to omit `--locked`.
src/lib.rs+24−0
@@ -0,0 +1,24 @@
1+//! This is the documentation of the binaries that come with `gitoxide`. These are called…
2+//!
3+//! #### `gix`
4+//!
5+//! A developer tool to allow using `gitoxide` algorithms and functionality outside of the test suite. It will be unstable as long as
6+//! the `gix` crate is unstable and is explicitly not to be understood as `git` replacement.
7+//!
8+//! #### `ein`
9+//!
10+//! A program to eventually become the most convenient way to do typical operations on `git` repositories, with all tooling one typically
11+//! needs built right into it.
12+//! For now, it's most useful for its assorted set of `tools` which help to build automations or learn something about `git` repositories.
13+//!
14+//! ## Feature Flags
15+//!
16+//! Feature configuration can be complex and this document seeks to provide an overview.
17+//!
18+#![cfg_attr(
19+ feature = "document-features",
20+ cfg_attr(doc, doc = ::document_features::document_features!())
21+)]
22+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
23+#![deny(rust_2018_idioms, missing_docs)]
24+#![forbid(unsafe_code)]