From f98c5c9cd6662eece985321d323a3e0f2fecb11d Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Tue, 16 Apr 2024 16:04:16 +0800
Subject: [PATCH] Update README (#407)

* Update README

* Write changelog
---
 CHANGELOG.md |   1 +
 INSTALL.md   |  83 +++++++++++++++++++++++++++
 README.md    | 158 +++++++++++++++++++--------------------------------
 3 files changed, 144 insertions(+), 98 deletions(-)
 create mode 100644 INSTALL.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ca6c8b7..bc98dfd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 * CI: Configure dependabot grouping #395 - @cyqsimon
 * CI refactor #399 - @cyqsimon
 * CI: Temporarily disable UI tests #406 - @cyqsimon
+* Update README #407 - @cyqsimon
 
 ## Removed
 
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..e3e438b
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,83 @@
+# Installation
+
+- [Installation](#installation)
+  - [Arch Linux](#arch-linux)
+  - [Exherbo Linux](#exherbo-linux)
+  - [Nix/NixOS](#nixnixos)
+  - [Void Linux](#void-linux)
+  - [Fedora](#fedora)
+  - [macOS/Linux (using Homebrew)](#macoslinux-using-homebrew)
+  - [macOS (using MacPorts)](#macos-using-macports)
+  - [FreeBSD](#freebsd)
+  - [Cargo](#cargo)
+
+## Arch Linux
+
+```
+pacman -S bandwhich
+```
+
+## Exherbo Linux
+
+`bandwhich` is available in [rust repository](https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/sys-apps/bandwhich), and can be installed via `cave`:
+
+```
+cave resolve -x repository/rust
+cave resolve -x bandwhich
+```
+
+## Nix/NixOS
+
+`bandwhich` is available in [`nixpkgs`](https://github.com/nixos/nixpkgs/blob/master/pkgs/tools/networking/bandwhich/default.nix), and can be installed, for example, with `nix-env`:
+
+```
+nix-env -iA nixpkgs.bandwhich
+```
+
+## Void Linux
+
+```
+xbps-install -S bandwhich
+```
+
+## Fedora
+
+`bandwhich` is available in [COPR](https://copr.fedorainfracloud.org/coprs/atim/bandwhich/), and can be installed via DNF:
+
+```
+sudo dnf copr enable atim/bandwhich -y && sudo dnf install bandwhich
+```
+
+## macOS/Linux (using Homebrew)
+
+```
+brew install bandwhich
+```
+
+## macOS (using MacPorts)
+
+```
+sudo port selfupdate
+sudo port install bandwhich
+```
+
+## FreeBSD
+
+```
+pkg install bandwhich
+```
+
+or
+
+```
+cd /usr/ports/net-mgmt/bandwhich && make install clean
+```
+
+## Cargo
+
+Regardless of OS, you can always fallback to the Rust package manager, `cargo`.
+For installation instructions of the Rust toolchain, see [here](https://www.rust-lang.org/tools/install).
+
+```
+cargo install bandwhich
+```
diff --git a/README.md b/README.md
index c488982..967b43a 100644
--- a/README.md
+++ b/README.md
@@ -13,16 +13,9 @@ This is a CLI utility for displaying current network utilization by process, con
   - [Installation](#installation)
     - [Downstream packaging status](#downstream-packaging-status)
     - [Download a prebuilt binary](#download-a-prebuilt-binary)
-    - [Arch Linux](#arch-linux)
-    - [Exherbo Linux](#exherbo-linux)
-    - [Nix/NixOS](#nixnixos)
-    - [Void Linux](#void-linux)
-    - [Fedora](#fedora)
-    - [macOS/Linux (using Homebrew)](#macoslinux-using-homebrew)
-    - [macOS (using MacPorts)](#macos-using-macports)
-    - [FreeBSD](#freebsd)
-    - [Building from source using `cargo`](#building-from-source-using-cargo)
-    - [OpenWRT](#openwrt)
+  - [Building from source](#building-from-source)
+    - [Cross-compiling](#cross-compiling)
+      - [Android](#android)
   - [Post install (Linux)](#post-install-linux)
     - [1. `setcap`](#1-setcap)
       - [Capabilities explained](#capabilities-explained)
@@ -51,113 +44,82 @@ For more details, see [The Future of Bandwhich #275](https://github.com/imsnif/b
 
 ### Downstream packaging status
 
+For detailed instructions for each platform, see [INSTALL.md](INSTALL.md).
+
 <a href="https://repology.org/project/bandwhich/versions">
   <img src="https://repology.org/badge/vertical-allrepos/bandwhich.svg?columns=3" alt="Packaging status">
 </a>
 
 ### Download a prebuilt binary
 
-If you're on `android` or `linux`, you can download the generic binary from the [releases](https://github.com/imsnif/bandwhich/releases)
+We offer several generic binaries in [releases](https://github.com/imsnif/bandwhich/releases) for various OSes.
 
-### Arch Linux
+<table>
+  <thead>
+    <th>OS</th><th>Architecture</th><th>Support</th><th>Usage</th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Android</td><td>aarch64</td><td>Best effort</td>
+      <td>
+        <p>All modern Android devices.</p>
+        <p>Note that this is a pure binary file, not an APK suitable for general usage.</p>
+      </td>
+    </tr>
+    <tr>
+      <td rowspan="3">Linux</td><td>aarch64</td><td>Full</td>
+      <td>64-bit ARMv8+ (servers, some modern routers, RPi-4+).</td>
+    </tr>
+    <tr>
+      <td>armv7hf</td><td>Best effort</td><td>32-bit ARMv7 (older routers, pre-RPi-4).</td>
+    </tr>
+    <tr>
+      <td>x64-gnu</td><td>Full</td>
+      <td>Most Linux desktops & servers.</td>
+    </tr>
+    <tr>
+      <td rowspan="2">MacOS</td><td>aarch64</td><td rowspan="2">Full</td>
+      <td>Apple silicon Macs (2021+).</td>
+    </tr>
+    <tr>
+      <td>x64</td>
+      <td>Intel Macs (pre-2021).</td>
+    </tr>
+    <tr>
+      <td>Windows</td><td>x64</td><td>Full</td>
+      <td>Most Windows desktops & servers.</td>
+    </tr>
+  </tbody>
+</table>
 
-```
-pacman -S bandwhich
+## Building from source
+
+```sh
+git clone https://github.com/imsnif/bandwhich.git
+cd bandwhich
+cargo build --release
 ```
 
-### Exherbo Linux
+For the up-to-date minimum supported Rust version, please refer to the `rust-version` field in [Cargo.toml](Cargo.toml).
 
-`bandwhich` is available in [rust repository](https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/sys-apps/bandwhich), and can be installed via `cave`:
+### Cross-compiling
 
-```
-cave resolve -x repository/rust
-cave resolve -x bandwhich
-```
+Cross-compiling for alternate targets is supported via [cross](https://github.com/cross-rs/cross). Here's the rough procedure:
 
-### Nix/NixOS
+1. Check the target architecture. If on Linux, you can use `uname -m`.
+2. Lookup [rustc platform support](https://doc.rust-lang.org/rustc/platform-support.html) for the corresponding target triple.
+3. [Install `cross`](https://github.com/cross-rs/cross#installation).
+4. Run `cross build --release --target <TARGET_TRIPLE>`.
 
-`bandwhich` is available in [`nixpkgs`](https://github.com/nixos/nixpkgs/blob/master/pkgs/tools/networking/bandwhich/default.nix), and can be installed, for example, with `nix-env`:
+#### Android
 
-```
-nix-env -iA nixpkgs.bandwhich
-```
-
-### Void Linux
-
-```
-xbps-install -S bandwhich
-```
-
-### Fedora
-
-`bandwhich` is available in [COPR](https://copr.fedorainfracloud.org/coprs/atim/bandwhich/), and can be installed via DNF:
-
-```
-sudo dnf copr enable atim/bandwhich -y && sudo dnf install bandwhich
-```
-
-### macOS/Linux (using Homebrew)
-
-```
-brew install bandwhich
-```
-
-### macOS (using MacPorts)
-
-```
-sudo port selfupdate
-sudo port install bandwhich
-```
-
-### FreeBSD
-
-```
-pkg install bandwhich
-```
-
-or
-
-```
-cd /usr/ports/net-mgmt/bandwhich && make install clean
-```
-
-### Building from source using `cargo`
-
-`bandwhich` can be installed using the Rust package manager, `cargo`.
-It might be in your distro repositories if you're on linux, or you can install it via [rustup](https://rustup.rs/).
-You can find additional installation instructions [here](https://doc.rust-lang.org/book/ch01-01-installation.html).
-
-The minimum supported Rust version is **1.70.0**.
-
-```
-cargo install bandwhich
-```
-
-#### Building from source for Android (`aarch64-linux-android`)
-
-Building for target `aarch64-linux-android` is supported via [cross](https://github.com/cross-rs/cross). Until [#1222](https://github.com/cross-rs/cross/issues/1222) is solved, use the latest HEAD:
+Until [cross-rs/cross#1222](https://github.com/cross-rs/cross/issues/1222) is solved, use the latest HEAD:
 
 ```sh
 cargo install --git https://github.com/cross-rs/cross.git cross
 cross build --release --target aarch64-linux-android
 ```
 
-Kindly be aware that this process generates a pure binary file and not an APK suitable for installation on any arbitrary Android device.
-
-The Android support for bandwhich beyond its build is *not* endorsed by this project and may be unstable or non-functional.
-
-### OpenWRT
-
-To install `bandwhich` on OpenWRT, you'll need to compile a binary that would fit its processor architecture. This might mean you would have to cross compile if, for example, you're working on an `x86_64` and the OpenWRT is installed on an `arm7`.
-Here is an example of cross compiling in this situation:
-
-- Check the processor architecture of your router by using `uname -m`
-- Clone the bandwhich repository `git clone https://github.com/imsnif/bandwhich`
-- Install `cross` using `cargo install cross`
-- build the `bandwhich` package using `cross build --target armv7-unknown-linux-musleabihf`
-- Copy the binary files from `target/armv7-unknown-linux-musleabihf/debug/bandwhich` to the router using `scp` by running `scp bandwhich root@192.168.1.1:~/` (here, 192.168.1.1 would be the IP address of your router).
-- Finally enter the router using ssh and run the binary directly with `./bandwhich`
-
 ## Post install (Linux)
 
 Since `bandwhich` sniffs network packets, it requires elevated privileges.
@@ -170,7 +132,7 @@ On Linux, there are two main ways to accomplish this:
     - This is the **recommended** setup **for single user machines**, or **if all users are trusted**.
     - This is **not recommended** if you want to **ensure users cannot see others' traffic**.
 
-```bash
+```sh
 # assign capabilities
 sudo setcap cap_sys_ptrace,cap_dac_read_search,cap_net_raw,cap_net_admin+ep $(command -v bandwhich)
 # run as unprivileged user
@@ -186,7 +148,7 @@ bandwhich
 - Require privilege escalation every time.
 - Do this if you are an administrator of a multi-user environment.
 
-```bash
+```sh
 sudo bandwhich
 ```