pdf2htmlEX/buildScripts

Building pdf2htmlEX

Because of its intimate use of specific versions of both Poppler and FontForge, cleanly building pdf2htmlEX is rather more complex than normal.

The (bash) scripts in this directory help automate this mutli-stage process.

For all but the most experienced programmers, we strongly encourage you to use these scripts to build pdf2htmlEX.

---

Table of contents

• TL;DR ...
  • Downloading precompiled versions
  • Building yourself
• The gory details ...
  • Top-level scripts
  • Individual steps
  • Helper files and scripts
• Yet more details?

---

TL;DR ...

Downloading precompiled versions

For most users, you probably really want to simply download one of the precompiled versions of pdf2htmlEX:

• AppImage : Download, make executable, and run...

  This will work on most Linuxes, and most recent Windows 10.

• Docker Image from the pdf2htmlEX Docker hub.

  This will work on any machine with Docker installed.

• Debian archive : Download, apt install locally, and run...

  This will work on any Debian based and most recent Windows 10 machines.

  Experienced users of Linux, may be able to repackage this *.deb for use with their favourite package management tool.

Building yourself

To build pdf2htmlEX on your own machine, inside the root directory of a fresh clone of the pdf2htmlEX/pdf2htmlEX repository, type:

    ./buildScripts/buildInstallLocally

This will automatically install all required development tools and libraries, and then proceed to download and statically compile the required versions of both Poppler and FontForge before compiling and installing pdf2htmlEX into /usr/local/bin.

NOTE: at the moment this will only work on machines with a Debian based distribution. such as Ubuntu, Linux Mint, etc.

The gory details ...

The bash scripts in this directory automate the download, build, install, test and upload steps required to provide a complete build/test/release cycle of pdf2htmlEX.

Each script can be used individually to re-run a particular step if needed.

Top-level scripts

Typically, most users, will run one of the following "top-level" scripts:

1. buildInstallLocally

   This will automate:

   1. the installation of all required development tools and libraries,

   2. download and statically compile the required versions of both Poppler and FontForge,

   3. compile and install pdf2htmlEX.

2. createImages

   Following a successful buildInstallLocally, this will create the following images:

   1. AppImage

   2. Docker image

   3. Debian archive

3. runTests

   Following a successful buildInstallLocally, this will run the various 'local' tests reporting errors as they occur.

   When run in Travis-ci, failing browser tests will not fail the overall Travis build, but will instead upload the test results to the GitHub Release page for later review.

4. uploadImages

   Following successful buildInstallLocally, createImages and runTests, this will automate the upload of the various artefacts to the pdf2htmlEX releases page, LaunchPad ppa and docker hub repository.

   Note that this step requires the user to enter passwords for each of the respective services. Most users will not need (or be able) to run this step.

5. travisLinuxDoItAll

   This script is used by the .travis.yml configuration to build, test and upload a complete pdf2htmlEX release cycle. It is essentially a compendium of all of the build scripts in the correct order.

Individual steps

• buildFontforge: Compiles a static version of libfontforge for use by pdf2htmlEX.

• buildPdf2htmlEX: Compiles and links pdf2htmlEX.

• buildPoppler: Compiles a static version of libpoppler and libpopper-glib for use by pdf2htmlEX.

• createAppImage: Using an already compiled version of pdf2htmlEX, installs it and popper-data into an AppImage.

• createDebianPackage: Using an already compiled version of pdf2htmlEX, installs it and poppler-data into a Debian archive (*.deb).

• createDockerImage: Using an already compile version of pdf2htmlEX, installs it and poppler-data into a Docker image.

• getBuildTools: Locally apt installs all development tools required to build pdf2htmlEX.

• getDevLibraries: Locally apt installs all development libraries required to build pdf2htmlEX.

  This script provides a definitive list of all libraries required to run pdf2htmlEX.

• getFontforge: Downloads and unpacks the version of FontForge specified in the FONTFORGE_VERSION environment variable into the pdf2htmlEX/fontoforge directory.

  The FONTFORGE_VERSION variable is specified in the versionEnvs script.

• getPoppler: Downloads and unpacks the version of Poppler specified in the POPPLER_VERSION environment variable into the pdf2htmlEX/poppler directory.

  The POPPLER_VERSION variable is specified in the versionEnvs script.

  The getPoppler script also downloads and unpacks the most recent version of poppler-data. Since poppler-data does not change very often, the correct version of poppler-data is specified in the getPoppler script itself.

• installPdf2htmlEX: Installs an already compiled version of pdf2htmlEX and poppler-data into the location specified by the PDF2HTMLEX_PREFIX environment variable.

  The PDF2HTMLEX_PREFIX variable is specified in the versionEnvs script.

• rutTests: Runs the tests located in the pdf2htmlEX/pdf2htmlEX/test directory. See the pdf2htmlEX/pdf2htmlEx/test directory's Readme file for details.

• uploadDebianArchive: Upload the pdf2htmlEX Debian archive to both the GitHub releases page, as well as the LaunchPad ppa.

  This script has not yet been implemented.

• uploadDockerImage: Upload the pdf2htmlEX Docker image to Docker hub repository associated to the docker hub users specified in the DOCKER_USERNAME environement variable.

  Unless the DOCKER_USERNAME and DOCKER_PASSWORD environment variables are pre-defined, this script will prompt the user for the respective values.

• uploadGitHubRelease: Upload the pdf2htmlEX artefacts (AppImage, Debian archive, test results, etc) to the continuous section of the release page associated with the TRAVIS_REPO_SLUG (user/project) environment variable.

  Unless the GITHUB_USERNAME, GITHUB_TOKEN, and TRAVIS_REPO_SLUG (user/project) environment variables are pre-defined, this script will prompt the user for the respective values.

Helper files and scripts

• versionEnvs: Specifies all of the evnironment variables required for a standard build of pdf2htmlEX. Changes in this script effect all of the other build scripts.

• reSourceVersionEnvs: This bash script is automatically generated by the build scripts as they are run. It records the values of all important environment variables required by the buildScripts. It is typcically sourced by each script before it preforms any actions.

• reportEnvs: Echos all important enviroment variables to the console. This script is used by the top-level scripts to ensure the current environment variables are listed before each build.

• uploadGitHubReleaseDSL: A collection of bash functions used by the uploadGitHubRelease script to automate the upload of release artefacts.

• uploadGitHubReleaseMessage: The contents of this text file is used by the uploadGitHubRelease script as the contents of the release message, as visible to the user, for the 'continuous' release section.

• dockerFunctions: A collection of bash functions used by the uploadDockerImage script to automate the upload of the Docker images to Docker Hub.

• listFilesByChangeTime: A simple bash script which lists the files in the buildScripts directory by most recently changed files first.

• Readme.md: This read me file.

Yet more details?

The various bash script files are meant to be fairly readable. They contain additional comments about what each step is meant to be doing.