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

.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,15 @@ local configname = "config-old"
 testdir = testdir .. "-" .. configname
 
 local imgext = imgext or ".png"
+-- https://stackoverflow.com/questions/592620/how-can-i-check-if-a-program-exists-from-a-bash-script
+-- https://github.com/gpoore/minted/pull/345
+local imgdiffexe
+if os.type ~= "windows" then
+  local status, output = os.execute("command -v magick 2>&1 >/dev/null")
+  if status == 0 then
+    imgdiffexe = "magick"
+  end
+end
 imgdiffexe = os.getenv("imgdiffexe") or imgdiffexe
 
 local failed = {}
@@ -129,9 +138,9 @@ local function ppmcheckpdf(job)
         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 .. " compare -compose src " .. 
+                      oldimg .. " " .. newimg .. " " .. diffname
+        print("Creating image diff file " .. diffname)
         run(testdir, cmd)
       elseif arg[1] == "save" then
         saveimgmd5(imgname, md5file, newmd5)