Tweak spacing and wording

This commit is contained in:
Jay Berkenbilt 2018-02-24 21:37:30 -05:00
parent 7f29a9d7cc
commit a6f206ad01
3 changed files with 175 additions and 97 deletions

View File

@ -1,21 +1,9 @@
# Using the QPDF AppImage bundle (for Linux x86_64 systems only)
First advice:
Tips:
- After downloading, you have to set the executable bit for any AppImage (for security reasons
this is disabled by default): `chmod +x <name-of-application>.AppImage`
* After downloading, you have to set the executable bit for any AppImage (for security reasons this is disabled by default): `chmod +x <name-of-application>.AppImage`
- Run the QPDF AppImage with the '--usage' parameter to start learning some useful details about
built-in features of this specific AppImage.
* Run the QPDF AppImage with the `--ai-usage` parameter to start learning some useful details about built-in features of this specific AppImage.
More tips:
- You can rename the AppImage to any name allowed for file names on Linux. The '.AppImage' suffix
is not required for it to function. It will also work as expected if you invoke it from a
symlink. Using 'qpdf' as its filename or symlink name is OK. However, you may want to continue
using the QPDF package provided by your system's package manager side by side with the AppImage
bundle: in this case it is recommended to use 'qpdf.ai' as a short name for (or as the symlink
name to) the qpdf-<version>.AppImage.
- [...more tips to come... work in progress...]
* You can rename the AppImage to any name allowed for file names on Linux. The `.AppImage` suffix is not required for it to function. It will also work as expected if you invoke it from a symlink. Using `qpdf` as its filename or symlink name is OK. However, you may want to continue using the QPDF package provided by your system's package manager side by side with the AppImage bundle: in this case it is recommended to use `qpdf.ai` as a short name for (or as the symlink name to) the qpdf-<version>.AppImage.

View File

