From 83cd732b9180a218b0b5ed0154f1c735b0e58751 Mon Sep 17 00:00:00 2001
From: Joel Natividad <1980690+jqnatividad@users.noreply.github.com>
Date: Wed, 4 Dec 2024 05:41:57 -0500
Subject: [PATCH] docs: add more info about special "build features"

fixes #2324

[skip ci]
---
 README.md        |  3 ++-
 docs/FEATURES.md | 11 +++++++----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4c1a0cefa..8043eb756 100644
--- a/README.md
+++ b/README.md
@@ -250,7 +250,7 @@ To compile different [variants](#variants) and enable optional [features](#featu
 
 ```bash
 # to compile qsv with all features enabled
-cargo build --release --locked --bin qsv --features feature_capable,apply,luau,fetch,foreach,python,to,self_update,polars
+cargo build --release --locked --bin qsv --features feature_capable,apply,fetch,foreach,geocode,luau,polars,python,self_update,ui
 # shorthand
 cargo build --release --locked --bin qsv -F all_features
 
@@ -265,6 +265,7 @@ cargo build --release --locked --bin qsvdp -F datapusher_plus,luau,polars
 ```
 
 > **_NOTE:_** To build with Rust nightly, see [Nightly Release Builds](docs/PERFORMANCE.md#nightly-release-builds).
+The `feature_capable`, `lite` and `datapusher_plus` are MUTUALLY EXCLUSIVE features. See [Special Build Features](docs/FEATURES.md#special-features-for-building-qsv-binary-variants) for more info.
 
 ### Variants
 
diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index 725c03049..4e71ef434 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -19,10 +19,13 @@ You need not worry that your manually built qsv will be overwritten by a self-up
 To check if your qsv build will have the option to self-update, run `qsv --version`. If you see `self_update` in the enabled features, and QSV_KIND is `prebuilt*` at the end, then you have the option to self-update.
 * `ui` - enables commands that require linking UI libraries - `clipboard`, `lens` and `prompt`. Disable this feature if you're building for a headless environment. Note that `qsvdp` and `qsvlite` does not enable the `ui` feature by default.
 
-* `feature_capable` - enable to build `qsv` binary variant which is feature-capable.
-* `all_features` - enable to build `qsv` binary variant with all features enabled (apply,fetch,foreach,geocode,lens,luau,polars,prompt,python,to,self_update).
-* `lite` - enable to build `qsvlite` binary variant with all features disabled.
-* `datapusher_plus` - enable to build `qsvdp` binary variant - the [DataPusher+](https://github.com/dathere/datapusher-plus) optimized qsv binary.
+## Special Features for building qsv binary variants:
+
+* `feature_capable` - enable to build `qsv` binary variant which is feature-capable. (mutually exclusive with `lite` and `datapusher_plus`)
+  * `all_features` - shortcut to enable to build `qsv` binary variant with all features enabled (apply,fetch,foreach,geocode,luau,polars,python,to,self_update,ui).
+
+* `lite` - enable to build `qsvlite` binary variant with all features disabled. (mutually exclusive with `feature_capable` and `datapusher_plus`)
+* `datapusher_plus` - enable to build `qsvdp` binary variant - the [DataPusher+](https://github.com/dathere/datapusher-plus) optimized qsv binary. (mutually exclusive with `feature_capable` and `lite`)
 * `nightly` - enable to turn on nightly/unstable features in the `crc32fast`, `hashbrown`, `polars`, `pyo3` & `rand` crates when building with Rust nightly/unstable.
 * `distrib_features` - enable to build `qsv` binary variant with all features enabled except `self_update`. This should make it easier for distro packagers to build `qsv` with all features enabled except `self_update` as qsv removes and adds features over time.