[nongnu] elpa/pdf-tools 24e7095bfe: Test and Documentation changes: dockerfiles and readme

[ELPA Syncer]

branch: elpa/pdf-tools
commit 24e7095bfe191638f41494804ad16633a08eaa27
Author: Vedang Manerikar <ved.manerikar@gmail.com>
Commit: Vedang Manerikar <ved.manerikar@gmail.com>

    Test and Documentation changes: dockerfiles and readme
    
    README changes:
    - Add documentation on how to test / add support for your favorite
    operating system.
    
    Dockerfile changes:
    - Rename Dockerfile.in to Dockerfile.common.in, to make the name
    clearer.
    - Add make as a prerequisite in the Dockerfile.
      + It is needed to run make commands and is not available in some of
      these images.
    - Add make targets for printing operating systems that are not yet
    supported in Docker testing.
      + This should help contributors with adding support for testing on
      these systems.
      + New targets are `server-test-supported` and
      `server-test-unsupported` at the top level.
    
    Related to: #130
---
 Makefile                                           |  6 +++++
 README.org                                         | 26 +++++++++++++++++++---
 server/test/Makefile                               | 13 +++++++++--
 .../{Dockerfile.in => Dockerfile.common.in}        |  0
 .../test/docker/templates/debian-10.Dockerfile.in  |  4 +++-
 .../test/docker/templates/debian-11.Dockerfile.in  |  4 +++-
 .../test/docker/templates/debian-9.Dockerfile.in   |  4 +++-
 .../test/docker/templates/fedora-34.Dockerfile.in  |  3 ++-
 .../test/docker/templates/fedora-35.Dockerfile.in  |  3 ++-
 .../test/docker/templates/fedora-36.Dockerfile.in  |  3 ++-
 .../docker/templates/freebsd.Dockerfile.in.FAILING |  0
 .../docker/templates/macos.Dockerfile.in.FAILING   |  0
 .../docker/templates/msys2.Dockerfile.in.FAILING   |  0
 .../docker/templates/nixos.Dockerfile.in.FAILING   |  0
 .../docker/templates/openbsd.Dockerfile.in.FAILING |  0
 .../templates/opensuse.Dockerfile.in.FAILING       |  0
 .../test/docker/templates/ubuntu-18.Dockerfile.in  |  4 ++--
 .../test/docker/templates/ubuntu-20.Dockerfile.in  |  4 ++--
 .../test/docker/templates/ubuntu-22.Dockerfile.in  |  4 ++--
 .../docker/templates/void.Dockerfile.in.FAILING    |  0
 20 files changed, 61 insertions(+), 17 deletions(-)

diff --git a/Makefile b/Makefile
index b206e8e7be..f776884c74 100644
--- a/Makefile
+++ b/Makefile
@@ -95,3 +95,9 @@ server-clean:
 
 server-distclean:
        ! [ -f server/Makefile ] || $(MAKE) -C server distclean
+
+server-test-supported: server/test/Makefile
+       $(MAKE) -C server/test print
+
+server-test-unsupported: server/test/Makefile
+       $(MAKE) -C server/test print-failing
diff --git a/README.org b/README.org
index a999186849..7c8d01c02c 100644
--- a/README.org
+++ b/README.org
@@ -32,7 +32,7 @@ Actually, displaying PDF files is just one part of 
~pdf-tools~. Since ~poppler~
 Installing this package via NonGNU ELPA or MELPA or any of the other package 
managers is straightforward and should just work.
 ~pdf-tools~ requires a server ~epdfinfo~ to run against, which it will try to 
compile and build when it is activated for the first time.
 
-You should not require any manual changes. The documentation below is *only if 
you are installing from source*, or for troubleshooting / debugging purposes.
+You should not require any manual changes. The documentation below is *only if 
you are installing from source*, or for troubleshooting / debugging purposes. 
The following steps need to be followed *in this order*, to install ~pdf-tools~ 
and ~epdfinfo~ correctly:
 
 - [[brain-child:8ce3cf4e-d186-4de1-a40e-f41063068ab0][Installing ~epdfinfo~ 
server prerequisites]]
 - [[brain-child:e305cd0a-e798-4c2b-af27-21bcd936c1c9][Installing the 
~epdfinfo~ server]]
@@ -541,7 +541,7 @@ L/R scrolling breaks while zoomed into a pdf, with usage of 
sublimity smooth scr
 #+end_src
 Toggling debug mode prints information about various operations in the 
