added more comprehensive documentation for the build scripts
This commit is contained in:
Stephen Gaito
parent
6f38dfffeb
commit
3f45343ba4
|
|
@ -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