diffoscope: Document the script to locate missing optional dependencies

And give it it a bit more descriptive name of list-missing-tools.sh.

2 files changed, 7 insertions, 0 deletions

diff --git a/pkgs/tools/misc/diffoscope/default.nix b/pkgs/tools/misc/diffoscope/default.nix
index 73b7f2272cdd..e55d5c89b5b1 100644
--- a/pkgs/tools/misc/diffoscope/default.nix
+++ b/pkgs/tools/misc/diffoscope/default.nix
@@ -6,6 +6,7 @@
 , enableBloat ? false
 }:
 
+# Note: when upgrading this package, please run the list-missing-tools.sh script as described below!
 python3Packages.buildPythonApplication rec {
   name = "diffoscope-${version}";
   version = "99";
@@ -30,6 +31,9 @@ python3Packages.buildPythonApplication rec {
 
   nativeBuildInputs = [ docutils help2man ];
 
+  # Most of the non-Python dependencies here are optional command-line tools for various file-format parsers.
+  # To help figuring out what's missing from the list, run: ./pkgs/tools/misc/diffoscope/list-missing-tools.sh
+  #
   # Still missing these tools: abootimg docx2txt dumpxsb enjarify js-beautify lipo oggDump otool procyon-decompiler Rscript
   # Also these libraries: python3-guestfs
   pythonPath = with python3Packages; [ debian libarchive-c python_magic tlsh rpm ] ++ [
diff --git a/pkgs/tools/misc/diffoscope/list-tools.sh b/pkgs/tools/misc/diffoscope/list-missing-tools.sh
index 9af7f0e38899..5f4d118cfed7 100755
--- a/pkgs/tools/misc/diffoscope/list-tools.sh
+++ b/pkgs/tools/misc/diffoscope/list-missing-tools.sh
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# This script lists all the optional command-line tools that diffoscope can use
+# (i.e. `diffoscope --list-tools`) but are missing from the Nix expression.
+
 diffoscope=$(nix-build --no-out-link -E 'with import ./. {}; diffoscope.override { enableBloat = true; }')/bin/diffoscope
 
 required=$($diffoscope --list-tools | \