From 171f9d660c3a050994ec034719362ef171bc7737 Mon Sep 17 00:00:00 2001
From: Terts Diepraam <terts.diepraam@gmail.com>
Date: Sat, 19 Aug 2023 18:00:33 +0200
Subject: [PATCH] docs: add platform support page in the docs

---
 docs/.gitignore       |  1 +
 docs/src/platforms.md | 45 +++++++++++++++++++++++++++++++++++++++++++
 src/bin/uudoc.rs      | 45 +++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 89 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/platforms.md

diff --git a/docs/.gitignore b/docs/.gitignore
index c669da8f6..be017dfbe 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,4 +1,5 @@
 book
 src/utils
 src/SUMMARY.md
+src/platform_table.md
 tldr.zip
\ No newline at end of file
diff --git a/docs/src/platforms.md b/docs/src/platforms.md
new file mode 100644
index 000000000..56ec616fc
--- /dev/null
+++ b/docs/src/platforms.md
@@ -0,0 +1,45 @@
+# Platform support
+
+<!-- markdownlint-disable MD033 -->
+
+uutils aims to be as "universal" as possible, meaning that we try to support
+many platforms. However, it is infeasible for us to guarantee that every
+platform works. Just like Rust itself, we therefore have multiple tiers of
+platform support, with different guarantees. We support two tiers of platforms:
+
+ - **Tier 1**: All applicable utils are compiled and tested in CI for these
+   platforms.
+ - **Tier 2**: These platforms are supported but not actively tested. We do accept
+   fixes for these platforms.
+
+> **Note**: The tiers are dictated by our CI. We would happily accept a job
+> in the CI for testing more platforms, bumping those platforms to tier 1.
+
+## Platforms per tier
+
+The platforms in tier 1 and the platforms that we test in CI are listed below.
+
+| Operating system | Tested targets |
+| ---------------- | -------------- |
+| **Linux**        | `x86_64-unknown-linux-gnu` <br> `x86_64-unknown-linux-musl` <br> `arm-unknown-linux-gnueabihf` <br> `i686-unknown-linux-gnu` <br> `aarch64-unknown-linux-gnu` |
+| **macOS**        | `x86_64-apple-darwin` |
+| **Windows**      | `i686-pc-windows-msvc` <br> `x86_64-pc-windows-gnu` <br> `x86_64-pc-windows-msvc` |
+| **FreeBSD**      | `x86_64-unknown-freebsd` |
+| **Android**      | `i686-linux-android` |
+
+The platforms in tier 2 are more vague, but include:
+
+ - untested variations of the platforms above,
+ - Redox OS,
+ - and BSDs such as OpenBSD, NetBSD & DragonFlyBSD.
+
+## Utility compatibility per platform
+
+Not all utils work on every platform. For instance, `chgrp` is not supported on
+Windows, because Windows does have the concept of groups. Below is a full table
+detailing which utilities are supported for the tier 1 platforms.
+
+Note that for some utilities, not all functionality is supported on each
+platform. This is documented per utility.
+
+{{ #include platform_table.md }}
diff --git a/src/bin/uudoc.rs b/src/bin/uudoc.rs
index 5ac858226..77c7a2fcf 100644
--- a/src/bin/uudoc.rs
+++ b/src/bin/uudoc.rs
@@ -42,6 +42,7 @@ fn main() -> io::Result<()> {
         [Introduction](index.md)\n\
         * [Installation](installation.md)\n\
         * [Build from source](build.md)\n\
+        * [Platform support](platforms.md)\n\
         * [Contributing](contributing.md)\n\
         * [GNU test coverage](test_coverage.md)\n\
         * [Extensions](extensions.md)\n\
@@ -53,7 +54,7 @@ fn main() -> io::Result<()> {
     println!("Gathering utils per platform");
     let utils_per_platform = {
         let mut map = HashMap::new();
-        for platform in ["unix", "macos", "windows"] {
+        for platform in ["unix", "macos", "windows", "unix_android"] {
             let platform_utils: Vec<String> = String::from_utf8(
                 std::process::Command::new("./util/show-utils.sh")
                     .arg(format!("--features=feat_os_{}", platform))
@@ -61,6 +62,7 @@ fn main() -> io::Result<()> {
                     .stdout,
             )
             .unwrap()
+            .trim()
             .split(' ')
             .map(ToString::to_string)
             .collect();
@@ -75,6 +77,7 @@ fn main() -> io::Result<()> {
                 .stdout,
         )
         .unwrap()
+        .trim()
         .split(' ')
         .map(ToString::to_string)
         .collect();
@@ -83,9 +86,47 @@ fn main() -> io::Result<()> {
         map
     };
 
-    println!("Writing to utils");
     let mut utils = utils.entries().collect::<Vec<_>>();
     utils.sort();
+
+    println!("Writing util per platform table");
+    {
+        let mut platform_table_file = File::create("docs/src/platform_table.md").unwrap();
+
+        // sum, cksum, b2sum, etc. are all available on all platforms, but not in the data structure
+        // otherwise, we check the map for the util name.
+        let check_supported = |name: &str, platform: &str| {
+            if name.ends_with("sum") || utils_per_platform[platform].iter().any(|u| u == name) {
+                "✓"
+            } else {
+                " "
+            }
+        };
+        writeln!(
+            platform_table_file,
+            "| util             | Linux | macOS | Windows | FreeBSD | Android |\n\
+             | ---------------- | ----- | ----- | ------- | ------- | ------- |"
+        )?;
+        for (&name, _) in &utils {
+            if name == "[" {
+                continue;
+            }
+            // The alignment is not necessary, but makes the output a bit more
+            // pretty when viewed as plain markdown.
+            writeln!(
+                platform_table_file,
+                "| {:<16} | {:<5} | {:<5} | {:<7} | {:<7} | {:<7} |",
+                format!("**{name}**"),
+                check_supported(name, "linux"),
+                check_supported(name, "macos"),
+                check_supported(name, "windows"),
+                check_supported(name, "unix"),
+                check_supported(name, "unix_android"),
+            )?;
+        }
+    }
+
+    println!("Writing to utils");
     for (&name, (_, command)) in utils {
         if name == "[" {
             continue;