mirror of
https://github.com/pdf2htmlEX/pdf2htmlEX.git
synced 2024-12-22 13:00:08 +00:00
added more comprehensive documentation for the build scripts
This commit is contained in:
Stephen Gaito
parent
6f38dfffeb
commit
3f45343ba4
253
buildScripts/Readme.md
Normal file
253
buildScripts/Readme.md
Normal file
@ -0,0 +1,253 @@
|
|||||||
|
# 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 ...](#tldr-)
|
||||||
|
- [Downloading precompiled versions](#http://localhost:5000/Readme.md#downloading-precompiled-versions-downloads)
|
||||||
|
- [Building yourself](#http://localhost:5000/Readme.md#building-yourself)
|
||||||
|
- [The gory details ...](#http://localhost:5000/Readme.md#the-gory-details-)
|
||||||
|
- [Top-level scripts](#http://localhost:5000/Readme.md#top-level-scripts)
|
||||||
|
- [Individual steps](#http://localhost:5000/Readme.md#individual-steps)
|
||||||
|
- [Helper files and scripts](http://localhost:5000/Readme.md#helper-files-and-scripts)
|
||||||
|
- [Yet more details?](http://localhost:5000/Readme.md#yet-more-details)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TL;DR ...
|
||||||
|
|
||||||
|
### Downloading precompiled versions {#Downloads}
|
||||||
|
|
||||||
|
For most users, you probably really want to simply download one of the
|
||||||
|
[precompiled versions of
|
||||||
|
`pdf2htmlEX`](https://github.com/pdf2htmlEX/pdf2htmlEX/releases):
|
||||||
|
|
||||||
|
- [AppImage](https://appimage.org/) : Download, make executable, and
|
||||||
|
run...
|
||||||
|
|
||||||
|
This will work on most Linuxes, and most recent Windows 10.
|
||||||
|
|
||||||
|
- [Docker](https://www.docker.com/) Image from the [`pdf2htmlEX` Docker
|
||||||
|
hub](https://hub.docker.com/orgs/pdf2htmlex/repositories).
|
||||||
|
|
||||||
|
This will work on any machine with Docker installed.
|
||||||
|
|
||||||
|
- [Debian archive](https://en.wikipedia.org/wiki/Dpkg) : Download,
|
||||||
|
[apt](https://en.wikipedia.org/wiki/APT_(software)) install locally,
|
||||||
|
and run...
|
||||||
|
|
||||||
|
This will work on any [Debian](https://www.debian.org/) 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](https://github.com/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](https://www.debian.org/) based distribution. such as
|
||||||
|
[Ubuntu](https://ubuntu.com/), [Linux Mint](https://linuxmint.com/), 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
|
||||||
|
|
||||||
|
However, 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](https://travis-ci.org/), 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 `source`d 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.
|
||||||
|
|
||||||
@ -1,6 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# This bash script clean all pdf2htmlEX build products
|
|
||||||
|
|
||||||
cd pdf2htmlEX
|
|
||||||
rm -rf build pdf2htmlEX.1 share/*.css share/*.js share/*.min.* src/pdf2htmlEX-config.h src/util/css_const.h
|
|
||||||
@ -1,25 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# This bash script automates the process of getting the original pdf2htmlEX
|
|
||||||
# source
|
|
||||||
|
|
||||||
PDF2HTMLEX_BRANCH=update-poppler
|
|
||||||
|
|
||||||
echo ""
|
|
||||||
echo "-------------------------------------------------------------------"
|
|
||||||
echo "GETTING pdf2htmlEX sources (using wget)"
|
|
||||||
echo " (PDF2HTMLEX_BRANCH: [$PDF2HTMLEX_BRANCH])"
|
|
||||||
echo "-------------------------------------------------------------------"
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
set -ev
|
|
||||||
|
|
||||||
wget https://codeload.github.com/stephengaito/pdf2htmlEX/zip/$PDF2HTMLEX_BRANCH
|
|
||||||
|
|
||||||
mv $PDF2HTMLEX_BRANCH $PDF2HTMLEX_BRANCH.zip
|
|
||||||
|
|
||||||
sudo apt install unzip
|
|
||||||
|
|
||||||
unzip $PDF2HTMLEX_BRANCH.zip
|
|
||||||
|
|
||||||
mv pdf2htmlEX-$PDF2HTMLEX_BRANCH pdf2htmlEX
|
|
||||||
Loading…
Reference in New Issue
Block a user