From de9963c05288e8fddcfbececd70c78cf7d452c65 Mon Sep 17 00:00:00 2001 From: Curtis Gedak Date: Mon, 14 Aug 2017 17:23:56 -0600 Subject: [PATCH] Initial instructions for Package Manuskript for Linux with PyInstaller --- ...e-Manuskript-for-Linux-with-PyInstaller.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 Package-Manuskript-for-Linux-with-PyInstaller.md diff --git a/Package-Manuskript-for-Linux-with-PyInstaller.md b/Package-Manuskript-for-Linux-with-PyInstaller.md new file mode 100644 index 0000000..a703088 --- /dev/null +++ b/Package-Manuskript-for-Linux-with-PyInstaller.md @@ -0,0 +1,190 @@ +# SUMMARY + +This guide describes the steps for packaging **Manuskript** for Linux. The resulting package runs on x86-64 bit Linux computers only. + +# CONSIDERATIONS + +Before embarking on this procedure consider creating a clean 64-bit Virtual Machine for the purpose of creating Manuskript PyInstaller packages. The reasons are three-fold: + +- Need to use oldest version of Linux you plan to support. See [Making Linux Apps Forward-Compatible](https://pyinstaller.readthedocs.io/en/stable/usage.html#making-linux-apps-forward-compatible). +- Ensure no QT4 installed on system. Otherwise pyinstaller attempts to include unneeded QT4 in the package if QT4 is found on the system. See [PyQt5.QtCore and PyQt4.QtCore modules both wrap the QObject class](https://github.com/pyinstaller/pyinstaller/issues/2174). +- [Binary package wheels are provided for Python v3.5 and later for 64-bit Linux, OS X and 32-bit and 64-bit Windows](https://www.riverbankcomputing.com/software/pyqt/download5). + +Users with 32-bit Linux will need to run Manuskript from source code. See [Run Manuskript from Source Code on Linux](https://github.com/olivierkes/manuskript/wiki/Run-Manuskript-from-Source-Code-on-Linux). + +_Note: I chose to create a Debian 8 Jessie 64-bit VM in order to support manuskript on a large number of currently supported GNU/Linux distros. At time of writing, Debian Jessie was the current oldStable release._ + +# INSTALLATION + +## Install Manuskript + +A working version of Manuskipt is required. If creating an official release, then download and extract an [official source code release zip or tarball file](https://github.com/olivierkes/manuskript/releases). + + unzip manuskript-#.#.#.zip + +Be sure to include optional software such as Markdown and PyEnchant so that these are included in the package. + + sudo apt install python3-markdown python3-pyenchant + +See [Run Manuskript from Source Code on Linux](https://github.com/olivierkes/manuskript/wiki/Run-Manuskript-from-Source-Code-on-Linux). + +## Install Prerequisite Software Packages + +Install all the necessary software required for creating the manuskript package. + + 1. Install zip + + sudo apt install zip + + 2. Install pip, PyInstaller and PyQt5 + + sudo apt install python3-pip + sudo pip3 install pyinstaller + +# PACKAGE CREATION + +Create a zip file package that can be installed and run on x86-64 computers. + + 1. Create the Manuskript package. + + cd manuskript + python3 /usr/local/bin/pyinstaller manuskript.spec + + This should create a self-contained directory called `dist` under the current working directory. + + 2. Create a zip file using the manuskript files under the `dist` directory. + + cd dist + zip -r manuskript-#.#.#{-#}-linux64.zip ./manuskript + + Note that the `-#` within the curly braces is optional. It is used to indicate updated packages of the same manuskript `#-#-#` version. The curly braces are not included in the file name. + + For example: + + First packaging of manuskript v0.4.0 would be named: + + manuskript-0.4.0-linux64.zip + + Second repackaging of manuskript v0.4.0 would be named: + + manuskript-0.4.0-1-linux64.zip + +# PACKAGE TEST INSTALLATION + +Use the following steps on a different computer or Virtual Machine to test that the manuskript package works. + + 1. Copy the manuksript-#.#.#{-#}-linux64.zip file and extract. + + unzip manuskript-#.#.#{-#}-linux64.zip + + 2. Install a different language dictionary (e.g. French). + + sudo apt install aspell-fr + + 3. Install pandoc for more export format options. + + sudo apt install pandoc + + 4. Run manuskript and open a project. + + ./manuskript/manuskript + # Open a project + + 5. Check for extra language dictionaries (e.g., French). + + # Check *Tools -> Dictionary* for French "fr" dictionaries. + + 6. Check for additional pandoc export options. + + # Select *File -> Compile* + # Check *Export to:* drop down for pandoc export options. + + 7. Exit manuskript. + +# REFERENCES + +- [Using PyInstaller](https://pyinstaller.readthedocs.io/en/stable/usage.html) +- [What is PyQT?](https://riverbankcomputing.com/software/pyqt/intro) + +--- + +# APPENDIX A: DISTRO TEST RESULTS + +These test results are for the [manuskript-0.4.0-1-linux64.zip](https://sourceforge.net/projects/manuskript/files/manuskript-0.4.0/manuskript-0.4.0-1-linux64.zip/download) package created using the above steps. + + 64 Bit Linux | Manuskript | Spellcheck | Pandoc + Distro | Runs? | Works? [1] | Works? [2] + --------------+------------+------------+----------- + Debian 8 | Yes | Yes | Yes + Debian 9 | **No** [3] | | + Fedora 25 | Yes | **No** | Yes + openSUSE 42.2 | Yes | Yes | Yes + Xubuntu 14.04 | Yes | Yes | Yes + Kubuntu 16.04 | Yes | Yes | Yes + +[1] Install spelling dictionary package to use spell checker. For example for English install the package `aspell-en`. + +[2] Install `pandoc` package to access additional Compile/Export formats, such as LaTeX and ePub. + +[3] Segmentation fault occurs when trying to run `manuskript-0.4.0-1-linux64.zip` on Debian 9 Stretch. + +Note that some warning messages are displayed on some distros when running from the command line; however, these do not appear to affect manuskript operation. + +## DISTRO MESSAGES + +Following are additional details about warning messages observed during testing. + +### Debian 8 Jessie + +No warning messages. + +### Debian 9 Stretch + +Segmentation fault occurs when trying to run `manuskript-0.4.0-1-linux64.zip` on Debian 9 Stretch. + +Users with Debian 9 Stretch will need to run Manuskript from source code. See [Run Manuskript from Source Code on Linux](https://github.com/olivierkes/manuskript/wiki/Run-Manuskript-from-Source-Code-on-Linux). + +### Fedora 25 + +Warning messages displayed: + + (manuskript:2886): Gtk-WARNING **: Unable to locate theme engine in module_path: "adwaita", + + (manuskript:2886): Gtk-WARNING **: Unable to locate theme engine in module_path: "pixmap", + + ... + + ** (manuskript:2886): WARNING **: Error loading plugin: /home/fedora/manuskript/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by /usr/lib64/enchant/libenchant_myspell.so) + + libGL error: unable to load driver: swrast_dri.so + libGL error: failed to load driver: swrast + +These warning messages do not adversely impact the operation of manuskript. Howerver it should be noted that spellcheck did not work. + +### openSUSE 42.2 Leap + +Warning messages displayed: + + libGL error: unable to load driver: swrast_dri.so + libGL error: failed to load driver: swrast + +These warning messages do not adversely impact the operation of manuskript. + +### Xubuntu 14.04 LTS (Trusty Tahr) + +Warning messages displayed: + + libGL error: unable to load driver: swrast_dri.so + libGL error: failed to load driver: swrast + +These warning messages do not adversely impact the operation of manuskript. + +### Kubuntu 16.04 LTS (Xenial Xerus) + +Warning messages displayed: + + ** (process:6886): WARNING **: Error loading plugin: /home/gedakc/Downloads/manuskript/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required by /usr/lib/x86_64-linux-gnu/enchant/libenchant_ispell.so) + + ** (process:6886): WARNING **: Error loading plugin: /home/gedakc/Downloads/manuskript/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required by /usr/lib/x86_64-linux-gnu/enchant/libenchant_ispell.so) + +These warning messages do not adversely impact the operation of manuskript.