Initial instructions for Package Manuskript for Linux with PyInstaller

Curtis Gedak 2017-08-14 17:23:56 -06:00
parent 962c6f6958
commit de9963c052

@ -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.