~*Messages*~ buffer, and this is useful to see what is happening behind the 
scenes
 
-** Run basic tests locally
+** Run Emacs lisp tests locally
 :PROPERTIES:
 :CREATED:  [2022-05-09 Mon 21:27]
 :ID:       1CBE7325-A5A1-479B-9A98-BEEFBAC9D8FF
@@ -549,6 +549,25 @@ Toggling debug mode prints information about various 
operations in the ~*Message
 You can go to the ~pdf-tools~ folder and run ~make test~ to run the ERT tests 
and check if the changes you have made to the code break any of the tests.
 
 The tests are written in ERT, which is the built-in testing system in Emacs. 
However, they are run using ~Cask~ which you will have to install first, if you 
don't have it already. You can install ~Cask~ by following the instructions on 
their site at https://github.com/cask/cask
+** Run server compilation tests locally
+:PROPERTIES:
+:CREATED:  [2022-07-20 Wed 16:42]
+:ID:       5327945D-9D92-4462-8172-7237DEF4C359
+:END:
+You can go to the ~pdf-tools~ folder and run ~make server-test~ to check if 
the changes you have made to the server code break compilation on any of the 
supported operating systems.
+
+The tests build ~Podman~ images for all supported operating systems, so you 
will have to install ~Podman~ first, if you don't have already. You can install 
~Podman~ by following the instructions on their site at 
https://podman.io/getting-started/installation
+
+Podman is compatible with Docker, so if you already have ~docker~ installed, 
you should be able to ~alias podman=docker~ on your shell and run the tests, 
without having to install Docker. (Note: I have not tested this)
+
+** Add a Dockerfile to automate server compilation testing
+:PROPERTIES:
+:CREATED:  [2022-07-20 Wed 16:52]
+:ID:       A401543C-308B-4175-8212-5B78CD6C8389
+:END:
+The ~server/test/docker~ folder contains Dockerfile templates used for testing 
that the ~epdfinfo~ server compiles correctly on various operating systems 
([[id:5327945D-9D92-4462-8172-7237DEF4C359][more details here]]).
+
+To see the list of operating systems where compilation testing is supported, 
run ~make server-test-supported~. To see the list of operating systems where 
testing is unsupported, run ~make server-test-unsupported~. To add support, 
look into the ~server/test/docker/templates~ folder (~ubuntu~ files are a good 
example to refer to)
 
 * FAQs
 :PROPERTIES:
@@ -584,12 +603,13 @@ I'm working on automating ~pdf-tools~ installation as 
much as possible, in order
 1. Add a call to ~os_myfavos~ under ~handle-options~ at the end of the 
existing call chain. Here we try and pick up the correct Operating System and 
install the relevant dependencies.
 2. Add handling for the ~--os~ argument in ~os_argument~ for ~myfavos~, so 
that the appropriate function can be called to install pre-requisites. ~--os~ 
is the argument that we pass to the script from the command-line to indicate 
which OS we are on.
 3. Create a ~os_myfavos~ function. This function checks if we are running on 
MyFavOS. If we are running on MyFavOS, it sets up ~PKGCMD~, ~PKGARGS~ and 
~PACKAGES~ variables so that the appropriate package manager can install the 
dependencies as part of the rest of the ~autobuild~ script.
+4. If you are adding support for your favorite operating system, consider 
adding automated testing support as well, to help me ensure that ~epdfinfo~ 
continues to compile correctly. See 
[[id:A401543C-308B-4175-8212-5B78CD6C8389][Add a Dockerfile to automate server 
compilation testing]] for more details.
 
 The idea here is to make the ~server/autobuild~ file the single place from 
which installation can happen on any Operating System. This makes building 
~pdf-tools~ dead simple via the ~Makefile~.
 
 This seems like a lot of work, but it is not. If you need a reference, search 
for ~os_gentoo~ or ~os_debian~ in the ~server/autobuild~ file and see how these 
are setup and used. The functions are used to install dependencies on Gentoo 
and Debian respectively, and are simple to copy / change.
 
