general: refactor build script; readme misc.

shell.nix

@@ -1,57 +1,63 @@
+# Build environment for the SM-T365 TWRP build (omni twrp-5.1, GCC 4.8-era).
+#
+# nixpkgs 22.11 is pinned because this old toolchain only links against legacy
+# host libraries (ncurses5, 32-bit libstdc++, old glibc layout). buildFHSUserEnv
+# synthesises those paths so AOSP prebuilt host binaries run unpatched.
+
 let
   pkgs = import (fetchTarball {
-    # An older nixpkgs version is required for old GCC and C++
-    # libraries.
     url = "https://github.com/NixOS/nixpkgs/archive/nixos-22.11.tar.gz";
   }) {};
-  
-  fhs = pkgs.buildFHSUserEnv {
-      name = "android-env";
 
-      targetPkgs = pkgs: with pkgs; [
-        git
-        gitRepo
-        gnupg
-        python2
-        curl
-        procps
-        openssl
-        gnumake
-        nettools
-        android-tools
-        jdk8
-        schedtool
-        util-linux
-        m4
-        gperf
-        perl
-        libxml2
-        zip
-        unzip
-        bison
-        flex
-        lzop
-        xz
-        python3
-      ];
-      
-      multiPkgs = pkgs: with pkgs; [
-        zlib
-        ncurses5
-        pkgsi686Linux.gcc9
-        pkgsi686Linux.libstdcxx5
-      ];
-      
-      runScript = "bash";
-      profile = "export ANDROID_JAVA_HOME=${pkgs.jdk8.home}";
-    };
+  fhs = pkgs.buildFHSUserEnv {
+    name = "android-env";
+
+    # Tools called directly on PATH by the build and by the user.
+    targetPkgs = pkgs: with pkgs; [
+      git         # the device/kernel clones (and `repo` plumbing)
+      gitRepo     # AOSP `repo` multi-repo tool
+      gnumake     # `mka` -> make for the omni build
+      python2     # omni-5.1 era build scripts expect python2
+      python3     # modern `repo` runs under python3
+      curl        # toolchain tarball download in build_twrp.sh
+      openssl     # used by a few AOSP host tools
+      procps      # `ps`/`pidof` referenced by build scripts
+      util-linux  # uuidgen and friends used during image building
+      android-tools # adb / fastboot for flashing and testing
+      jdk8        # 5.1 needs java <=8 (signapk, dx)
+      schedtool   # legacy tool invoked by some omni scripts
+      m4 gperf bison flex   # classic AOSP host toolchain
+      perl        # kernel/scripting helper (timeconst.pl, etc.)
+      libxml2     # xml libs used by host tools
+      zip unzip   # packaging
+      lzop        # legacy lzo support
+      xz          # LZMA ramdisk compression (mkbootimg.mk)
+      gnupg       # gpg for repo manifest verification (optional)
+      nettools    # minor networking helpers used by host scripts
+    ];
+
+    # Multilib: the 5.1 ia32 host tools need 32-bit libstdc++ and zlib;
+    # ncurses5 is required by older host builds.
+    multiPkgs = pkgs: with pkgs; [
+      zlib
+      ncurses5
+      pkgsi686Linux.gcc9
+      pkgsi686Linux.libstdcxx5
+    ];
+
+    runScript = "bash";
+    profile = "export ANDROID_JAVA_HOME=${pkgs.jdk8.home}";
+  };
 in pkgs.stdenv.mkDerivation {
   name = "android-env-shell";
   nativeBuildInputs = [ fhs ];
   shellHook = ''
+    # `nix-shell --run "cmd"` is unreliable here: the unconditional
+    # `exec android-env` would swallow the command, so forward it explicitly.
+    # build_twrp.sh still uses a stdin pipe because it is the tested path.
     if [ -n "$BASH_EXECUTION_STRING" ]; then
       exec android-env -c "$BASH_EXECUTION_STRING"
     fi
     exec android-env
   '';
-}
+}