building-from-source.adoc

Building PdfShow From Source

Build: Prerequisites

On all platforms you need JDK ({current-java-ver}+) and Apache Maven installed. On Windows jpackage has a couple of pre-requisites, which it will let you know about if they’re not already installed.

If I have been using a pre-release of darwinsys-api, which I often do, you will also have to clone https://github.com/IanDarwin/darwinsys-api, then cd darwinsys-api; mvn package install which should install the latest darwinsys-api into your ~/.m2/repository.

Then in pdfshow you can do mvn package, or open it in your Maven-aware IDE and run Main.java

Build: Making Installable Packages

On Linux, for RPMs, you need rpm-build or you will get told that 'rpm' is an invalid type (sudo dnf install rpm-build). On Linux, for DEBs, you need fakeroot (sudo apt install fakeroot).

The install formats are:

Table 1. The Installer Formats

OS	Default Format	Other formats with mkinstaller -t
macOS (Apple Silicon only)	DMG, with copy-to-Applications iconage.	pkg
Linux	rpm and deb	-
Windows	MSI installer	exe

Getting Source

Download the repository from {gh-url}.

Install Apache-Maven if not already installed.

Using command-line tools:

git clone https://github.com/IanDarwin/pdfshow
cd pdfshow

Using IntelliJ IDEA

From the startup screen, "Get from Version Control"
Enter the URL https://github.com/IanDarwin/pdfshow and click Clone
Accept or choose the directory and click Clone
On "Open or Import" popup (with choice of how to open), select "Maven Project"

Using Eclipse (no longer actively tested):

Window->Show View->Git->Git Repositories.
In the Repos window, Clone (the third icon at the right side of this window).
Enter the URL https://github.com/IanDarwin/pdfshow and click Next
On the next dialog, be sure to check Import Existing Projects before Next.
PdfShow should show up in the Package Explorer

Trial Runs

To try out the program in a supported, Maven-enabled Java IDE, just open and run Main.java. If you use some other IDE, and get it working, please submit a pull request with that IDE’s config files, as long as it doesn’t require changing the directory structure (i.e., moving existing files around).

To run the program in command-line Maven, use mvn exec:java.

Packaging

To make a JAR file with just the program and its images (without the dependencies), do mvn package.

To make a clickable runnable JAR file, run mvn package assembly:single. You’ll then find a jar with dependencies in the target folder. It’ll be named something like target/pdfshow-x.y.z-SNAPSHOT-jar-with-dependencies.jar. You can run it with java -jar target/pdfshow*dependencies.jar (see scripts/pdfshow), or just click on it in a file manager window in most windowed environments.

The full-blown, platform-specific installers we release are built by the mkinstaller script. This makes a clickable runnable JAR file as above and then runs the Java jpackage tool. You can run that script yourself if you want. You can only build the Mac installer on macOS, the Windows installer on Windows, etc.

Configuring a Linux rpm-based system and building PDFShow

This may not be optimal, but should work. Newer versions may be available.

sudo dnf search jdk

Pick and install the latest (probably 23; N.B. 21 did not work as they forgot to install the jmod files, which are needed to build the installers).

sudo dnf install rpm-build

mkdir git
cd git
git clone https://github.com/IanDarwin/pdfshow

Some Linux systems' packaging have Maven depending on dark ages' JDK-1.8; if yours does, do:

cd ~/Downloads
curl -o apache-maven-3.8.4-bin.tar.gz \
	https://dlcdn.apache.org/maven/maven-3/3.8.4/binaries/apache-maven-3.8.4-bin.tar.gz
cd /usr/local; sudo tar xzvf ~/Downloads/apache-maven-3.8.4.tar.gz
PATH=$PATH:/usr/local/apache-maven-3.8.4/bin

Then you can build it.

cd pdfshow
mkinstaller # If some tests fail on Linux with infra-related errs, don't care: add -s

This should create an installer or two in the pdfshow directory.

Contributing / Development

Fork the repo, clone your forked copy, make changes, test changes, send a pull request.

FAQ

Q: Why didn’t I use this for the drawing:

PDPageContentStream contentStream = new PDPageContentStream(document, page);
contentStream.setNonStrokingColor(Color.DARK_GRAY);
contentStream.addRect(200, 650, 100, 100);

A: The problem is that it would be much harder (if not impossible) to implement Undo processing when using that approach. Perhaps a later Save PDF function could insert the GObjects into the PDF using this technique.

Q: Why not use the built-in contains() method for hit detection?

A: The GObject hierarchy is intentionally light-weight, not JComponent, and it’s gotta be the same amount of work.