-When you make your changes, be sure to test them!
+When you make your changes, please be sure to test 
[[id:1CBE7325-A5A1-479B-9A98-BEEFBAC9D8FF][the elisp changes]] as well as 
[[id:5327945D-9D92-4462-8172-7237DEF4C359][the server code changes]] as 
described in the linked articles.
 
 ** I am on a Macbook M1 and ~pdf-tools~ installation fails with a stack-trace
 :PROPERTIES:
diff --git a/server/test/Makefile b/server/test/Makefile
index 5aafa40802..1520786afd 100644
--- a/server/test/Makefile
+++ b/server/test/Makefile
@@ -20,7 +20,7 @@ check: docker/test
 
 # Create the Dockerfile
 docker/%.Dockerfile: docker/templates/%.Dockerfile.in \
-                    docker/templates/Dockerfile.in
+       docker/templates/Dockerfile.common.in
        @echo Creating Dockerfile for target $*
        cat $^ > $@
 
@@ -52,4 +52,13 @@ clean: docker/clean
        rm -f -- docker/*.Dockerfile
 
 print:
-       @for os in $(DOCKER_OS); do echo $$os; done | sort
+       @echo List of Operating systems where server compilation is tested [via 
Docker]:
+       @for os in $(DOCKER_OS); do echo - $$os; done | sort
+
+print-failing: FAILING_OS := $(patsubst %.Dockerfile.in.FAILING, %, \
+       $(notdir $(wildcard docker/templates/*.Dockerfile.in.FAILING)))
+
+print-failing:
+       @echo List of Operating systems where server compilation is not tested:
+       @for os in $(FAILING_OS); do echo - $$os; done | sort
+       @echo PLEASE help support your favorite OS! More details at: 
https://pdftools.wiki/A401543C
diff --git a/server/test/docker/templates/Dockerfile.in 
b/server/test/docker/templates/Dockerfile.common.in
similarity index 100%
rename from server/test/docker/templates/Dockerfile.in
rename to server/test/docker/templates/Dockerfile.common.in
diff --git a/server/test/docker/templates/debian-10.Dockerfile.in 
b/server/test/docker/templates/debian-10.Dockerfile.in
index 2f01de7e74..a2ad6bb2e7 100644
--- a/server/test/docker/templates/debian-10.Dockerfile.in
+++ b/server/test/docker/templates/debian-10.Dockerfile.in
@@ -1,4 +1,6 @@
 # -*- dockerfile -*-
 # Debian 10 is known as buster
 FROM debian:10
-RUN apt-get update -y
+ARG DEBIAN_FRONTEND=noninteractive
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN apt-get update -y && apt-get install -y make tzdata
diff --git a/server/test/docker/templates/debian-11.Dockerfile.in 
b/server/test/docker/templates/debian-11.Dockerfile.in
index cabb29d98e..dae6b6c2c5 100644
--- a/server/test/docker/templates/debian-11.Dockerfile.in
+++ b/server/test/docker/templates/debian-11.Dockerfile.in
@@ -1,4 +1,6 @@
 # -*- dockerfile -*-
 # Debian 11 is known as bullseye
 FROM debian:11
-RUN apt-get update -y
+ARG DEBIAN_FRONTEND=noninteractive
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN apt-get update -y && apt-get install -y make tzdata
diff --git a/server/test/docker/templates/debian-9.Dockerfile.in 
b/server/test/docker/templates/debian-9.Dockerfile.in
index 8f6e34140b..b558ade515 100644
--- a/server/test/docker/templates/debian-9.Dockerfile.in
+++ b/server/test/docker/templates/debian-9.Dockerfile.in
@@ -1,4 +1,6 @@
 # -*- dockerfile -*-
 # Debian 9 is known as stretch
 FROM debian:9
-RUN apt-get update -y
+ARG DEBIAN_FRONTEND=noninteractive
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN apt-get update -y && apt-get install -y make tzdata
diff --git a/server/test/docker/templates/fedora-34.Dockerfile.in 
b/server/test/docker/templates/fedora-34.Dockerfile.in
index 42dc26d8bd..dbb736e145 100644
--- a/server/test/docker/templates/fedora-34.Dockerfile.in
+++ b/server/test/docker/templates/fedora-34.Dockerfile.in
@@ -1,3 +1,4 @@
 # -*- dockerfile -*-
 FROM fedora:34
-RUN dnf update -y
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN dnf update -y && dnf install -y make tzdata
diff --git a/server/test/docker/templates/fedora-35.Dockerfile.in 
b/server/test/docker/templates/fedora-35.Dockerfile.in
index 16a0eb3646..915cac41f9 100644
--- a/server/test/docker/templates/fedora-35.Dockerfile.in
+++ b/server/test/docker/templates/fedora-35.Dockerfile.in
@@ -1,3 +1,4 @@
 # -*- dockerfile -*-
 FROM fedora:35
-RUN dnf update -y
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN dnf update -y && dnf install -y make tzdata
diff --git a/server/test/docker/templates/fedora-36.Dockerfile.in 
b/server/test/docker/templates/fedora-36.Dockerfile.in
index e795d685bb..c36a716db2 100644
--- a/server/test/docker/templates/fedora-36.Dockerfile.in
+++ b/server/test/docker/templates/fedora-36.Dockerfile.in
@@ -1,3 +1,4 @@
 # -*- dockerfile -*-
 FROM fedora:36
-RUN dnf update -y
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN dnf update -y && dnf install -y make tzdata
diff --git a/server/test/docker/templates/freebsd.Dockerfile.in.FAILING 
b/server/test/docker/templates/freebsd.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/server/test/docker/templates/macos.Dockerfile.in.FAILING 
b/server/test/docker/templates/macos.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/server/test/docker/templates/msys2.Dockerfile.in.FAILING 
b/server/test/docker/templates/msys2.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/server/test/docker/templates/nixos.Dockerfile.in.FAILING 
b/server/test/docker/templates/nixos.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/server/test/docker/templates/openbsd.Dockerfile.in.FAILING 
b/server/test/docker/templates/openbsd.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/server/test/docker/templates/opensuse.Dockerfile.in.FAILING 
b/server/test/docker/templates/opensuse.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/server/test/docker/templates/ubuntu-18.Dockerfile.in 
b/server/test/docker/templates/ubuntu-18.Dockerfile.in
index 8f4cc6bc36..f49284d054 100644
--- a/server/test/docker/templates/ubuntu-18.Dockerfile.in
+++ b/server/test/docker/templates/ubuntu-18.Dockerfile.in
@@ -1,5 +1,5 @@
 # -*- dockerfile -*-
 FROM ubuntu:bionic
 ARG DEBIAN_FRONTEND=noninteractive
-# Need to install tzdata here to avoid stupid prompts when running package 
install via autobuild
-RUN apt-get update -y && apt-get install -y tzdata
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN apt-get update -y && apt-get install -y make tzdata
diff --git a/server/test/docker/templates/ubuntu-20.Dockerfile.in 
b/server/test/docker/templates/ubuntu-20.Dockerfile.in
index 515e5f5566..4b0d3a43ef 100644
--- a/server/test/docker/templates/ubuntu-20.Dockerfile.in
+++ b/server/test/docker/templates/ubuntu-20.Dockerfile.in
@@ -1,5 +1,5 @@
 # -*- dockerfile -*-
 FROM ubuntu:focal
 ARG DEBIAN_FRONTEND=noninteractive
-# Need to install tzdata here to avoid stupid prompts when running package 
install via autobuild
-RUN apt-get update -y && apt-get install -y tzdata
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN apt-get update -y && apt-get install -y make tzdata
diff --git a/server/test/docker/templates/ubuntu-22.Dockerfile.in 
b/server/test/docker/templates/ubuntu-22.Dockerfile.in
index 649752d846..217daed50b 100644
--- a/server/test/docker/templates/ubuntu-22.Dockerfile.in
+++ b/server/test/docker/templates/ubuntu-22.Dockerfile.in
@@ -1,5 +1,5 @@
 # -*- dockerfile -*-
 FROM ubuntu:jammy
 ARG DEBIAN_FRONTEND=noninteractive
-# Need to install tzdata here to avoid stupid prompts when running package 
install via autobuild
-RUN apt-get update -y && apt-get install -y tzdata
+# Need to install make, tzdata here to avoid stupid prompts when running 
package install via autobuild
+RUN apt-get update -y && apt-get install -y make tzdata
diff --git a/server/test/docker/templates/void.Dockerfile.in.FAILING 
b/server/test/docker/templates/void.Dockerfile.in.FAILING
new file mode 100644
index 0000000000..e69de29bb2