Skip to content

Commit

Permalink
feat: add pro-forma libaray to allow feature documentation of `gitoxi…
Browse files Browse the repository at this point in the history
…de` on docs.rs
  • Loading branch information
Byron committed May 4, 2023
1 parent d67551d commit 13a0f1e
Show file tree
Hide file tree
Showing 3 changed files with 80 additions and 27 deletions.
80 changes: 53 additions & 27 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,48 @@ doctest = false
[features]
default = ["max"]

#! ### Build Configuration
#! These combine common choices of building blocks to represent typical builds.

## Everything, all at once.
##
## 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.
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" ]

## Like `max`, but only Rust is allowed.
##
## 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
## transports as it uses Rust's HTTP implementation.
##
## 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.
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", "gix/regex" ]

## All of the good stuff, with less fanciness for smaller binaries.
##
## 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.
lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]

## The smallest possible build, best suitable for small single-core machines.
##
## This build is essentially limited to local operations without any fanciness.
##
## Optimized for size, no parallelism thus much slower, progress line rendering.
small = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "is-terminal" ]

## Like lean, but uses Rusts async implementations for networking.
##
## 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
## is very limited to only HTTP (without typical `git` configuration) and git over TCP like provided by the `git daemon`.
##
## 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.
##
## Due to async client-networking not being implemented for most transports, this one supports only the 'git+tcp' and HTTP transport.
## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-async-client", "prodash-render-line"]

#! ### Building Blocks
#! Typical combinations of features of our dependencies, some of which are referred to in the `gitoxide` crate's code for conditional compilation.

## Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
## as well as fast, hardware accelerated hashing, along with a faster zlib backend.
## If disabled, the binary will be visibly smaller.
Expand All @@ -39,36 +81,24 @@ pretty-cli = [ "gitoxide-core/serde", "prodash/progress-tree", "prodash/progress
## that appears after a short duration.
prodash-render-line-crossterm = ["prodash-render-line", "prodash/render-line-crossterm", "prodash/signal-hook", "is-terminal", "crosstermion"]

#! ### Convenience Features
#! These combine common choices of the above features to represent typical builds

## *fast* + *prodash-render-tui-crossterm* + *prodash-render-line-crossterm* + *http* + *gitoxide-core-tools* + *client-networking*
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" ]

## *fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-networking*.
lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]
## fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-async-networking*.
## Due to async client-networking not being implemented for most transports, this one supports only the 'git' transport.
## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-async-client", "prodash-render-line"]

## As small as it can possibly be, no threading, no fast sha1, line progress only, rust based zlib implementation.
## no networking, local operations only.
small = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "is-terminal" ]
## Progress reporting with a TUI, can then be enabled with the `--progress` flag.
prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]

## Makes the crate execute as fast as possible without pulling in C libraries, while keeping everything else minimal akin to the `small` build.
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" ]
## Progress reporting by visually drawing lines into the terminal without switching to an alternate window.
prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "prodash/progress-tree"]

#! ### `gitoxide-core` Configuration
## Prints statistical information to inform about cache efficiency when those are dropped.
## Use this as a way to understand if bigger caches actually produce greater yiedls.
cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]

## A way to enable all `gitoxide-core` tools found in `gix tools`
## A way to enable most `gitoxide-core` tools found in `ein tools`, namely `organize` and `estimate hours`.
gitoxide-core-tools = ["gitoxide-core/organize", "gitoxide-core/estimate-hours"]

## A program to perform analytics on a git repository, using an auto-maintained sqlite database
## A program to perform analytics on a `git` repository, using an auto-maintained sqlite database
gitoxide-core-tools-query = ["gitoxide-core-tools", "gitoxide-core/query"]

#! #### Mutually Exclusive Networking
#! If both are set a compile error is triggered. This also means that `cargo … --all-features` will fail.
#! ### Building Blocks for mutually exclusive networking
#! If some of these are set at the same time a compile error is triggered. This also means that `cargo … --all-features` will fail.

## Use blocking client networking.
gitoxide-core-blocking-client = ["gitoxide-core/blocking-client"]
Expand All @@ -79,10 +109,6 @@ http-client-reqwest = ["gix/blocking-http-transport-reqwest-rust-tls"]
## Use async client networking.
gitoxide-core-async-client = ["gitoxide-core/async-client", "futures-lite"]

# internal
prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]
prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "prodash/progress-tree"]
cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]

[dependencies]
anyhow = "1.0.42"
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,9 @@ effortlessly and for your particular CPU for additional performance gains.
The minimum supported Rust version is [documented in the CI configuration](https://github.com/Byron/gitoxide/blob/main/.github/workflows/msrv.yml#L23),
the latest stable one will work as well.

There are various build configurations, all of them are [documented here](https://docs.rs/crate/gitoxide/latest). The documentation should also be useful
for packagers who need to tune external dependencies.

```
# A certain way to install `gitoxide` with just Rust and a C compiler installed.
# If there are problems with SSL certificates during clones, try to omit `--locked`.
Expand Down
24 changes: 24 additions & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
//! This is the documentation of the binaries that come with `gitoxide`. These are called…
//!
//! #### `gix`
//!
//! A developer tool to allow using `gitoxide` algorithms and functionality outside of the test suite. It will be unstable as long as
//! the `gix` crate is unstable and is explicitly not to be understood as `git` replacement.
//!
//! #### `ein`
//!
//! A program to eventually become the most convenient way to do typical operations on `git` repositories, with all tooling one typically
//! needs built right into it.
//! For now, it's most useful for its assorted set of `tools` which help to build automations or learn something about `git` repositories.
//!
//! ## Feature Flags
//!
//! Feature configuration can be complex and this document seeks to provide an overview.
//!
#![cfg_attr(
feature = "document-features",
cfg_attr(doc, doc = ::document_features::document_features!())
)]
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
#![deny(rust_2018_idioms, missing_docs)]
#![forbid(unsafe_code)]

0 comments on commit 13a0f1e

Please sign in to comment.