@ -5,32 +5,38 @@
#
# License: MIT
#
# The purpose of this custom AppRun script is to enable symlinking the AppImage and invoking the corresponding
# binary depending on which symlink name was used to invoke the AppImage.
# The purpose of this custom AppRun script is to enable symlinking the
# AppImage and invoking the corresponding binary depending on which
# symlink name was used to invoke the AppImage.
#
# At the same time it also allows to invoke the embedded binaries as 'sub-commands'. This is in the interest of
# saving users from creating extra symlinks (without preventing others from STILL using such, should they want
# or need these).
# At the same time it also allows to invoke the embedded binaries as
# 'sub-commands'. This is in the interest of saving users from
# creating extra symlinks (without preventing others from STILL using
# such, should they want or need these).
#
# It also provides some additional help parameters in order to allow faster familiarization with functionality
# embedded in this AppImage. For example it support the listing and viewing of embedded manpages, HTML files,
# PDF files, licenses and READMEs.
# It also provides some additional help parameters in order to allow
# faster familiarization with functionality embedded in this AppImage.
# For example it support the listing and viewing of embedded manpages,
# HTML files, PDF files, licenses and READMEs.
#
# Note, the AppImage can be renamed to anything what's 'legal' for an executable name under Linux or used via
# a symlink under any name and it should behave like 'qpdf' is expected to behave. If the symlink name is
# 'fix-qdf' or 'zlib-flate' it should behave like these...
# Note, the AppImage can be renamed to anything what's 'legal' for an
# executable name under Linux or used via a symlink under any name and
# it should behave like 'qpdf' is expected to behave. If the symlink
# name is 'fix-qdf' or 'zlib-flate' it should behave like these...
HERE="$(dirname "$(readlink -f "${0}")")"
# Set APPDIR and ARGV0 when running directly from the AppDir.
# Running from the AppDir can be beneficial when debugging the AppImage (or give performance improvements):
# Running from the AppDir can be beneficial when debugging the
# AppImage (or give performance improvements):
if [ -z $APPDIR ]; then
APPDIR="$HERE"
ARGV0="$0"
fi
# This is a semi-secret environment variable which can be set for debugging the AppImage.
# For now it is only meant for temporary use and may be removed again in the near future once things have
# This is a semi-secret environment variable which can be set for
# debugging the AppImage. For now it is only meant for temporary use
# and may be removed again in the near future once things have
# settled:
if [ "x$SET_BASH_X_FOR_APPRUN" == "xYeSS" ] ; then
set -x
@ -54,8 +60,9 @@ echo "
All QPDF command line functionality inside an AppImage package.
--------------------------------------------------------------------------
(This package uses the AppImage software packaging technology for Linux ['One App == One File']
for easy availability of the newest QPDF releases across all major Linux distributions.)
(This package uses the AppImage software packaging technology for
Linux ['One App == One File'] for easy availability of the newest
QPDF releases across all major Linux distributions.)
Usage:
------
@ -64,7 +71,8 @@ echo "
# Show help screen of QPDF itself
$ARGV0 --ai-usage
# This message (it's only present in the AppImage incarnation of QPDF)
# This message (it's only present in the AppImage
# incarnation of QPDF)
$ARGV0 fix-qdf|zlib-flate
# Run the named sub-command
@ -89,7 +97,8 @@ echo "
# List all PDF documents embedded in AppImage
$ARGV0 --pdf <path/to/file>
# Use system default PDF viewer to display embedded PDF document(s)
# Use system default PDF viewer to display embedded PDF
# document(s)
# (for list of available PDF files see \"$ARGV0 --list-pdf\")
$ARGV0 --list-readme
@ -103,10 +112,12 @@ echo "
# List all LICENSE files embedded in AppImage
$ARGV0 --license <name-of-license>
# Show content of LICENSE file embedded in AppImage (piped thru 'less -N')
# Show content of LICENSE file embedded in AppImage
# (piped thru 'less -N')
$ARGV0 --show-apprun|--self-show|--selfshow
# Show 'AppRun' invoked by 'less -N'; type '-N' to toogle line number display
# Show 'AppRun' invoked by 'less -N'; type '-N' to toggle
# line number display
$ARGV0 --appimage-help
# Show AppImage options available for all 'type 2' AppImages
@ -114,15 +125,17 @@ echo "
$ARGV0 --help
# Show help screen of QPDF itself
------------------------------------------------------------------------------------------------
NOTE: The execution of this AppImage is controlled by a custom AppRun script. The state of this
script is experimental and preliminary. Hence it may not work as expected, or miss some
functionality. You can hack on this script by unpacking this AppImage into a local sub directory
[currently named 'squashfs-root'] with this command:
------------------------------------------------------------------------------
NOTE: The execution of this AppImage is controlled by a custom AppRun
script. The state of this script is experimental and preliminary.
Hence it may not work as expected, or miss some functionality. You
can hack on this script by unpacking this AppImage into a local
subdirectory [currently named 'squashfs-root'] with this command:
$ARGV0 --appimage-extract
After you're done with your hacks, repackage the AppImage again with this command:
After you're done with your hacks, repackage the AppImage again with
this command:
appimagetool [/path/to/]squashfs-root [/path/to/]QPDF-*.AppImage
@ -131,7 +144,7 @@ echo "
* https://github.com/AppImage/AppImageUpdate/releases/ and
* https://github.com/AppImage/zsync2/releases and
* https://github.com/probonopd/linuxdeployqt/releases/
------------------------------------------------------------------------------------------------
------------------------------------------------------------------------------
"
}
@ -168,14 +181,30 @@ esac
}
if [ x"$1" == "xshow-apprun" -o x"$1" == "x--show-apprun" -o x"$1" == "x--apprunshow" -o x"$1" == "x--apprun-show" -o x"$1" == "xselfshow" -o x"$1" == "x--selfshow" -o x"$1" == "xself-show" -o x"$1" == "x--self-show" -o x"$1" == "x--show-self" -o x"$1" == "x--showself" -o x"$1" == "xshow-self" -o x"$1" == "xshowself" ] ; then
if [ x"$1" == "xshow-apprun" -o \
x"$1" == "x--show-apprun" -o \
x"$1" == "x--apprunshow" -o \
x"$1" == "x--apprun-show" -o \
x"$1" == "xselfshow" -o \
x"$1" == "x--selfshow" -o \
x"$1" == "xself-show" -o \
x"$1" == "x--self-show" -o \
x"$1" == "x--show-self" -o \
x"$1" == "x--showself" -o \
x"$1" == "xshow-self" -o \
x"$1" == "xshowself" ] ; then
cd "$HERE"
less -N AppRun
exit $?
fi
if [ x"$1" == "xlistlicense" -o x"$1" == "x--listlicense" -o x"$1" == "xlist-license" -o x"$1" == "x--list-license" -o x"$1" == "x--licenselist" -o x"$1" == "x--license-list" ] ; then
if [ x"$1" == "xlistlicense" -o \
x"$1" == "x--listlicense" -o \
x"$1" == "xlist-license" -o \
x"$1" == "x--list-license" -o \
x"$1" == "x--licenselist" -o \
x"$1" == "x--license-list" ] ; then
cd "$HERE"
echo ""
echo "You may invoke \"$ARGV0\" with one of the following additional arguments."
@ -187,14 +216,22 @@ if [ x"$1" == "xlistlicense" -o x"$1" == "x--listlicense" -o x"$1" == "xlist-li
fi
if [ "x$1" == "xai-usage" -o "x$1" == "x--aiusage" -o "x$1" == "x--ai-usage" -o "x$1" == "x-u" ] ; then
if [ x"$1" == "xai-usage" -o \
x"$1" == "x--aiusage" -o \
x"$1" == "x--ai-usage" -o \
x"$1" == "x-u" ] ; then
usage | less
#usage
exit $?
fi
if [ x"$1" == "xlistman" -o x"$1" == "x--listman" -o x"$1" == "xlist-man" -o x"$1" == "x--list-man" -o x"$1" == "x--manlist" -o x"$1" == "x--man-list" ] ; then
if [ x"$1" == "xlistman" -o \
x"$1" == "x--listman" -o \
x"$1" == "xlist-man" -o \
x"$1" == "x--list-man" -o \
x"$1" == "x--manlist" -o \
x"$1" == "x--man-list" ] ; then
cd "$HERE"
echo ""
echo "You may invoke \"$ARGV0\" with one of the following additional arguments."
@ -206,7 +243,12 @@ if [ x"$1" == "xlistman" -o x"$1" == "x--listman" -o x"$1" == "xlist-man" -o x"$
fi
if [ x"$1" == "xlistexe" -o x"$1" == "x--listexe" -o x"$1" == "xlist-exe" -o x"$1" == "x--list-exe" -o x"$1" == "x--exelist" -o x"$1" == "x--exe-list" ] ; then
if [ x"$1" == "xlistexe" -o \
x"$1" == "x--listexe" -o \
x"$1" == "xlist-exe" -o \
x"$1" == "x--list-exe" -o \
x"$1" == "x--exelist" -o \
x"$1" == "x--exe-list" ] ; then
cd "$HERE"
echo ""
echo "You may invoke \"$ARGV0\" with one of the following additional arguments."
@ -220,7 +262,12 @@ if [ x"$1" == "xlistexe" -o x"$1" == "x--listexe" -o x"$1" == "xlist-exe" -o x"$
fi
if [ x"$1" == "xlistreadme" -o x"$1" == "x--listreadme" -o x"$1" == "xlist-readme" -o x"$1" == "x--list-readme" -o x"$1" == "x--readmelist" -o x"$1" == "x--readme-list" ] ; then
if [ x"$1" == "xlistreadme" -o \
x"$1" == "x--listreadme" -o \
x"$1" == "xlist-readme" -o \
x"$1" == "x--list-readme" -o \
x"$1" == "x--readmelist" -o \
x"$1" == "x--readme-list" ] ; then
cd "$HERE"
echo ""
echo "You may invoke \"$ARGV0\" with one of the following additional arguments."
@ -232,7 +279,12 @@ if [ x"$1" == "xlistreadme" -o x"$1" == "x--listreadme" -o x"$1" == "xlist-readm
fi
if [ x"$1" == "xlisthtml" -o x"$1" == "x--listhtml" -o x"$1" == "xlist-html" -o x"$1" == "x--list-html" -o x"$1" == "x--htmllist" -o x"$1" == "x--html-list" ] ; then
if [ x"$1" == "xlisthtml" -o \
x"$1" == "x--listhtml" -o \
x"$1" == "xlist-html" -o \
x"$1" == "x--list-html" -o \
x"$1" == "x--htmllist" -o \
x"$1" == "x--html-list" ] ; then
cd "$HERE"
echo ""
echo "You may invoke \"$ARGV0\" with one of the following additional arguments."
@ -244,7 +296,12 @@ if [ x"$1" == "xlisthtml" -o x"$1" == "x--listhtml" -o x"$1" == "xlist-html" -o
fi
if [ x"$1" == "xlistpdf" -o x"$1" == "x--listpdf" -o x"$1" == "xlist-pdf" -o x"$1" == "x--list-pdf" -o x"$1" == "x--pdflist" -o x"$1" == "x--pdf-list" ] ; then
if [ x"$1" == "xlistpdf" -o \
x"$1" == "x--listpdf" -o \
x"$1" == "xlist-pdf" -o \
x"$1" == "x--list-pdf" -o \
x"$1" == "x--pdflist" -o \
x"$1" == "x--pdf-list" ] ; then
cd "$HERE"
echo ""
echo "You may invoke \"$ARGV0\" with one of the following additional arguments."
@ -256,7 +313,8 @@ if [ x"$1" == "xlistpdf" -o x"$1" == "x--listpdf" -o x"$1" == "xlist-pdf" -o x"$
fi
if [ x"$1" == "xreadme" -o x"$1" == "x--readme" ] ; then
if [ x"$1" == "xreadme" -o \
x"$1" == "x--readme" ] ; then
cd "$HERE"
shift
echo ""
@ -287,7 +345,8 @@ if [ x"$1" == "xreadme" -o x"$1" == "x--readme" ] ; then
fi
if [ x"$1" == "xlicense" -o x"$1" == "x--license" ] ; then
if [ x"$1" == "xlicense" -o \
x"$1" == "x--license" ] ; then
cd "$HERE"
shift
echo ""
@ -489,4 +548,3 @@ else
fi
fi

View File

@ -2,39 +2,45 @@
# Copyright (c) 2018 Jay Berkenbilt and Kurt Pfeifle
#
# This script is mainly meant to build an 'AppImage' from GitHub sources of QPDF via Travis CI on an
# Ubuntu Trusty (14.04) LTS system (see https://appimage.org/).
# This script is mainly meant to build an 'AppImage' from GitHub
# sources of QPDF via Travis CI on an Ubuntu Trusty (14.04) LTS system
# (see https://appimage.org/).
#
# But it also allows Linux users to build such an AppImage on their own systems. Please read
# 'README.md' from the top level Git sources to see what preconditions you must meet to build QPDF
# in general. The same apply to build an AppImage. Then follow these three steps:
# But it also allows Linux users to build such an AppImage on their
# own systems. Please read 'README.md' from the top level Git sources
# to see what preconditions you must meet to build QPDF in general.
# The same apply to build an AppImage. Then follow these three steps:
#
# 1. Clone Git sources: `git clone https://github.com/qpdf/qpdf.git git.qpdf`
# 2. Change into git dir: `cd git.qpdf`
# 3. Run this script: `bash appimage/build-appimage`
#
# The resulting AppImage will be placed in './appimage/build/QPDF-x86_64.AppImage'.
# Read the output of the script for hints in case something goes wrong.
# The resulting AppImage will be placed in
# './appimage/build/QPDF-x86_64.AppImage'. Read the output of the
# script for hints in case something goes wrong.
#
# You may pass custom options for the configure step by setting them into the 'CUSTOM_CONFIGURE'
# environment variable and exporting it before running this script. For example:
# You may pass custom options for the configure step by setting them
# into the 'CUSTOM_CONFIGURE' environment variable and exporting it
# before running this script. For example:
#
# export CUSTOM_CONFIGURE=" --enable-test-compare-images [--more-other-options]"
#
# ATTENTION:
#
# 1. To build the AppImage you should have a working internet connection.
# Reason: the script downloads the most recent 'linuxdeployqt' utility for building the AppImage.
# 2. If you build the AppImage on a too recent Linux distribution, it may only work on the exact
# distribution you build it on. For an AppImage to work on a wide range of different
# distributions from the last 3-4 years if should be built on Ubuntu Trusty (14.04).
# 1. To build the AppImage you should have a working internet
# connection. Reason: the script downloads the most recent
# 'linuxdeployqt' utility for building the AppImage.
# 2. If you build the AppImage on a too recent Linux distribution,
# it may only work on the exact distribution you build it on. For
# an AppImage to work on a wide range of different distributions
# from the last 3-4 years if should be built on Ubuntu Trusty
# (14.04).
set -ex
# Support for signing the AppImage (only by original maintainer):
sign=
if [ "x$1" == "x--sign" ] ; then
if [ "x$1" == "x--sign" ]; then
sign=--sign
fi
@ -46,14 +52,18 @@ _osversion=$(cat /etc/os-release | grep PRETTY_NAME | awk -F'=' '{print $2}' | s
if [ x"$_osversion" != x"Ubuntu 14.04.5 LTS" ] ; then
set +x
echo ""
echo "+==============================================================================================================+"
echo "|| WARNING: You are about to build a QPDF AppImage on a system which is NOT Ubuntu 14.04.5 LTS ('Trusty'). ||"
echo "|| ||"
echo "|| Very likely you use a newer Linux distribution. ||"
echo "|| The resulting AppImage will not be 'universally' usable. ||"
echo "|| Hence, it likely will not be capable of running on a large range of Linux distributions. ||"
echo "|| It will only reliably run on the very same systems it has been created on, and maybe some similar ones. ||"
echo "+==============================================================================================================+"
# 0 1 2 3 4 5 6 7
# 01234567890123456789012345678901234567890123456789012345678901234567890123456789
echo "+===========================================================================+"
echo "|| WARNING: You are about to build a QPDF AppImage on a system which is ||"
echo "|| NOT Ubuntu 14.04 LTS ('Trusty'). ||"
echo "|| ||"
echo "|| It is recommended that you use a distribution that is at least a ||"
echo "|| few years old to maximize the number of Linux distributions the ||"
echo "|| resulting AppImage will work on. AppImages often don't work on ||"
echo "|| distributions older than the one they were built on because of ||"
echo "|| standard library differences. ||"
echo "+===========================================================================+"
echo ""
set -x
fi
@ -74,7 +84,9 @@ rm -rf $here/build
# Prepare build of QPDF from sources:
./autogen.sh
./configure --prefix=/usr --enable-werror --enable-show-failed-test-output --enable-html-doc --enable-pdf-doc "$CUSTOM_CONFIGURE"
./configure --prefix=/usr --enable-werror \
--enable-show-failed-test-output \
--enable-html-doc --enable-pdf-doc "$CUSTOM_CONFIGURE"
# Build!
make -j$(nproc)
@ -86,7 +98,7 @@ make check
mkdir -p $appdir
# Install build result into AppDir:
make install DESTDIR=$appdir ; find $appdir
make install DESTDIR=$appdir; find $appdir
# Change into build directory:
cd $here/build
@ -95,18 +107,35 @@ cd $here/build
rm -rf appdir/usr/include appdir/usr/lib/pkgconfig appdir/usr/lib/*.{a,la,so}
# Copy icon which is needed for desktop integration into place:
for i in appdir/usr/share/icons/hicolor/512x512/apps ; do
for i in appdir/usr/share/icons/hicolor/512x512/apps; do
mkdir -p $i
cp $top/logo/qpdf.png $i
done
# Copy .desktop and .appdata.xml metadata for desktop integration into place:
for i in appdir/usr/share/applications ; do mkdir -p $i ; cp $top/appimage/qpdf.desktop $i ; done
for i in appdir/usr/share/metainfo ; do mkdir -p $i ; cp $top/appimage/qpdf.appdata.xml $i ; done
for i in appdir/usr/share/doc/qpdf ; do mkdir -p $i ; cp $top/README* $i ; cp $top/NOTICE.md $i/README-notice.md ; cp $top/LICENSE.txt $i ; cp $top/Artistic-2.0 $i/Artistic-LICENSE.txt ; cp $top/ChangeLog $i/README-ChangeLog ; cp $top/TODO $i/README-todo ; done
for i in appdir/usr/share/applications; do
mkdir -p $i
cp $top/appimage/qpdf.desktop $i
done
for i in appdir/usr/share/metainfo; do
mkdir -p $i
cp $top/appimage/qpdf.appdata.xml $i
done
for i in appdir/usr/share/doc/qpdf; do
mkdir -p $i
cp $top/README* $i
cp $top/NOTICE.md $i/README-notice.md
cp $top/LICENSE.txt $i
cp $top/Artistic-2.0 $i/Artistic-LICENSE.txt
cp $top/ChangeLog $i/README-ChangeLog
cp $top/TODO $i/README-todo
done
# The following lines are experimental (for debugging; and to test support for unexpected future binaries added to QPDF):
for i in /usr/bin/env /bin/less /bin/busybox ; do cp $i appdir/usr/bin/ ; done
# The following lines are experimental (for debugging; and to test
# support for unexpected future binaries added to QPDF):
for i in /usr/bin/env /bin/less /bin/busybox; do
cp $i appdir/usr/bin/
done
ls -l /usr/bin/env /bin/less /bin/busybox
# Fetch 'linuxdeployqt' which will transform the AppDir into an AppImage:
@ -114,7 +143,7 @@ wget -c "https://github.com/probonopd/linuxdeployqt/releases/download/continuous
chmod a+x linuxdeployqt*.AppImage
# Set up a clean environment:
unset QTDIR ; unset QT_PLUGIN_PATH ; unset LD_LIBRARY_PATH
unset QTDIR; unset QT_PLUGIN_PATH; unset LD_LIBRARY_PATH
# Let 'linuxdeployqt' do its first stage of work:
./linuxdeployqt*.AppImage appdir/usr/share/applications/*.desktop -bundle-non-qt-libs
@ -122,11 +151,13 @@ unset QTDIR ; unset QT_PLUGIN_PATH ; unset LD_LIBRARY_PATH
# In addition to the main executable, we have additional ones to process
./linuxdeployqt*.AppImage appdir/usr/bin/zlib-flate -bundle-non-qt-libs
# To eventually generate the AppImage we extract the linuxdeployqt AppImage to get access to the embedded 'appimagetool':
# To eventually generate the AppImage we extract the linuxdeployqt
# AppImage to get access to the embedded 'appimagetool':
./linuxdeployqt*.AppImage --appimage-extract
# We want to run our custom AppRun script:
rm appdir/AppRun ; cp $top/appimage/AppRun appdir ; chmod a+x appdir/AppRun # Replace symlink with custom script
# We want to run our custom AppRun script.
# Replace symlink with custom script
rm appdir/AppRun; cp $top/appimage/AppRun appdir; chmod a+x appdir/AppRun
# If we are not on Ubuntu Trusty, we need to disable 'appstreamcli' validation:
if [ x"$_osversion" == x"Ubuntu 14.04.5 LTS" ] ; then
@ -136,8 +167,10 @@ else
set +x
echo ""
echo " Running 'appimagetool' with '-n' parameter..."
echo " Reason: this does not seem to be a Travis CI build running on Ubuntu Trusty 14.04."
echo " '-n' disables checking of AppStream data by the 'appstreamcli' utility since post-Trusty versions have incompatible changes."
echo " Reason: this does not seem to be a Travis CI build running on"
echo " Ubuntu Trusty 14.04."
echo " '-n' disables checking of AppStream data by the 'appstreamcli'"
echo " utility since post-Trusty versions have incompatible changes."
echo ""
set -x
fi
@ -147,16 +180,15 @@ MAJOR_QPDF_VERSION=$( ./appdir/usr/bin/qpdf --version | grep "qpdf version" | aw
VERSION=${MAJOR_QPDF_VERSION}-continuous-${TRAVIS_JOB_NUMBER}-$(date "+%Y-%m-%d")-git.$(git rev-parse --short HEAD)-x86_64
# Remove the default AppRun/symlink and use our own custom AppRun script
rm appdir/AppRun ; cp $top/appimage/AppRun appdir; chmod a+x appdir/AppRun
rm appdir/AppRun; cp $top/appimage/AppRun appdir; chmod a+x appdir/AppRun
set +x
# Finally, generate the AppImage:
PATH=./squashfs-root/usr/bin:$PATH ./squashfs-root/usr/bin/appimagetool $sign -g $appimagetool_param appdir qpdf-$VERSION.AppImage
PATH=./squashfs-root/usr/bin:$PATH ./squashfs-root/usr/bin/appimagetool $sign -g $appimagetool_param appdir qpdf-$VERSION-x86_64.AppImage
# Tell everyone where our result is stored:
echo ""
echo "===================================================================================="
echo "============================================================================="
echo " === AppImage is ready in $top/appimage/build ==="
echo "===================================================================================="
echo "============================================================================="
echo ""