feat(ppm): auto set imgdiffexe on non-Win

Also improve behavior and logging when saving.

.github/workflows/texlive.yml

@@ -50,9 +50,9 @@ jobs:
       with:
         package-file: .github/workflows/texlive.package
         update-all-packages: true
-    - name: Install pdftoppm
+    - name: Install ppmcheckpdf dependencies
       run: |
-        sudo apt-get install poppler-utils
+        sudo apt-get install imagemagick poppler-utils
 
     # note: old tests in "./testfiles-old" are only checked using pdftex,
     # which is also the engine used to generate .png and .md5 files.
@@ -66,12 +66,13 @@ jobs:
       run: |
         texlua buildend.lua
 
-    ## TODO: only save updated png and md5 files
-    # - name: Upload png and md5
-    #   if: matrix.tool == 'ppmcheckpdf' && steps.ppmcheckpdf.outcome == 'failure'
-    #   uses: actions/upload-artifact@v4
-    #   with:
-    #     name: png-and-md5
-    #     path: |
-    #       testfiles/*.png
-    #       testfiles/*.md5
+    # TODO: generate a list of files related to failed tests, then
+    # upload all them (.tex, .log, .pdf, .png, .md5, etc.)
+    - name: Upload diff files
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: tabularray-diffs
+        path: |
+          build/**/*.diff
+          build/**/*.diff.png

.gitignore

@@ -2,3 +2,5 @@ build/**/*.*
 # unignore default difference files generated by l3build 
 !build/**/*.diff
 !build/**/*.fc
+# unignore diff images created by ppmcheckpdf.lua
+!build/**/*.diff.png

CONTRIBUTING.md

@@ -19,12 +19,17 @@ Contributing to the Code
   - Install `pdftoppm` program. 
     - Windows: `tlmgr install wintools.windows`
     - Ubuntu: `apt-get install poppler-utils`
-    - MacOS: `brew install poppler`
+    - macOS: `brew install poppler`
+  - Install `magick` program.
+    - Windows: see https://imagemagick.org/script/download.php#windows
+    - Ubuntu: `apt-get install imagemagick`
+    - macOS: `brew install imagemagick`
 
 - Run tests
   - Run `l3build check` to compile test files.
   - Run `texlua buildend.lua` to compare MD5 checksums for test outputs of `pdftex` engine.
     - The `buildend.lua` calls `ppmcheckpdf.lua` (both are contained in this repository), which then uses `pdftoppm` program to convert PDF to PNG and makes MD5 checksums.
+    - On non-Windows systems, when ImageMagick CLI program `magick` is available, `ppmcheckpdf.lua` also creates `.diff.md5` diff images for failed tests.
 
 - Update test results
     - Run `l3build save <name>...` to update corresponding `testfiles/<name>.tlg` files.

ppmcheckpdf.lua

@@ -43,6 +43,26 @@ local configname = "config-old"
 testdir = testdir .. "-" .. configname
 
 local imgext = imgext or ".png"
+-- Unlike that in Lua 5.3, texlua's `os.execute` still returns a single
+-- value, representing the error level.
+-- https://github.com/latex3/l3build/pull/333
+local imgdiffexe
+if os.type ~= "windows" then
+  local errorlevel = os.execute("command -v magick 2>&1 >/dev/null")
+  -- "0" is not a falsy value in Lua; "nil" is the only one
+  if errorlevel == 0 then
+    -- "magick" is availabel since imagemagick v7
+    -- https://askubuntu.com/a/1315605
+    imgdiffexe = "magick compare"
+  else
+    errorlevel = os.execute("command -v compare 2>&1 >/dev/null")
+    if errorlevel == 0 then
+      imgdiffexe = "compare"
+    end
+  end
+end
+imgdiffexe = os.getenv("imgdiffexe") or imgdiffexe
+
 local failed = {}
 
 local md5 = require("md5")
@@ -110,6 +130,7 @@ local function saveimgmd5(imgname, md5file, newmd5)
 end
 
 local function ppmcheckpdf(job)
+  rm(testdir, "*.diff.png")
   local errorlevel
   local imgname = job .. imgext
   local md5file = testfiledir .. "/" .. job .. ".md5"
@@ -123,17 +144,16 @@ local function ppmcheckpdf(job)
       errorlevel = 1
       print("  " .. imgname .. "          --> failed")
       failed[#failed + 1] = imgname
-      local imgdiffexe = os.getenv("imgdiffexe")
-      if imgdiffexe then
+      if arg[1] == "save" then
+        saveimgmd5(imgname, md5file, newmd5)
+      elseif imgdiffexe then
         local oldimg = abspath(testfiledir) .. "/" .. imgname
         local newimg = abspath(testdir) .. "/" .. imgname
         local diffname = job .. ".diff.png"
-        local cmd = imgdiffexe .. " " .. oldimg .. " " .. newimg
-                    .. " -compose src " .. diffname
-        print("  creating image diff file " .. diffname)
+        local cmd = imgdiffexe .. " -compose src " .. 
+                      oldimg .. " " .. newimg .. " " .. diffname
+        print("Creating image diff file " .. diffname)
         run(testdir, cmd)
-      elseif arg[1] == "save" then
-        saveimgmd5(imgname, md5file, newmd5)
       end
     end
   else
@@ -172,7 +192,12 @@ end
 
 local errorlevel = main()
 if errorlevel ~= 0 then
-  print("\n  PPM Checks failed with images\n")
+  if arg[1] == "save" then
+    errorlevel = 0
+    print("\n  PPM check files saved for\n")
+  else
+    print("\n  PPM checks failed with images\n")
+  end
   for _, i in ipairs(failed) do
     print("  - " .. i)
   end